Man Pages

getcwd(3p) - phpMan getcwd(3p) - phpMan

Command: man perldoc info search(apropos)  


GETCWD(3P)                 POSIX Programmer's Manual                GETCWD(3P)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (consult the corresponding Linux manual page for details of Linux behavior), or the interface  may  not  be
       implemented on Linux.

NAME
       getcwd - get the pathname of the current working directory

SYNOPSIS
       #include <unistd.h>

       char *getcwd(char *buf, size_t size);


DESCRIPTION
       The getcwd() function shall place an absolute pathname of the current working directory in the array pointed to
       by buf, and return buf. The pathname copied to the array shall contain no components that are  symbolic  links.
       The  size argument is the size in bytes of the character array pointed to by the buf argument. If buf is a null
       pointer, the behavior of getcwd() is unspecified.

RETURN VALUE
       Upon successful completion, getcwd() shall return the buf argument. Otherwise, getcwd()  shall  return  a  null
       pointer and set errno to indicate the error. The contents of the array pointed to by buf are then undefined.

ERRORS
       The getcwd() function shall fail if:

       EINVAL The size argument is 0.

       ERANGE The size argument is greater than 0, but is smaller than the length of the pathname +1.


       The getcwd() function may fail if:

       EACCES Read or search permission was denied for a component of the pathname.

       ENOMEM Insufficient storage space is available.


       The following sections are informative.

EXAMPLES
   Determining the Absolute Pathname of the Current Working Directory
       The  following  example  returns  a pointer to an array that holds the absolute pathname of the current working
       directory. The pointer is returned in the ptr variable, which points to the buf array  where  the  pathname  is
       stored.


              #include <stdlib.h>
              #include <unistd.h>
              ...
              long size;
              char *buf;
              char *ptr;


              size = pathconf(".", _PC_PATH_MAX);


              if ((buf = (char *)malloc((size_t)size)) != NULL)
                  ptr = getcwd(buf, (size_t)size);
              ...

APPLICATION USAGE
       None.

RATIONALE
       Since  the  maximum  pathname length is arbitrary unless {PATH_MAX} is defined, an application generally cannot
       supply a buf with size {{PATH_MAX}+1}.

       Having getcwd() take no arguments and instead use the malloc() function to produce space for the returned argu-
       ment  was  considered.  The  advantage is that getcwd() knows how big the working directory pathname is and can
       allocate an appropriate amount of space. But the programmer would have to use the free() function to  free  the
       resulting  object, or each use of getcwd() would further reduce the available memory. Also, malloc() and free()
       are used nowhere else in this volume of IEEE Std 1003.1-2001. Finally, getcwd() is taken from the SVID where it
       has the two arguments used in this volume of IEEE Std 1003.1-2001.

       The  older  function  getwd() was rejected for use in this context because it had only a buffer argument and no
       size argument, and thus had no way to prevent overwriting the buffer, except to depend  on  the  programmer  to
       provide a large enough buffer.

       On  some implementations, if buf is a null pointer, getcwd() may obtain size bytes of memory using malloc(). In
       this case, the pointer returned by getcwd() may be used as the argument in a subsequent call to free().  Invok-
       ing getcwd() with buf as a null pointer is not recommended in conforming applications.

       If  a  program is operating in a directory where some (grand)parent directory does not permit reading, getcwd()
       may fail, as in most implementations it must read the directory to determine the name of  the  file.  This  can
       occur  if search, but not read, permission is granted in an intermediate directory, or if the program is placed
       in that directory by some more privileged process (for example, login). Including the [EACCES] error  condition
       makes the reporting of the error consistent and warns the application writer that getcwd() can fail for reasons
       beyond the control of the application writer or user. Some implementations can avoid this occurrence (for exam-
       ple,  by  implementing  getcwd()  using  pwd,  where  pwd  is a set-user-root process), thus the error was made
       optional. Since this volume of IEEE Std 1003.1-2001 permits the addition of other errors, this would be a  com-
       mon addition and yet one that applications could not be expected to deal with without this addition.

FUTURE DIRECTIONS
       None.

SEE ALSO
       malloc(), the Base Definitions volume of IEEE Std 1003.1-2001, <unistd.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  Issue  6,  Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The
       Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Stan-
       dard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The original Standard can be
       obtained online at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                           GETCWD(3P)