getcwd man page on RedHat

Man page or keyword search:  
man Server   29550 pages
apropos Keyword Search (all sections)
Output format
RedHat 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 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)
[top]

List of man pages available for RedHat

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