xnu-2782.30.5.tar.gz

[apple/xnu.git] / bsd / man / man2 / chmod.2

diff --git a/bsd/man/man2/chmod.2 b/bsd/man/man2/chmod.2
index 302be5974d4e1b549643837488ee0a55efefae65..b49c280756af9997b48b379883901525a2563274 100644 (file)
--- a/bsd/man/man2/chmod.2
+++ b/bsd/man/man2/chmod.2
@@ -38,15 +38,24 @@
 .Os BSD 4
 .Sh NAME
 .Nm chmod ,
 .Os BSD 4
 .Sh NAME
 .Nm chmod ,

-.Nm fchmod
+.Nm fchmod ,
+.Nm fchmodat

 .Nd change mode of file
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
 .Fd #include <sys/stat.h>
 .Ft int
 .Nd change mode of file
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
 .Fd #include <sys/stat.h>
 .Ft int

-.Fn chmod "const char *path" "mode_t mode"
+.Fo chmod
+.Fa "const char *path"
+.Fa "mode_t mode"
+.Fc

 .Ft int
 .Ft int

-.Fn fchmod "int fd" "mode_t mode"
+.Fo fchmod
+.Fa "int fildes"
+.Fa "mode_t mode"
+.Fc
+.Ft int
+.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag"

 .Sh DESCRIPTION
 The function
 .Fn chmod
 .Sh DESCRIPTION
 The function
 .Fn chmod


@@ -56,18 +65,53 @@ specified by the pathname
 .Fa path
 to
 .Fa mode .
 .Fa path
 to
 .Fa mode .

-.Fn Fchmod
+.Fn fchmod

 sets the permission bits of the specified
 file descriptor
 sets the permission bits of the specified
 file descriptor

-.Fa fd .
-.Fn Chmod
+.Fa fildes .
+.Fn chmod

 verifies that the process owner (user) either owns
 the file specified by
 .Fa path
 (or
 verifies that the process owner (user) either owns
 the file specified by
 .Fa path
 (or

-.Fa fd ) ,
+.Fa fildes ) ,

 or
 is the super-user.
 or
 is the super-user.

+.Pp
+The
+.Fn fchmodat
+is equivalent to
+.Fn chmod
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the file to be changed is determined relative to the directory
+associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+The values for the
+.Fa flag
+are constructed by a bitwise-inclusive OR of flags from the following list, defined
+in
+.In fcntl.h :
+.Bl -tag -width indent
+.It Dv AT_SYMLINK_NOFOLLOW
+If
+.Fa path
+names a symbolic link, then the mode of the symbolic link is changed.
+.El
+.Pp
+If
+.Fn fchmodat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used.
+If also
+.Fa flag
+is zero, the behavior is identical to a call to
+.Fn chmod .

 A mode is created from
 .Em or'd
 permission bit masks
 A mode is created from
 .Em or'd
 permission bit masks


@@ -126,62 +170,134 @@ Otherwise, a value of -1 is returned and
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
 .Va errno
 is set to indicate the error.
 .Sh ERRORS

-.Fn Chmod
-will fail and the file mode will be unchanged if:
+The
+.Fn chmod
+system call will fail and the file mode will be unchanged if:

 .Bl -tag -width Er
 .Bl -tag -width Er

-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
+.\" ==========
+.It Bq Er EACCES
+Search permission is denied for a component of the path prefix.
+.\" ==========
+.It Bq Er EFAULT
+.Fa Path
+points outside the process's allocated address space.
+.\" ==========
+.It Bq Er EINTR
+Its execution was interrupted by a signal.
+.\" ==========
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.\" ==========
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ==========

 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 
 .Dv {NAME_MAX}
 characters, or an entire path name exceeded 
 .Dv {PATH_MAX}
 characters.
 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 
 .Dv {NAME_MAX}
 characters, or an entire path name exceeded 
 .Dv {PATH_MAX}
 characters.

+.\" ==========

 .It Bq Er ENOENT
 The named file does not exist.
 .It Bq Er ENOENT
 The named file does not exist.

-.It Bq Er EACCES
-Search permission is denied for a component of the path prefix.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
+.\" ==========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
+.\" ==========

 .It Bq Er EPERM
 The effective user ID does not match the owner of the file and
 the effective user ID is not the super-user.
 .It Bq Er EPERM
 The effective user ID does not match the owner of the file and
 the effective user ID is not the super-user.

+.\" ==========

 .It Bq Er EROFS
 The named file resides on a read-only file system.
 .It Bq Er EROFS
 The named file resides on a read-only file system.

-.It Bq Er EFAULT
-.Fa Path
-points outside the process's allocated address space.
-.It Bq Er EIO
-An I/O error occurred while reading from or writing to the file system.

 .El
 .Pp
 .El
 .Pp

-.Fn Fchmod
+.Fn fchmod

 will fail if:
 .Bl -tag -width Er
 will fail if:
 .Bl -tag -width Er

+.\" ==========

 .It Bq Er EBADF
 .It Bq Er EBADF

-The descriptor is not valid.
+.Fa fildes
+is not a valid file descriptor.
+.\" ==========

 .It Bq Er EINVAL
 .It Bq Er EINVAL

-.Fa Fd
+.Fa fildes

 refers to a socket, not to a file.
 refers to a socket, not to a file.

-.It Bq Er EROFS
-The file resides on a read-only file system.
+.\" ==========
+.It Bq Er EINVAL
+.Fa mode
+is not a valid file mode.
+.\" ==========
+.It Bq Er EINTR
+Its execution was interrupted by a signal.
+.\" ==========

 .It Bq Er EIO
 An I/O error occurred while reading from or writing to the file system.
 .It Bq Er EIO
 An I/O error occurred while reading from or writing to the file system.

+.\" ==========
+.It Bq Er EPERM
+The effective user ID does not match the owner of the file and
+the effective user ID is not the super-user.
+.\" ==========
+.It Bq Er EROFS
+The file resides on a read-only file system.
+.El
+.Pp
+In addition to the
+.Fn chmod
+errors,
+.Fn fchmodat
+fails if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is neither
+.Fa AT_FDCWD
+nor a valid file descriptor open for searching.
+.It Bq Er EINVAL
+The value of the
+.Fa flag
+argument is not valid.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.

 .El
 .El

+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/stat.h>
+.Pp
+The include file
+.In sys/types.h
+is necessary.

 .Sh SEE ALSO
 .Xr chmod 1 ,
 .Sh SEE ALSO
 .Xr chmod 1 ,

-.Xr open 2 ,

 .Xr chown 2 ,
 .Xr chown 2 ,

+.Xr open 2 ,

 .Xr stat 2 ,
 .Xr stat 2 ,

+.Xr compat 5 ,

 .Xr sticky 8
 .Sh STANDARDS
 The
 .Fn chmod
 function is expected to conform to 
 .St -p1003.1-88 .
 .Xr sticky 8
 .Sh STANDARDS
 The
 .Fn chmod
 function is expected to conform to 
 .St -p1003.1-88 .

+The
+.Fn fchmodat
+function is expected to conform to POSIX.1-2008 . 

 .Sh HISTORY
 The
 .Fn fchmod
 function call
 appeared in
 .Bx 4.2 .
 .Sh HISTORY
 The
 .Fn fchmod
 function call
 appeared in
 .Bx 4.2 .

+The
+.Fn fchmodat
+system call appeared in OS X 10.10