diff options
Diffstat (limited to 'man/man3/realpath.3')
| -rw-r--r-- | man/man3/realpath.3 | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/man/man3/realpath.3 b/man/man3/realpath.3 new file mode 100644 index 000000000..512807217 --- /dev/null +++ b/man/man3/realpath.3 @@ -0,0 +1,231 @@ +'\" t +.\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Rewritten old page, 990824, aeb@cwi.nl +.\" 2004-12-14, mtk, added discussion of resolved_path == NULL +.\" +.TH realpath 3 (date) "Linux man-pages (unreleased)" +.SH NAME +realpath \- return the canonicalized absolute pathname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <limits.h> +.B #include <stdlib.h> +.P +.BI "char *realpath(const char *restrict " path , +.BI " char *restrict " resolved_path ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR realpath (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR realpath () +expands all symbolic links and resolves references +to +.IR "/./" ", " "/../" +and extra \[aq]/\[aq] +characters in the null-terminated string named by +.I path +to produce a canonicalized absolute pathname. +The resulting pathname is stored as a null-terminated string, +up to a maximum of +.B PATH_MAX +bytes, +in the buffer pointed to by +.IR resolved_path . +The resulting path will have no symbolic link, +.I "/./" +or +.I "/../" +components. +.P +If +.I resolved_path +is specified as NULL, then +.BR realpath () +uses +.BR malloc (3) +to allocate a buffer of up to +.B PATH_MAX +bytes to hold the resolved pathname, +and returns a pointer to this buffer. +The caller should deallocate this buffer using +.BR free (3). +.\" Even if we use resolved_path == NULL, then realpath() will still +.\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX +.\" bytes -- MTK, Dec 04 +.SH RETURN VALUE +If there is no error, +.BR realpath () +returns a pointer to the +.IR resolved_path . +.P +Otherwise, it returns NULL, the contents +of the array +.I resolved_path +are undefined, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Read or search permission was denied for a component of the path prefix. +.TP +.B EINVAL +.I path +is NULL. +.\" (In libc5 this would just cause a segfault.) +(Before glibc 2.3, +this error is also returned if +.I resolved_path +is NULL.) +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded +.B NAME_MAX +characters, or an entire pathname exceeded +.B PATH_MAX +characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR realpath () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS GNU extensions +If the call fails with either +.B EACCES +or +.B ENOENT +and +.I resolved_path +is not NULL, then the prefix of +.I path +that is not readable or does not exist is returned in +.IR resolved_path . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.4BSD, POSIX.1-2001, Solaris. +.P +POSIX.1-2001 says that the behavior if +.I resolved_path +is NULL is implementation-defined. +POSIX.1-2008 specifies the behavior described in this page. +.P +In 4.4BSD and Solaris, the limit on the pathname length is +.B MAXPATHLEN +(found in \fI<sys/param.h>\fP). +SUSv2 prescribes +.B PATH_MAX +and +.BR NAME_MAX , +as found in \fI<limits.h>\fP or provided by the +.BR pathconf (3) +function. +A typical source fragment would be +.P +.in +4n +.EX +#ifdef PATH_MAX + path_max = PATH_MAX; +#else + path_max = pathconf(path, _PC_PATH_MAX); + if (path_max <= 0) + path_max = 4096; +#endif +.EE +.in +.P +(But see the BUGS section.) +.\".P +.\" 2012-05-05, According to Casper Dik, the statement about +.\" Solaris was not true at least as far back as 1997, and +.\" may never have been true. +.\" +.\" The 4.4BSD, Linux and SUSv2 versions always return an absolute +.\" pathname. +.\" Solaris may return a relative pathname when the +.\" .I path +.\" argument is relative. +.\" The prototype of +.\" .BR realpath () +.\" is given in \fI<unistd.h>\fP in libc4 and libc5, +.\" but in \fI<stdlib.h>\fP everywhere else. +.SH BUGS +The POSIX.1-2001 standard version of this function is broken by design, +since it is impossible to determine a suitable size for the output buffer, +.IR resolved_path . +According to POSIX.1-2001 a buffer of size +.B PATH_MAX +suffices, but +.B PATH_MAX +need not be a defined constant, and may have to be obtained using +.BR pathconf (3). +And asking +.BR pathconf (3) +does not really help, since, on the one hand POSIX warns that +the result of +.BR pathconf (3) +may be huge and unsuitable for mallocing memory, +and on the other hand +.BR pathconf (3) +may return \-1 to signify that +.B PATH_MAX +is not bounded. +The +.I "resolved_path\ ==\ NULL" +feature, not standardized in POSIX.1-2001, +but standardized in POSIX.1-2008, allows this design problem to be avoided. +.\" .P +.\" The libc4 and libc5 implementation contained a buffer overflow +.\" (fixed in libc-5.4.13). +.\" Thus, set-user-ID programs like +.\" .BR mount (8) +.\" needed a private version. +.SH SEE ALSO +.BR realpath (1), +.BR readlink (2), +.BR canonicalize_file_name (3), +.BR getcwd (3), +.BR pathconf (3), +.BR sysconf (3) |