Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CHMOD(2)		  FreeBSD System Calls Manual		      CHMOD(2)

NAME
     chmod, fchmodat, fchmod --	change mode of file

SYNOPSIS
     #include <sys/stat.h>

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

     int
     fchmod(int	fd, mode_t mode);

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

     int
     fchmodat(int fd, const char *path,	mode_t mode, int flag);

DESCRIPTION
     The chmod() function sets the file	permission bits	of the file specified
     by	the pathname path to mode.  chmod() verifies that the process owner
     (user) either owns	the specified file or is the superuser.

     The mode argument is the bitwise OR of zero or more of the	permission bit
     masks from	the following list:

	   #define S_IRWXU 0000700    /* RWX mask for owner */
	   #define S_IRUSR 0000400    /* R for owner */
	   #define S_IWUSR 0000200    /* W for owner */
	   #define S_IXUSR 0000100    /* X for owner */

	   #define S_IRWXG 0000070    /* RWX mask for group */
	   #define S_IRGRP 0000040    /* R for group */
	   #define S_IWGRP 0000020    /* W for group */
	   #define S_IXGRP 0000010    /* X for group */

	   #define S_IRWXO 0000007    /* RWX mask for other */
	   #define S_IROTH 0000004    /* R for other */
	   #define S_IWOTH 0000002    /* W for other */
	   #define S_IXOTH 0000001    /* X for other */

	   #define S_ISUID 0004000    /* set user id on	execution */
	   #define S_ISGID 0002000    /* set group id on execution */
	   #define S_ISVTX 0001000    /* save swapped text even	after use */

     If	mode ISVTX (the	sticky bit) is set on a	file, it is ignored.

     If	mode ISVTX (the	sticky bit) is set on a	directory, an unprivileged
     user may not delete or rename files of other users	in that	directory.
     The sticky	bit may	be set by any user on a	directory which	the user owns
     or	has appropriate	permissions.  For more details of the properties of
     the sticky	bit, see sticky(8).

     Writing or	changing the owner of a	file turns off the set-user-ID and
     set-group-ID bits unless the user is the superuser.  This makes the sys-
     tem somewhat more secure by protecting set-user-ID	(set-group-ID) files
     from remaining set-user-ID	(set-group-ID) if they are modified, at	the
     expense of	a degree of compatibility.

     The fchmodat() function is	equivalent to chmod() except in	the case where
     path specifies a relative path.  In this case the file to be changed is
     determined	relative to the	directory associated with the file descriptor
     fd	instead	of the current working directory.

     If	fchmodat() is passed the special value AT_FDCWD	(defined in <fcntl.h>)
     in	the fd parameter, the current working directory	is used.  If flag is
     also zero,	the behavior is	identical to a call to chmod().

     The flag argument is the bitwise OR of zero or more of the	following val-
     ues:

	   AT_SYMLINK_NOFOLLOW	If path	names a	symbolic link, then the	mode
				of the symbolic	link is	changed.

     The fchmod() function is equivalent to chmod() except that	the file whose
     permissions are changed is	specified by the file descriptor fd.

RETURN VALUES
     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the
     error.

ERRORS
     The chmod() and fchmodat()	functions will fail and	the file mode will be
     unchanged if:

     [ENOTDIR]		A component of the path	prefix is not a	directory.

     [ENAMETOOLONG]	A component of a pathname exceeded NAME_MAX charac-
			ters, or an entire pathname (including the terminating
			NUL) exceeded PATH_MAX bytes.

     [ENOENT]		The named file does not	exist.

     [EACCES]		Search permission is denied for	a component of the
			path prefix.

     [EINVAL]		mode contains bits other than the file type and	those
			described above.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

     [EPERM]		The effective user ID does not match the owner of the
			file and the effective user ID is not the superuser.

     [EROFS]		The named file resides on a read-only file system.

     [EFAULT]		path points outside the	process's allocated address
			space.

     [EIO]		An I/O error occurred while reading from or writing to
			the file system.

     Additionally, the fchmodat() function will	fail if:

     [EINVAL]		The value of the flag argument was neither zero	nor
			AT_SYMLINK_NOFOLLOW.

     [EBADF]		The path argument specifies a relative path and	the fd
			argument is neither AT_FDCWD nor a valid file descrip-
			tor.

     [ENOTDIR]		The path argument specifies a relative path and	the fd
			argument is a valid file descriptor but	it does	not
			reference a directory.

     [EOPNOTSUPP]	The flag argument specifies AT_SYMLINK_NOFOLLOW	on a
			symbolic link and the file system does not support
			that operation.

     [EACCES]		The path argument specifies a relative path but	search
			permission is denied for the directory which the fd
			file descriptor	references.

     fchmod() will fail	and the	file mode will be unchanged if:

     [EBADF]		The descriptor is not valid.

     [EINVAL]		fd refers to a socket, not to a	file.

     [EINVAL]		mode contains bits other than the file type and	those
			described above.

     [EPERM]		The effective user ID does not match the owner of the
			file and the effective user ID is not the superuser.

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

     [EIO]		An I/O error occurred while reading from or writing to
			the file system.

SEE ALSO
     chmod(1), chown(2), open(2), stat(2), sticky(8)

STANDARDS
     The chmod(), fchmod(), and	fchmodat() functions are expected to conform
     to	IEEE Std 1003.1-2008 ("POSIX.1").

HISTORY
     The chmod() system	call first appeared in Version 1 AT&T UNIX; fchmod()
     in	4.1cBSD; and fchmodat()	has been available since OpenBSD 5.0.

FreeBSD	13.0		      September	10, 2015		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=chmod&sektion=2&manpath=OpenBSD+6.9>

home | help