Man Linux: Main Page and Category List

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  argument  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().
       Invoking 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 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
       permits  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 .