getcwd Subroutine

Purpose

Gets the path name of the current directory.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

char *getcwd ( Buffer, Size) char *Buffer; size_t Size;

Description

The getcwd subroutine places the absolute path name of the current working directory in the array pointed to by the Buffer parameter, and returns that path name. The size parameter specifies the size in bytes of the character array pointed to by the Buffer parameter.

Parameters

Item	Description
Buffer	Points to string space that will contain the path name. If the Buffer parameter value is a null pointer, the getcwd subroutine, using the malloc subroutine, obtains the number of bytes of free space as specified by the Size parameter. In this case, the pointer returned by the getcwd subroutine can be used as the parameter in a subsequent call to the free subroutine. Starting the getcwd subroutine with a null pointer as the Buffer parameter value is not recommended.

Item

Description

Buffer

Points to string space that will contain the path name. If the Buffer parameter value is a null pointer, the getcwd subroutine, using the malloc subroutine, obtains the number of bytes of free space as specified by the Size parameter. In this case, the pointer returned by the getcwd subroutine can be used as the parameter in a subsequent call to the free subroutine. Starting the getcwd subroutine with a null pointer as the Buffer parameter value is not recommended.

Item	Description
Size	Specifies the length of the string space. The value of the Size parameter must be at least 1 greater than the length of the path name to be returned.

Return Values

If the getcwd subroutine is unsuccessful, a null value is returned and the errno global variable is set to indicate the error. The getcwd subroutine is unsuccessful if the Size parameter is not large enough or if an error occurs in a lower-level function.

In UNIX03 mode, the getcwd subroutine returns a null value if the actual path name is longer than the value defined by PATH_MAX (see the limits.h file). In the pervious mode, the getcwd subroutine returns a truncated path name if the path name is longer than PATH_MAX. The previous behavior is disabled by setting the environment variable XPG_SUS_ENV=ON.

Error Codes

If the getcwd subroutine is unsuccessful, it returns one or more of the following error codes:

Item	Description
EACCES	Indicates that read or search permission was denied for a component of the path name
EINVAL	Indicates that the Size parameter is 0 or a negative number.
ENOMEM	Indicates that insufficient storage space is available.
ERANGE	Indicates that the Size parameter is greater than 0, but is smaller than the length of the path name plus 1.