Go to the previous, next section.

Working Directory

Each process has associated with it a directory, called its current working directory or simply working directory, that is used in the resolution of relative file names (see section File Name Resolution).

When you log in and begin a new session, your working directory is initially set to the home directory associated with your login account in the system user database. You can find any user's home directory using the getpwuid or getpwnam functions; see section User Database.

Users can change the working directory using shell commands like cd. The functions described in this section are the primitives used by those commands and by other programs for examining and changing the working directory.

Prototypes for these functions are declared in the header file `unistd.h'.

Function: char * getcwd (char *buffer, size_t size)

The getcwd function returns an absolute file name representing the current working directory, storing it in the character array buffer that you provide. The size argument is how you tell the system the allocation size of buffer.

The GNU library version of this function also permits you to specify a null pointer for the buffer argument. Then getcwd allocates a buffer automatically, as with malloc (see section Unconstrained Allocation). If the size is greater than zero, then the buffer is that large; otherwise, the buffer is as large as necessary to hold the result.

The return value is buffer on success and a null pointer on failure. The following errno error conditions are defined for this function:

EINVAL
The size argument is zero and buffer is not a null pointer.

ERANGE
The size argument is less than the length of the working directory name. You need to allocate a bigger array and try again.

EACCES
Permission to read or search a component of the file name was denied.

Here is an example showing how you could implement the behavior of GNU's getcwd (NULL, 0) using only the standard behavior of getcwd:

char *
gnu_getcwd ()
{
  int size = 100;
  char *buffer = (char *) xmalloc (size);

  while (1)
    {
      char *value = getcwd (buffer, size);
      if (value != 0)
        return buffer;
      size *= 2;
      free (buffer);
      buffer = (char *) xmalloc (size);
    }
}

See section Examples of malloc, for information about xmalloc, which is not a library function but is a customary name used in most GNU software.

Function: char * getwd (char *buffer)

This is similar to getcwd. The GNU library provides getwd for backwards compatibility with BSD. The buffer should be a pointer to an array at least PATH_MAX bytes long.

Function: int chdir (const char *filename)

This function is used to set the process's working directory to filename.

The normal, successful return value from chdir is 0. A value of -1 is returned to indicate an error. The errno error conditions defined for this function are the usual file name syntax errors (see section File Name Errors), plus ENOTDIR if the file filename is not a directory.

Go to the previous, next section.