huschi.net

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 differ (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  sym-
       bolic  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  indi-
       cate  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 argument was considered.  The  advan-
       tage  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().
       Invoking getcwd() with buf as a null pointer is not recommended in con-
       forming applications.
       If a program is operating  in  a  directory  where  some  (grand)parent
       directory does not permit reading, getcwd() may fail, as in most imple-
       mentations 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  direc-
       tory  by  some  more privileged process (for example, login). Including
       the [EACCES] error condition makes the reporting of the  error  consis-
       tent  and  warns the application writer that getcwd() can fail for rea-
       sons beyond the control of the application writer or user. Some  imple-
       mentations  can  avoid  this  occurrence  (for example, 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 per-
       mits the addition of other errors, this would be a common 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, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications 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 Standard, 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)