summaryrefslogtreecommitdiffstats
path: root/man3/getcwd.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/getcwd.3')
-rw-r--r--man3/getcwd.3311
1 files changed, 0 insertions, 311 deletions
diff --git a/man3/getcwd.3 b/man3/getcwd.3
deleted file mode 100644
index 1004458..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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)