.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
-.Fn chmod "const char *path" "mode_t mode"
+.Fo chmod
+.Fa "const char *path"
+.Fa "mode_t mode"
+.Fc
.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
.Fa path
to
.Fa mode .
-.Fn Fchmod
+.Fn fchmod
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
-.Fa fd ) ,
+.Fa fildes ) ,
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
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
-.Xr sticky 8 .
+.Xr sticky 7 .
.Pp
Writing or changing the owner of a file
turns off the set-user-id and set-group-id bits
.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
-.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 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 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
-.Fn Fchmod
+.Fn fchmod
will fail if:
.Bl -tag -width Er
+.\" ==========
.It Bq Er EBADF
-The descriptor is not valid.
+.Fa fildes
+is not a valid file descriptor.
+.\" ==========
.It Bq Er EINVAL
-.Fa Fd
+.Fa fildes
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 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
+.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 ,
-.Xr open 2 ,
.Xr chown 2 ,
+.Xr open 2 ,
.Xr stat 2 ,
-.Xr sticky 8
+.Xr compat 5 ,
+.Xr sticky 7
.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 .
+The
+.Fn fchmodat
+system call appeared in OS X 10.10
projects / apple / xnu.git / blobdiff