chmod()

Change the permissions for a file

Synopsis:

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

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

Arguments:

path

The name of the file whose permissions you want to change.

mode

The new permissions for the file. For more information, see “Access permissions” in the documentation for stat().

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The chmod() function changes S_ISUID, S_ISGID, S_ISVTX and the file permission bits of the file specified by the pathname pointed to by path to the corresponding bits in the mode argument. The application must ensure that the effective user ID of the process matches the owner of the file or the process has appropriate privileges to do this.

If a directory is writable and the sticky bit (S_ISVTX) is set on the directory, a process can remove or rename a file within that directory only if one or more of the following is also true:

• The effective user ID of the process matches the file's owner ID.
• The effective user ID of the process matches the directory's owner ID.
• The file is writable by the effective user ID of the process.
• The user is a superuser (effective user ID of 0).

If a directory has the set-group ID bit set, a file created in that directory will have the same group ID as that directory. Otherwise, the newly created file's group ID is set to the effective group ID of the creating process.

If the calling process doesn't have appropriate privileges, and if the group ID of the file doesn't match the effective group ID, and the file is a regular file, bit S_ISGID (set-group-ID on execution) in the file's mode is cleared on a successful return from chmod().

If the effective user ID of the calling process is equal to the file owner, or the calling process has appropriate privileges (for example, it belongs to the superuser), chmod() sets S_ISUID, S_ISGID and the file permission bits, defined in the <sys/stat.h> header file, from the corresponding bits in the mode argument. These bits define access permissions for the user associated with the file, the group associated with the file and all others.

This call has no effect on file descriptors for files that are already open.

If chmod() succeeds, the st_ctime field of the file is marked for update.

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

EACCES

Search permission is denied on a component of the path prefix.

ELOOP

Too many levels of symbolic links or prefixes.

ENAMETOOLONG

The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.

ENOTDIR

A component of the path prefix isn't a directory.

ENOENT

The file doesn't exist, or the path arguments points to an empty string.

ENOSYS

The chmod() function isn't implemented for the filesystem specified in path.

EPERM

The effective user ID doesn't match the owner of the file, and the calling process doesn't have appropriate privileges.

EROFS

The file resides on a read-only filesystem.

Examples:

/*
 * Change the permissions of a list of files
 * to by read/write by the owner only
 */
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>

int main( int argc, char **argv )
{
    int i;
    int ecode = 0;

    for( i = 1; i < argc; i++ ) {
        if( chmod( argv[i], S_IRUSR | S_IWUSR ) == -1 ) {
            perror( argv[i] );
            ecode++;
        }
    }

    return ecode;
}

Classification:

POSIX 1003.1

See also:

chown(), errno, fchmod(), fchown(), fstat(), open(), stat()