File Permissions and Ownership

The stat(2) family of functions allows you to inquire about a file system object's permissions and ownership. Permissions are described by the stat structure member st_mode. To alter this permission setting, you change its mode. This is covered next, using the functions chmod(2), fchmod(2), and lchmod(2).

Each user on a UNIX system owns files that he has created. He is the owner of his files and, as the owner, possesses the right to change its permissions (mode). Likewise, the user is a member of a group. Consequently, there exists group ownership on file system objects. The owner of a file (with exceptions) can give his ownership away to another user or group on the system. This is known as changing the owner or group of the file.

Changing Permissions

The chmod(2) function permits the program to alter the permission bits of a file system object. The functions chmod(2), fchmod(2), and lchmod(2) have the following synopsis:

#include <sys/stat.h>

int chmod(const char *path, mode_t mode);

int fchmod(int fd, mode_t mode);

int lchmod(const char *path, mode_t mode);

The chmod(2) function follows symbolic links to arrive at the file that will have its permissions altered. The lchmod(2) function, which is not available on all UNIX platforms, allows the caller to alter the permissions on the symbolic link itself.

The functions chmod(2) and lchmod(2) require the pathname of the file system object. Function fchmod(2) changes the permissions on the object open on the file descriptor fd.

The permission bits in argument mode replace the existing permissions on the file system object. These functions return 0 when successful or -1 with an error code in errno if they fail.

The following example shows how a C program could make the shell script my_script executable for the owner and group:

if ( chmod("./my_script",0550) == -1 )
    /* Report error */
else
    /* Successful */

Alternatively, using macro constants, this example could have been written as follows:

if ( chmod("./my_script",S_IRUSR|S_IXUSR|S_IRGRP|S_IXGRP) == -1 )
    /* Report error */
else
    /* Successful */

Calling these functions will not affect the access of objects that have already been opened.

Changing Ownership

In order to change the ownership of a file, the function chown(2) must be called. The synopsis for this family of functions is as follows:

#include <sys/types.h>
#include <unistd.h>

int chown(const char *path, uid_t owner, gid_t group);

int fchown(int fd, uid_t owner, gid_t group);

int lchown(const char *path, uid_t owner, gid_t group);

Function chown(2) follows the symbolic links starting with path to arrive at the file that will be changed. The function fchown(2) affects the file that is open on file descriptor fd. The lchown(2) function affects the ownership of the symbolic link itself, rather than the file it points to.

The arguments owner and group set the ownership user ID and group ID, respectively. Argument owner or group may be given the value -1 (with one exception) to leave the user ID or group ID unchanged. This is useful when changing only one of the two values of a file system object. See Chapter 12, "User ID, Password, and Group Management," for more about how to obtain user and group ID numbers.

Most UNIX platforms clear the set-user-ID and set-group-ID bits when these functions are called. This helps to prevent accidental or mischievous security holes in file system permissions. However, when the caller is root, the set-user-ID and set-group-ID bits are not reset.

The following example sets the ownership of the file /etc/hosts to root (value 0), while leaving the group ID unchanged:

if ( chown("/etc/hosts",0,-1) == -1 )
    /* Report error */
else
    /* Successful */

Some systems may restrict these calls, since they can represent a security risk under the right conditions.