Merging upstream version 6.8.

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

1 files changed, 311 insertions, 0 deletions

diff --git a/man/man3/getcwd.3 b/man/man3/getcwd.3
new file mode 100644
index 0000000..ea3c4cf
--- /dev/null
+++ b/man/man3/getcwd.3
@@ -0,0 +1,311 @@
+'\" t
+.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Wed Jul 21 22:35:42 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified 18 Mar 1996 by Martin Schulze (joey@infodrom.north.de):
+.\"   Corrected description of getwd().
+.\" Modified Sat Aug 21 12:32:12 MET 1999 by aeb - applied fix by aj
+.\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb
+.\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi <rl@hellgate.ch>
+.\"
+.TH getcwd 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getcwd, getwd, get_current_dir_name \- get current working directory
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "char *getcwd(char " buf [. size "], size_t " size );
+.B "char *get_current_dir_name(void);"
+.P
+.BI "[[deprecated]] char *getwd(char " buf [PATH_MAX]);
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR get_current_dir_name ():
+.nf
+    _GNU_SOURCE
+.fi
+.P
+.BR getwd ():
+.nf
+    Since glibc 2.12:
+        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
+            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
+            || /* glibc <= 2.19: */ _BSD_SOURCE
+    Before glibc 2.12:
+        _BSD_SOURCE || _XOPEN_SOURCE >= 500
+.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+.fi
+.SH DESCRIPTION
+These functions return a null-terminated string containing an
+absolute pathname that is the current working directory of
+the calling process.
+The pathname is returned as the function result and via the argument
+.IR buf ,
+if present.
+.P
+The
+.BR getcwd ()
+function copies an absolute pathname of the current working directory
+to the array pointed to by
+.IR buf ,
+which is of length
+.IR size .
+.P
+If the length of the absolute pathname of the current working directory,
+including the terminating null byte, exceeds
+.I size
+bytes, NULL is returned, and
+.I errno
+is set to
+.BR ERANGE ;
+an application should check for this error, and allocate a larger
+buffer if necessary.
+.P
+As an extension to the POSIX.1-2001 standard, glibc's
+.BR getcwd ()
+allocates the buffer dynamically using
+.BR malloc (3)
+if
+.I buf
+is NULL.
+In this case, the allocated buffer has the length
+.I size
+unless
+.I size
+is zero, when
+.I buf
+is allocated as big as necessary.
+The caller should
+.BR free (3)
+the returned buffer.
+.P
+.BR get_current_dir_name ()
+will
+.BR malloc (3)
+an array big enough to hold the absolute pathname of
+the current working directory.
+If the environment
+variable
+.B PWD
+is set, and its value is correct, then that value will be returned.
+The caller should
+.BR free (3)
+the returned buffer.
+.P
+.BR getwd ()
+does not
+.BR malloc (3)
+any memory.
+The
+.I buf
+argument should be a pointer to an array at least
+.B PATH_MAX
+bytes long.
+If the length of the absolute pathname of the current working directory,
+including the terminating null byte, exceeds
+.B PATH_MAX
+bytes, NULL is returned, and
+.I errno
+is set to
+.BR ENAMETOOLONG .
+(Note that on some systems,
+.B PATH_MAX
+may not be a compile-time constant;
+furthermore, its value may depend on the filesystem, see
+.BR pathconf (3).)
+For portability and security reasons, use of
+.BR getwd ()
+is deprecated.
+.SH RETURN VALUE
+On success, these functions return a pointer to a string containing
+the pathname of the current working directory.
+In the case of
+.BR getcwd ()
+and
+.BR getwd ()
+this is the same value as
+.IR buf .
+.P
+On failure, these functions return NULL, and
+.I errno
+is set to indicate the error.
+The contents of the array pointed to by
+.I buf
+are undefined on error.
+.SH ERRORS
+.TP
+.B EACCES
+Permission to read or search a component of the filename was denied.
+.TP
+.B EFAULT
+.I buf
+points to a bad address.
+.TP
+.B EINVAL
+The
+.I size
+argument is zero and
+.I buf
+is not a null pointer.
+.TP
+.B EINVAL
+.BR getwd ():
+.I buf
+is NULL.
+.TP
+.B ENAMETOOLONG
+.BR getwd ():
+The size of the null-terminated absolute pathname string exceeds
+.B PATH_MAX
+bytes.
+.TP
+.B ENOENT
+The current working directory has been unlinked.
+.TP
+.B ENOMEM
+Out of memory.
+.TP
+.B ERANGE
+The
+.I size
+argument is less than the length of the absolute pathname of the
+working directory, including the terminating null byte.
+You need to allocate a bigger array and try again.
+.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 getcwd (),
+.BR getwd ()
+T}	Thread safety	MT-Safe
+T{
+.na
+.nh
+.BR get_current_dir_name ()
+T}	Thread safety	MT-Safe env
+.TE
+.SH VERSIONS
+POSIX.1-2001 leaves the behavior of
+.BR getcwd ()
+unspecified if
+.I buf
+is NULL.
+.P
+POSIX.1-2001
+does not define any errors for
+.BR getwd ().
+.SH VERSIONS
+.SS C library/kernel differences
+On Linux, the kernel provides a
+.BR getcwd ()
+system call, which the functions described in this page will use if possible.
+The system call takes the same arguments as the library function
+of the same name, but is limited to returning at most
+.B PATH_MAX
+bytes.
+(Before Linux 3.12,
+.\" commit 3272c544da48f8915a0e34189182aed029bd0f2b
+the limit on the size of the returned pathname was the system page size.
+On many architectures,
+.B PATH_MAX
+and the system page size are both 4096 bytes,
+but a few architectures have a larger page size.)
+If the length of the pathname of the current working directory
+exceeds this limit, then the system call fails with the error
+.BR ENAMETOOLONG .
+In this case, the library functions fall back to
+a (slower) alternative implementation that returns the full pathname.
+.P
+Following a change in Linux 2.6.36,
+.\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74
+the pathname returned by the
+.BR getcwd ()
+system call will be prefixed with the string "(unreachable)"
+if the current directory is not below the root directory of the current
+process (e.g., because the process set a new filesystem root using
+.BR chroot (2)
+without changing its current directory into the new root).
+Such behavior can also be caused by an unprivileged user by changing
+the current directory into another mount namespace.
+When dealing with pathname from untrusted sources, callers of the
+functions described in this page
+should consider checking whether the returned pathname starts
+with '/' or '(' to avoid misinterpreting an unreachable path
+as a relative pathname.
+.SH STANDARDS
+.TP
+.BR getcwd ()
+POSIX.1-2008.
+.TP
+.BR get_current_dir_name ()
+GNU.
+.TP
+.BR getwd ()
+None.
+.SH HISTORY
+.TP
+.BR getcwd ()
+POSIX.1-2001.
+.TP
+.BR getwd ()
+POSIX.1-2001, but marked LEGACY.
+Removed in POSIX.1-2008.
+Use
+.BR getcwd ()
+instead.
+.P
+Under Linux, these functions make use of the
+.BR getcwd ()
+system call (available since Linux 2.1.92).
+On older systems they would query
+.IR /proc/self/cwd .
+If both system call and proc filesystem are missing, a
+generic implementation is called.
+Only in that case can
+these calls fail under Linux with
+.BR EACCES .
+.SH NOTES
+These functions are often used to save the location of the current working
+directory for the purpose of returning to it later.
+Opening the current
+directory (".") and calling
+.BR fchdir (2)
+to return is usually a faster and more reliable alternative when sufficiently
+many file descriptors are available, especially on platforms other than Linux.
+.SH BUGS
+Since the Linux 2.6.36 change that added "(unreachable)" in the
+circumstances described above, the glibc implementation of
+.BR getcwd ()
+has failed to conform to POSIX and returned a relative pathname when the API
+contract requires an absolute pathname.
+With glibc 2.27 onwards this is corrected;
+calling
+.BR getcwd ()
+from such a pathname will now result in failure with
+.BR ENOENT .
+.SH SEE ALSO
+.BR pwd (1),
+.BR chdir (2),
+.BR fchdir (2),
+.BR open (2),
+.BR unlink (2),
+.BR free (3),
+.BR malloc (3)