Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 231 insertions, 0 deletions

diff --git a/man/man3/realpath.3 b/man/man3/realpath.3
new file mode 100644
index 0000000..581edf8
--- /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 2024-05-02 "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)