diff options
Diffstat (limited to 'man3/getcwd.3')
| -rw-r--r-- | man3/getcwd.3 | 311 |
1 files changed, 0 insertions, 311 deletions
diff --git a/man3/getcwd.3 b/man3/getcwd.3 deleted file mode 100644 index 6ba1e3280..000000000 --- a/man3/getcwd.3 +++ /dev/null @@ -1,311 +0,0 @@ -'\" 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 (date) "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) |