Go to the previous, next section.

Assigning File Permissions

The primitive functions for creating files (for example, open or mkdir) take a mode argument, which specifies the file permissions for the newly created file. But the specified mode is modified by the process's file creation mask, or umask, before it is used.

The bits that are set in the file creation mask identify permissions that are always to be disabled for newly created files. For example, if you set all the "other" access bits in the mask, then newly created files are not accessible at all to processes in the "other" category, even if the mode argument specified to the creation function would permit such access. In other words, the file creation mask is the complement of the ordinary access permissions you want to grant.

Programs that create files typically specify a mode argument that includes all the permissions that make sense for the particular file. For an ordinary file, this is typically read and write permission for all classes of users. These permissions are then restricted as specified by the individual user's own file creation mask.

To change the permission of an existing file given its name, call chmod. This function ignores the file creation mask; it uses exactly the specified permission bits.

In normal use, the file creation mask is initialized in the user's login shell (using the umask shell command), and inherited by all subprocesses. Application programs normally don't need to worry about the file creation mask. It will do automatically what it is supposed to do.

When your program should create a file and bypass the umask for its access permissions, the easiest way to do this is to use fchmod after opening the file, rather than changing the umask.

In fact, changing the umask is usually done only by shells. They use the umask function.

The functions in this section are declared in `sys/stat.h'.

Function: mode_t umask (mode_t mask)

The umask function sets the file creation mask of the current process to mask, and returns the previous value of the file creation mask.

Here is an example showing how to read the mask with umask without changing it permanently:

mode_t
read_umask (void)
{
  mask = umask (0);
  umask (mask);
}

However, it is better to use getumask if you just want to read the mask value, because that is reentrant (at least if you use the GNU operating system).

Function: mode_t getumask (void)

Return the current value of the file creation mask for the current process. This function is a GNU extension.

Function: int chmod (const char *filename, mode_t mode)

The chmod function sets the access permission bits for the file named by filename to mode.

If the filename names a symbolic link, chmod changes the permission of the file pointed to by the link, not those of the link itself. There is actually no way to set the mode of a link, which is always -1.

This function returns 0 if successful and -1 if not. In addition to the usual file name syntax errors (see section File Name Errors), the following errno error conditions are defined for this function:

ENOENT
The named file doesn't exist.

EPERM
This process does not have permission to change the access permission of this file. Only the file's owner (as judged by the effective user ID of the process) or a privileged user can change them.

EROFS
The file resides on a read-only file system.

Function: int fchmod (int filedes, int mode)

This is like chmod, except that it changes the permissions of the file currently open via descriptor filedes.

The return value from fchmod is 0 on success and -1 on failure. The following errno error codes are defined for this function:

EBADF
The filedes argument is not a valid file descriptor.

EINVAL
The filedes argument corresponds to a pipe or socket, or something else that doesn't really have access permissions.

EPERM
This process does not have permission to change the access permission of this file. Only the file's owner (as judged by the effective user ID of the process) or a privileged user can change them.

EROFS
The file resides on a read-only file system.

Go to the previous, next section.