getcwd man page on Gentoo

Man page or keyword search:  
man Server   6889 pages
apropos Keyword Search (all sections)
Output format
Gentoo logo
[printable version]

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 shall contain no components that are dot or  dot-dot,  or  are
       symbolic links.

       If  there are multiple pathnames that getcwd() could place in the array
       pointed to by buf, one beginning with a single  <slash>	character  and
       one  or more beginning with two <slash> characters, then getcwd() shall
       place the pathname beginning with a single  <slash>  character  in  the
       array.  The  pathname shall not contain any unnecessary <slash> charac‐
       ters after the leading one or two <slash> characters.

       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 string +1.

       The getcwd() function may fail if:

       EACCES Search permission was denied for the current directory, or  read
	      or  search  permission was denied for a directory above the cur‐
	      rent directory in the file hierarchy.

       ENOMEM Insufficient storage space is available.

       The following sections are informative.

EXAMPLES
       The following example  uses  {PATH_MAX}	as  the	 initial  buffer  size
       (unless	it  is	indeterminate  or very large), and calls getcwd() with
       progressively larger buffers until it does not give an [ERANGE] error.

	   #include <stdlib.h>
	   #include <errno.h>
	   #include <unistd.h>

	   ...

	   long path_max;
	   size_t size;
	   char *buf;
	   char *ptr;

	   path_max = pathconf(".", _PC_PATH_MAX);
	   if (path_max == -1)
	       size = 1024;
	   else if (path_max > 10240)
	       size = 10240;
	   else
	       size = path_max;

	   for (buf = ptr = NULL; ptr == NULL; size *= 2)
	   {
	       if ((buf = realloc(buf, size)) == NULL)
	       {
		   ... handle error ...
	       }

	       ptr = getcwd(buf, size);
	       if (ptr == NULL && errno != ERANGE)
	       {
		   ... handle error ...
	       }
	   }
	   ...
	   free (buf);

APPLICATION USAGE
       If the pathname obtained from getcwd() is longer than {PATH_MAX} bytes,
       it  could produce an [ENAMETOOLONG] error if passed to chdir().	There‐
       fore, in order to return to that directory it may be necessary to break
       the  pathname  into  sections  shorter  than  {PATH_MAX} bytes and call
       chdir() on each section in turn (the first section  being  an  absolute
       pathname	 and  subsequent sections being relative pathnames). A simpler
       way to handle saving and restoring the working directory when it may be
       deeper  than  {PATH_MAX}	 bytes	in the file hierarchy is to use a file
       descriptor and fchdir(), rather than getcwd()  and  chdir().   However,
       the  two methods do have some differences. The fchdir() approach causes
       the program to restore a working directory even if it has been  renamed
       in  the	meantime, whereas the chdir() approach restores to a directory
       with the same name as  the  original,  even  if	the  directories  were
       renamed	in  the	 meantime. Since the fchdir() approach does not access
       parent directories, it can succeed when getcwd() would fail due to per‐
       missions	 problems.  In	applications conforming to earlier versions of
       this standard, it was not possible to use the  fchdir()	approach  when
       the  working  directory is searchable but not readable, as the only way
       to open a directory was with O_RDONLY, whereas  the  getcwd()  approach
       can succeed in this case.

RATIONALE
       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.
       Finally, getcwd() is taken from the SVID where it has the two arguments
       used in this volume of POSIX.1‐2008.

       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	recom‐
       mended in conforming applications.

       Earlier	implementations of getcwd() sometimes generated pathnames like
       "../../../subdirname" internally, using them to	explore	 the  path  of
       ancestor	 directories  back to the root. If one of these internal path‐
       names exceeded {PATH_MAX} in length, the implementation could fail with
       errno set to [ENAMETOOLONG].  This is no longer allowed.

       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 developer that  getcwd()	can  fail  for
       reasons	beyond	the control of the application developer 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 POSIX.1‐2008 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 addi‐
       tion.

FUTURE DIRECTIONS
       None.

SEE ALSO
       malloc()

       The Base Definitions volume of POSIX.1‐2008, <unistd.h>

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal  and	 Electronics  Engineers,  Inc  and  The	 Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum	 1  applied.)  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.unix.org/online.html .

       Any typographical or formatting errors that appear  in  this  page  are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors,	 see  https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013			    GETCWD(3P)
[top]

List of man pages available for Gentoo

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net