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:

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

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes