<<< Previous | Home | Next >>>

The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008
Copyright © 2001-2008 The IEEE and The Open Group

#### NAME

> realpath - resolve a pathname

#### SYNOPSIS

> ``[XSI] #include <stdlib.h>
> char *realpath(const char *restrict` file_name`,
> char *restrict` resolved_name`);``
> `
> `

#### DESCRIPTION

> The realpath() function shall derive, from the pathname pointed to by file_name, an absolute pathname that resolves to the same directory entry, whose resolution does not involve `'.'` , `'..'` , or symbolic links. If resolved_name is a null pointer, the generated pathname shall be stored as a null-terminated string in a buffer allocated as if by a call to malloc(). Otherwise, if {PATH_MAX} is defined as a constant in the <limits.h> header, then the generated pathname shall be stored as a null-terminated string, up to a maximum of {PATH_MAX} bytes, in the buffer pointed to by resolved_name.

> If resolved_name is not a null pointer and {PATH_MAX} is not defined as a constant in the <limits.h> header, the behavior is undefined.

#### RETURN VALUE

> Upon successful completion, realpath() shall return a pointer to the buffer containing the resolved name. Otherwise, realpath() shall return a null pointer and set errno to indicate the error.

> If the resolved_name argument is a null pointer, the pointer returned by realpath() can be passed to free().

> If the resolved_name argument is not a null pointer and the realpath() function fails, the contents of the buffer pointed to by resolved_name are undefined.

#### ERRORS

> The realpath() function shall fail if:

> [EACCES]
>   Read or search permission was denied for a component of file_name.
> [EINVAL]
>   The file_name argument is a null pointer.
> [EIO]
>   An error occurred while reading from the file system.
> [ELOOP]
>   A loop exists in symbolic links encountered during resolution of the file_name argument.
> [ENAMETOOLONG]
>   The length of a component of a pathname is longer than {NAME_MAX}.
> [ENOENT]
>   A component of file_name does not name an existing file or file_name points to an empty string.
> [ENOTDIR]
>   A component of the path prefix is not a directory, or the file_name argument contains at least one non- <slash> character and ends with one or more trailing <slash> characters and the last pathname component names an existing file that is neither a directory nor a symbolic link to a directory.

> The realpath() function may fail if:

> [ELOOP]
>   More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the file_name argument.
> [ENAMETOOLONG]
>   The length of a pathname exceeds {PATH_MAX}, or pathname resolution of a symbolic link produced an intermediate result with a length that exceeds {PATH_MAX}.
> [ENOMEM]
>   Insufficient storage space is available.

The following sections are informative.

#### EXAMPLES

> ##### Generating an Absolute Pathname

> The following example generates an absolute pathname for the file identified by the symlinkpath argument. The generated pathname is stored in the buffer pointed to by actualpath.

>     #include <stdlib.h>
>     ...
>     char *symlinkpath = "/tmp/symlink/file";
>     char *actualpath;

>     actualpath = realpath(symlinkpath, NULL);
>     if (actualpath != NULL)
>     {
>         ... use actualpath ...

>         free(actualpath);
>     }
>     else
>     {
>         ... handle error ...
>     }

#### APPLICATION USAGE

> For functions that allocate memory as if by malloc(), the application should release such memory when it is no longer required by a call to free(). For realpath(), this is the return value.

#### RATIONALE

> Since realpath() has no length argument, if {PATH_MAX} is not defined as a constant in <limits.h>, applications have no way of determining how large a buffer they need to allocate for it to be safe to pass to realpath(). A {PATH_MAX} value obtained from a prior pathconf() call is out-of-date by the time realpath() is called. Hence the only reliable way to use realpath() when {PATH_MAX} is not defined in <limits.h> is to pass a null pointer for resolved_name so that realpath() will allocate a buffer of the necessary size.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> fpathconf , free , getcwd , sysconf

> XBD <limits.h> , <stdlib.h>

#### CHANGE HISTORY

> First released in Issue 4, Version 2.

#### Issue 5

> Moved from X/OPEN UNIX extension to BASE.

#### Issue 6

> The restrict keyword is added to the realpath() prototype for alignment with the ISO/IEC 9899:1999 standard.

> The wording of the mandatory [ELOOP] error condition is updated, and a second optional [ELOOP] error condition is added.

> IEEE Std 1003.1-2001/Cor 1-2002, item XSH/TC1/D6/51 is applied, adding new text to the DESCRIPTION for the case when resolved_name is a null pointer, changing the [EINVAL] error text, adding text to the RATIONALE, and adding text to FUTURE DIRECTIONS.

> IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/110 is applied, updating the ERRORS section to refer to the file_name argument, rather than a nonexistent path argument.

#### Issue 7

> Austin Group Interpretation 1003.1-2001 #143 is applied.

> This function is updated for passing a null pointer to realpath() for the resolved_name argument.

> The APPLICATION USAGE section is updated to clarify that memory is allocated as if by malloc().

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2008 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]

<<< Previous | Home | Next >>>