mirror of https://github.com/mkerrisk/man-pages
181 lines
4.9 KiB
Groff
181 lines
4.9 KiB
Groff
.\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl)
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" Rewritten old page, 990824, aeb@cwi.nl
|
|
.\" 2004-12-14, mtk, added discussion of resolved_path == NULL
|
|
.\"
|
|
.TH REALPATH 3 2004-12-14 "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
realpath \- return the canonicalized absolute pathname
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <limits.h>
|
|
.B #include <stdlib.h>
|
|
.sp
|
|
.BI "char *realpath(const char *" path ", char *" resolved_path );
|
|
.SH DESCRIPTION
|
|
.BR realpath ()
|
|
expands all symbolic links and resolves references
|
|
to
|
|
.IR '/./' ", " '/../'
|
|
and extra
|
|
.I '/'
|
|
characters in the null terminated string named by
|
|
.I path
|
|
and stores the canonicalized absolute pathname in the buffer of size
|
|
.B PATH_MAX
|
|
named by
|
|
.IR resolved_path .
|
|
The resulting path will have no symbolic link,
|
|
.I '/./'
|
|
or
|
|
.I '/../'
|
|
components.
|
|
.SH "RETURN VALUE"
|
|
If there is no error,
|
|
.BR realpath ()
|
|
returns a pointer to the
|
|
.IR resolved_path .
|
|
|
|
Otherwise it returns a NULL pointer, and the contents
|
|
of the array
|
|
.I resolved_path
|
|
are undefined. The global variable
|
|
.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
|
|
Either
|
|
.I path
|
|
or
|
|
.I resolved_path
|
|
is NULL. (In libc5 this would just cause a segfault.)
|
|
But, see NOTES below.
|
|
.TP
|
|
.B EIO
|
|
An I/O error occurred while reading from the file system.
|
|
.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 ENOTDIR
|
|
A component of the path prefix is not a directory.
|
|
.SH NOTES
|
|
The glibc implementation of
|
|
.BR realpath ()
|
|
provides a non-standard extension.
|
|
If
|
|
.I resolved_path
|
|
is specified as NULL, then
|
|
.BR realpath ()
|
|
uses
|
|
.BR malloc (3)
|
|
to allocate a buffer of up to 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 BUGS
|
|
Avoid using this function. It is broken by design since (unless
|
|
using the non-standard
|
|
.I "resolved_path\ ==\ NULL"
|
|
feature) it is
|
|
impossible to determine a suitable size for the output buffer,
|
|
.IR resolved_path .
|
|
According to POSIX a buffer of size PATH_MAX suffices, but
|
|
PATH_MAX need not be a defined constant, and may have to be
|
|
obtained using
|
|
.BR pathconf ().
|
|
And asking
|
|
.BR pathconf ()
|
|
does not really help, since on the one hand POSIX warns that
|
|
the result of
|
|
.BR pathconf ()
|
|
may be huge and unsuitable for mallocing memory. And on the other
|
|
hand
|
|
.BR pathconf ()
|
|
may return \-1 to signify that PATH_MAX is not bounded.
|
|
.LP
|
|
The libc4 and libc5 implementation contains a buffer overflow
|
|
(fixed in libc-5.4.13).
|
|
Thus, set-user-ID programs like mount need a private version.
|
|
.SH HISTORY
|
|
The
|
|
.BR realpath ()
|
|
function first appeared in 4.4BSD, contributed by Jan-Simon Pendry.
|
|
In Linux this function appears in libc 4.5.21.
|
|
.SH "CONFORMING TO"
|
|
4.4BSD, POSIX.1-2001.
|
|
|
|
In 4.4BSD and Solaris the limit on the pathname length is MAXPATHLEN
|
|
(found in <sys/param.h>).
|
|
SUSv2 prescribes PATH_MAX and
|
|
NAME_MAX, as found in <limits.h> or provided by the
|
|
.BR pathconf ()
|
|
function.
|
|
A typical source fragment would be
|
|
.LP
|
|
.RS
|
|
.nf
|
|
#ifdef PATH_MAX
|
|
path_max = PATH_MAX;
|
|
#else
|
|
path_max = pathconf(path, _PC_PATH_MAX);
|
|
if (path_max <= 0)
|
|
path_max = 4096;
|
|
#endif
|
|
.fi
|
|
.RE
|
|
(But see the BUGS section.)
|
|
.LP
|
|
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 <unistd.h> in libc4 and libc5,
|
|
but in <stdlib.h> everywhere else.
|
|
.SH "SEE ALSO"
|
|
.BR readlink (2),
|
|
.BR canonicalize_file_name (3),
|
|
.BR getcwd (3),
|
|
.BR pathconf (3),
|
|
.BR sysconf (3)
|