Index: head/lib/libc/sys/access.2 =================================================================== --- head/lib/libc/sys/access.2 (revision 340346) +++ head/lib/libc/sys/access.2 (revision 340347) @@ -1,254 +1,268 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)access.2 8.2 (Berkeley) 4/1/94 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt ACCESS 2 .Os .Sh NAME .Nm access , .Nm eaccess , .Nm faccessat .Nd check accessibility of a file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn access "const char *path" "int mode" .Ft int .Fn eaccess "const char *path" "int mode" .Ft int .Fn faccessat "int fd" "const char *path" "int mode" "int flag" .Sh DESCRIPTION The .Fn access and .Fn eaccess system calls check the accessibility of the file named by the .Fa path argument for the access permissions indicated by the .Fa mode argument. The value of .Fa mode is either the bitwise-inclusive OR of the access permissions to be checked .Dv ( R_OK for read permission, .Dv W_OK for write permission, and .Dv X_OK for execute/search permission), or the existence test .Pq Dv F_OK . .Pp For additional information, see the .Sx "File Access Permission" section of .Xr intro 2 . .Pp The .Fn eaccess system call uses the effective user ID and the group access list to authorize the request; the .Fn access system call uses the real user ID in place of the effective user ID, the real group ID in place of the effective group ID, and the rest of the group access list. .Pp The .Fn faccessat system call is equivalent to .Fn access except in the case where .Fa path specifies a relative path. In this case the file whose accessibility is to be determined is located relative to the directory associated with the file descriptor .Fa fd instead of the current working directory. If .Fn faccessat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fn access . Values for .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_EACCESS The checks for accessibility are performed using the effective user and group IDs instead of the real user and group ID as required in a call to .Fn access . .It Dv AT_BENEATH -Only operate on files and directories below the starting directory. +Only operate on files and directories below the topping directory. +See the description of the +.Dv O_BENEATH +flag in the +.Xr open 2 +manual page. .El .Pp Even if a process's real or effective user has appropriate privileges and indicates success for .Dv X_OK , the file may not actually have execute permission bits set. Likewise for .Dv R_OK and .Dv W_OK . .Sh RETURN VALUES .Rv -std .Sh ERRORS .Fn access , .Fn eaccess , or .Fn faccessat will fail if: .Bl -tag -width Er .It Bq Er EINVAL The value of the .Fa mode argument is invalid. .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOENT The named file does not exist. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EROFS Write access is requested for a file on a read-only file system. .It Bq Er ETXTBSY Write access is requested for a pure procedure (shared text) file presently being executed. .It Bq Er EACCES Permission bits of the file mode do not permit the requested access, or search permission is denied on a component of the path prefix. .It Bq Er EFAULT The .Fa path argument 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 Also, the .Fn faccessat system call may fail 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 .Dv AT_FDCWD nor a valid file descriptor. .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. .It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE The .Dv AT_BENEATH -flag was specified but +flag was provided to +.Fn faccessat , +and the absolute .Fa path -is not strictly relative to the starting directory. -For example, +does not have its tail fully contained under the topping directory, +or the relative .Fa path -is absolute or includes a ".." component that escapes the starting directory. +escapes it. .El .Sh SEE ALSO .Xr chmod 2 , .Xr intro 2 , .Xr stat 2 .Sh STANDARDS The .Fn access system call is expected to conform to .St -p1003.1-90 . The .Fn faccessat system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn access function appeared in .At v7 . The .Fn faccessat system call appeared in .Fx 8.0 . .Sh SECURITY CONSIDERATIONS The .Fn access system call is a potential security hole due to race conditions and should never be used. Set-user-ID and set-group-ID applications should restore the effective user or group ID, and perform actions directly rather than use .Fn access to simulate access checks for the real user or group ID. The .Fn eaccess system call likewise may be subject to races if used inappropriately. .Pp .Fn access remains useful for providing clues to users as to whether operations make sense for particular filesystem objects (e.g. 'delete' menu item only highlighted in a writable folder ... avoiding interpretation of the st_mode bits that the application might not understand -- e.g. in the case of AFS). It also allows a cheaper file existence test than .Xr stat 2 . Index: head/lib/libc/sys/chflags.2 =================================================================== --- head/lib/libc/sys/chflags.2 (revision 340346) +++ head/lib/libc/sys/chflags.2 (revision 340347) @@ -1,338 +1,352 @@ .\" Copyright (c) 1989, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)chflags.2 8.3 (Berkeley) 5/2/95 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt CHFLAGS 2 .Os .Sh NAME .Nm chflags , .Nm lchflags , .Nm fchflags , .Nm chflagsat .Nd set file flags .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/stat.h .In unistd.h .Ft int .Fn chflags "const char *path" "unsigned long flags" .Ft int .Fn lchflags "const char *path" "unsigned long flags" .Ft int .Fn fchflags "int fd" "unsigned long flags" .Ft int .Fn chflagsat "int fd" "const char *path" "unsigned long flags" "int atflag" .Sh DESCRIPTION The file whose name is given by .Fa path or referenced by the descriptor .Fa fd has its flags changed to .Fa flags . .Pp The .Fn lchflags system call is like .Fn chflags except in the case where the named file is a symbolic link, in which case .Fn lchflags will change the flags of the link itself, rather than the file it points to. .Pp The .Fn chflagsat is equivalent to either .Fn chflags or .Fn lchflags depending on the .Fa atflag 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 atflag 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 flags of the symbolic link are changed. .It Dv AT_BENEATH Only allow to change flags for a file which is beneath of -the starting directory. +the topping directory. +See the description of the +.Dv O_BENEATH +flag in the +.Xr open 2 +manual page. .El .Pp If .Fn chflagsat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used. If also .Fa atflag is zero, the behavior is identical to a call to .Fn chflags . .Pp The flags specified are formed by .Em or Ns 'ing the following values .Pp .Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent .It Dv SF_APPEND The file may only be appended to. .It Dv SF_ARCHIVED The file has been archived. This flag means the opposite of the DOS, Windows and CIFS FILE_ATTRIBUTE_ARCHIVE attribute. This flag has been deprecated, and may be removed in a future release. .It Dv SF_IMMUTABLE The file may not be changed. .It Dv SF_NOUNLINK The file may not be renamed or deleted. .It Dv SF_SNAPSHOT The file is a snapshot file. .It Dv UF_APPEND The file may only be appended to. .It Dv UF_ARCHIVE The file needs to be archived. This flag has the same meaning as the DOS, Windows and CIFS FILE_ATTRIBUTE_ARCHIVE attribute. Filesystems in FreeBSD may or may not have special handling for this flag. For instance, ZFS tracks changes to files and will set this bit when a file is updated. UFS only stores the flag, and relies on the application to change it when needed. .It Dv UF_HIDDEN The file may be hidden from directory listings at the application's discretion. The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_HIDDEN attribute. .It Dv UF_IMMUTABLE The file may not be changed. .It Dv UF_NODUMP Do not dump the file. .It Dv UF_NOUNLINK The file may not be renamed or deleted. .It Dv UF_OFFLINE The file is offline, or has the Windows and CIFS FILE_ATTRIBUTE_OFFLINE attribute. Filesystems in FreeBSD store and display this flag, but do not provide any special handling when it is set. .It Dv UF_OPAQUE The directory is opaque when viewed through a union stack. .It Dv UF_READONLY The file is read only, and may not be written or appended. Filesystems may use this flag to maintain compatibility with the DOS, Windows and CIFS FILE_ATTRIBUTE_READONLY attribute. .It Dv UF_REPARSE The file contains a Windows reparse point and has the Windows and CIFS FILE_ATTRIBUTE_REPARSE_POINT attribute. .It Dv UF_SPARSE The file has the Windows FILE_ATTRIBUTE_SPARSE_FILE attribute. This may also be used by a filesystem to indicate a sparse file. .It Dv UF_SYSTEM The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_SYSTEM attribute. Filesystems in FreeBSD may store and display this flag, but do not provide any special handling when it is set. .El .Pp If one of .Dv SF_IMMUTABLE , SF_APPEND , or .Dv SF_NOUNLINK is set a non-super-user cannot change any flags and even the super-user can change flags only if securelevel is 0. (See .Xr init 8 for details.) .Pp The .Dv UF_IMMUTABLE , UF_APPEND , UF_NOUNLINK , UF_NODUMP , and .Dv UF_OPAQUE flags may be set or unset by either the owner of a file or the super-user. .Pp The .Dv SF_IMMUTABLE , SF_APPEND , SF_NOUNLINK , and .Dv SF_ARCHIVED flags may only be set or unset by the super-user. Attempts to toggle these flags by non-super-users are rejected. These flags may be set at any time, but normally may only be unset when the system is in single-user mode. (See .Xr init 8 for details.) .Pp The implementation of all flags is filesystem-dependent. See the description of the .Dv UF_ARCHIVE flag above for one example of the differences in behavior. Care should be exercised when writing applications to account for support or lack of support of these flags in various filesystems. .Pp The .Dv SF_SNAPSHOT flag is maintained by the system and cannot be toggled. .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn chflags system call will fail if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 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 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 One of .Dv SF_IMMUTABLE , SF_APPEND , or .Dv SF_NOUNLINK is set and the user is either not the super-user or securelevel is greater than 0. .It Bq Er EPERM A non-super-user attempted to toggle one of .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND , or .Dv SF_NOUNLINK . .It Bq Er EPERM An attempt was made to toggle the .Dv SF_SNAPSHOT flag. .It Bq Er EROFS The named file resides on a read-only file system. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to the file system. .It Bq Er EOPNOTSUPP The underlying file system does not support file flags, or does not support all of the flags set in .Fa flags . .El .Pp The .Fn fchflags system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The descriptor is not valid. .It Bq Er EINVAL The .Fa fd argument refers to a socket, not to a file. .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 One of .Dv SF_IMMUTABLE , SF_APPEND , or .Dv SF_NOUNLINK is set and the user is either not the super-user or securelevel is greater than 0. .It Bq Er EPERM A non-super-user attempted to toggle one of .Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND , or .Dv SF_NOUNLINK . .It Bq Er EPERM An attempt was made to toggle the .Dv SF_SNAPSHOT flag. .It Bq Er EROFS The file resides on a read-only file system. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to the file system. .It Bq Er EOPNOTSUPP The underlying file system does not support file flags, or does not support all of the flags set in .Fa flags . .It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE The .Dv AT_BENEATH -flag was specified but +flag was provided to +.Fn chflagsat , +and the absolute .Fa path -is not strictly relative to the starting directory. -For example, +does not have its tail fully contained under the topping directory, +or the relative .Fa path -is absolute or includes a ".." component that escapes the starting directory. +escapes it. .El .Sh SEE ALSO .Xr chflags 1 , .Xr fflagstostr 3 , .Xr strtofflags 3 , .Xr init 8 , .Xr mount_unionfs 8 .Sh HISTORY The .Fn chflags and .Fn fchflags system calls first appeared in .Bx 4.4 . The .Fn lchflags system call first appeared in .Fx 5.0 . The .Fn chflagsat system call first appeared in .Fx 10.0 . Index: head/lib/libc/sys/chmod.2 =================================================================== --- head/lib/libc/sys/chmod.2 (revision 340346) +++ head/lib/libc/sys/chmod.2 (revision 340347) @@ -1,339 +1,353 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)chmod.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt CHMOD 2 .Os .Sh NAME .Nm chmod , .Nm fchmod , .Nm lchmod , .Nm fchmodat .Nd change mode of file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/stat.h .Ft int .Fn chmod "const char *path" "mode_t mode" .Ft int .Fn fchmod "int fd" "mode_t mode" .Ft int .Fn lchmod "const char *path" "mode_t mode" .Ft int .Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" .Sh DESCRIPTION The file permission bits of the file named specified by .Fa path or referenced by the file descriptor .Fa fd are changed to .Fa mode . The .Fn chmod system call verifies that the process owner (user) either owns the file specified by .Fa path (or .Fa fd ) , or is the super-user. The .Fn chmod system call follows symbolic links to operate on the target of the link rather than the link itself. .Pp The .Fn lchmod system call is similar to .Fn chmod but does not follow symbolic links. .Pp The .Fn fchmodat is equivalent to either .Fn chmod or .Fn lchmod depending on the .Fa flag 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. .It Dv AT_BENEATH Only allow to change permissions of a file which is beneath of -the starting directory. +the topping directory. +See the description of the +.Dv O_BENEATH +flag in the +.Xr open 2 +manual page. .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 . .Pp A mode is created from .Em or'd permission bit masks defined in .In sys/stat.h : .Pp .Bd -literal -offset indent -compact #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 /* sticky bit */ .Ed .Pp The non-standard .Dv S_ISTXT is a synonym for .Dv S_ISVTX . .Pp The .Fx VM system totally ignores the sticky bit .Pq Dv S_ISVTX for executables. On UFS-based file systems (FFS, LFS) the sticky bit may only be set upon directories. .Pp If mode .Dv S_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 .Xr sticky 7 . .Pp If mode ISUID (set UID) is set on a directory, and the MNT_SUIDDIR option was used in the mount of the file system, then the owner of any new files and sub-directories created within this directory are set to be the same as the owner of that directory. If this function is enabled, new directories will inherit the bit from their parents. Execute bits are removed from the file, and it will not be given to root. This behavior does not change the requirements for the user to be allowed to write the file, but only the eventual owner after it has been created. Group inheritance is not affected. .Pp This feature is designed for use on fileservers serving PC users via ftp, SAMBA, or netatalk. It provides security holes for shell users and as such should not be used on shell machines, especially on home directories. This option requires the SUIDDIR option in the kernel to work. Only UFS file systems support this option. For more details of the suiddir mount option, see .Xr mount 8 . .Pp Writing or changing the owner of a file turns off the set-user-id and set-group-id bits unless the user is the super-user. This makes the system 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. .Sh RETURN VALUES .Rv -std .Sh ERRORS 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 ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 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 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 is not the super-user, the effective user ID do match the owner of the file, but the group ID of the file does not match the effective group ID nor one of the supplementary group IDs. .It Bq Er EPERM The named file has its immutable or append-only flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EROFS The named file resides on a read-only file system. .It Bq Er EFAULT The .Fa path argument 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. .It Bq Er EFTYPE The effective user ID is not the super-user, the mode includes the sticky bit .Dv ( S_ISVTX ) , and path does not refer to a directory. .El .Pp The .Fn fchmod system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The descriptor is not valid. .It Bq Er EINVAL The .Fa fd argument refers to a socket, not to a file. .It Bq Er EROFS The file resides on a read-only file system. .It Bq Er EIO An I/O error occurred while reading from or writing to the 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. .It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE The .Dv AT_BENEATH -flag was specified but +flag was provided to +.Fn fchmodat , +and the absolute .Fa path -is not strictly relative to the starting directory. -For example, +does not have its tail fully contained under the topping directory, +or the relative .Fa path -is absolute or includes a ".." component that escapes the starting directory. +escapes it. .El .Sh SEE ALSO .Xr chmod 1 , .Xr chflags 2 , .Xr chown 2 , .Xr open 2 , .Xr stat 2 , .Xr sticky 7 .Sh STANDARDS The .Fn chmod system call is expected to conform to .St -p1003.1-90 , except for the return of .Er EFTYPE . The .Dv S_ISVTX bit on directories is expected to conform to .St -susv3 . The .Fn fchmodat system call is expected to conform to .St -p1003.1-2008 . .Sh HISTORY The .Fn chmod function appeared in .At v1 . The .Fn fchmod system call appeared in .Bx 4.2 . The .Fn lchmod system call appeared in .Fx 3.0 . The .Fn fchmodat system call appeared in .Fx 8.0 . Index: head/lib/libc/sys/chown.2 =================================================================== --- head/lib/libc/sys/chown.2 (revision 340346) +++ head/lib/libc/sys/chown.2 (revision 340347) @@ -1,280 +1,294 @@ .\" Copyright (c) 1980, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)chown.2 8.4 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" -.Dd Octover 20, 2018 +.Dd November 11, 2018 .Dt CHOWN 2 .Os .Sh NAME .Nm chown , .Nm fchown , .Nm lchown , .Nm fchownat .Nd change owner and group of a file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn chown "const char *path" "uid_t owner" "gid_t group" .Ft int .Fn fchown "int fd" "uid_t owner" "gid_t group" .Ft int .Fn lchown "const char *path" "uid_t owner" "gid_t group" .Ft int .Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" .Sh DESCRIPTION The owner ID and group ID of the file named by .Fa path or referenced by .Fa fd is changed as specified by the arguments .Fa owner and .Fa group . The owner of a file may change the .Fa group to a group of which he or she is a member, but the change .Fa owner capability is restricted to the super-user. .Pp The .Fn chown system call clears the set-user-id and set-group-id bits on the file to prevent accidental or mischievous creation of set-user-id and set-group-id programs if not executed by the super-user. The .Fn chown system call follows symbolic links to operate on the target of the link rather than the link itself. .Pp The .Fn fchown system call is particularly useful when used in conjunction with the file locking primitives (see .Xr flock 2 ) . .Pp The .Fn lchown system call is similar to .Fn chown but does not follow symbolic links. .Pp The .Fn fchownat system call is equivalent to the .Fn chown and .Fn lchown 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. .Pp Values for .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, ownership of the symbolic link is changed. .It Dv AT_BENEATH Only allow to change ownership of a file which is beneath of -the starting directory. +the topping directory. +See the description of the +.Dv O_BENEATH +flag in the +.Xr open 2 +manual page. .El .Pp If .Fn fchownat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fn chown or .Fn lchown respectively, depending on whether or not the .Dv AT_SYMLINK_NOFOLLOW bit is set in the .Fa flag argument. .Pp One of the owner or group id's may be left unchanged by specifying it as -1. .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn chown and .Fn lchown will fail and the file 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 ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 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 EPERM The operation would change the ownership, but the effective user ID is not the super-user. .It Bq Er EPERM The named file has its immutable or append-only flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EROFS The named file resides on a read-only file system. .It Bq Er EFAULT The .Fa path argument 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 The .Fn fchown system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument does not refer to a valid descriptor. .It Bq Er EINVAL The .Fa fd argument refers to a socket, not a file. .It Bq Er EPERM 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 EIO An I/O error occurred while reading from or writing to the file system. .El .Pp In addition to the errors specified for .Fn chown and .Fn lchown , the .Fn fchownat system call may fail 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 .Dv 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. .It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE The .Dv AT_BENEATH -flag was specified but +flag was provided to +.Fn fchownat , +and the absolute .Fa path -is not strictly relative to the starting directory. -For example, +does not have its tail fully contained under the topping directory, +or the relative .Fa path -is absolute or includes a ".." component that escapes the starting directory. +escapes it. .El .Sh SEE ALSO .Xr chgrp 1 , .Xr chflags 2 , .Xr chmod 2 , .Xr flock 2 , .Xr chown 8 .Sh STANDARDS The .Fn chown system call is expected to conform to .St -p1003.1-90 . The .Fn fchownat system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn chown function appeared in .At v1 . The .Fn fchown system call appeared in .Bx 4.2 . .Pp The .Fn chown system call was changed to follow symbolic links in .Bx 4.4 . The .Fn lchown system call was added in .Fx 3.0 to compensate for the loss of functionality. .Pp The .Fn fchownat system call appeared in .Fx 8.0 . Index: head/lib/libc/sys/link.2 =================================================================== --- head/lib/libc/sys/link.2 (revision 340346) +++ head/lib/libc/sys/link.2 (revision 340347) @@ -1,301 +1,315 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)link.2 8.3 (Berkeley) 1/12/94 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt LINK 2 .Os .Sh NAME .Nm link , .Nm linkat .Nd make a hard file link .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn link "const char *name1" "const char *name2" .Ft int .Fo linkat .Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag" .Fc .Sh DESCRIPTION The .Fn link system call atomically creates the specified directory entry (hard link) .Fa name2 with the attributes of the underlying object pointed at by .Fa name1 . If the link is successful: the link count of the underlying object is incremented; .Fa name1 and .Fa name2 share equal access and rights to the underlying object. .Pp If .Fa name1 is removed, the file .Fa name2 is not deleted and the link count of the underlying object is decremented. .Pp The object pointed at by the .Fa name1 argument must exist for the hard link to succeed and both .Fa name1 and .Fa name2 must be in the same file system. The .Fa name1 argument may not be a directory. .Pp The .Fn linkat system call is equivalent to .Fa link except in the case where either .Fa name1 or .Fa name2 or both are relative paths. In this case a relative path .Fa name1 is interpreted relative to the directory associated with the file descriptor .Fa fd1 instead of the current working directory and similarly for .Fa name2 and the file descriptor .Fa fd2 . .Pp Values for .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_FOLLOW If .Fa name1 names a symbolic link, a new link for the target of the symbolic link is created. .It Dv AT_BENEATH -Only allow to link to a file which is beneath of the starting directory. +Only allow to link to a file which is beneath of the topping directory. +See the description of the +.Dv O_BENEATH +flag in the +.Xr open 2 +manual page. .El .Pp If .Fn linkat is passed the special value .Dv AT_FDCWD in the .Fa fd1 or .Fa fd2 parameter, the current working directory is used for the respective .Fa name argument. If both .Fa fd1 and .Fa fd2 have value .Dv AT_FDCWD , the behavior is identical to a call to .Fn link . Unless .Fa flag contains the .Dv AT_SYMLINK_FOLLOW flag, if .Fa name1 names a symbolic link, a new link is created for the symbolic link .Fa name1 and not its target. .Sh RETURN VALUES .Rv -std link .Sh ERRORS The .Fn link system call will fail and no link will be created if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of either path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of either pathname exceeded 255 characters, or entire length of either path name exceeded 1023 characters. .It Bq Er ENOENT A component of either path prefix does not exist. .It Bq Er EOPNOTSUPP The file system containing the file named by .Fa name1 does not support links. .It Bq Er EMLINK The link count of the file named by .Fa name1 would exceed 32767. .It Bq Er EACCES A component of either path prefix denies search permission. .It Bq Er EACCES The requested link requires writing in a directory with a mode that denies write permission. .It Bq Er ELOOP Too many symbolic links were encountered in translating one of the pathnames. .It Bq Er ENOENT The file named by .Fa name1 does not exist. .It Bq Er EEXIST The link named by .Fa name2 does exist. .It Bq Er EPERM The file named by .Fa name1 is a directory. .It Bq Er EPERM The file named by .Fa name1 has its immutable or append-only flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EPERM The parent directory of the file named by .Fa name2 has its immutable flag set. .It Bq Er EXDEV The link named by .Fa name2 and the file named by .Fa name1 are on different file systems. .It Bq Er ENOSPC The directory in which the entry for the new link is being placed cannot be extended because there is no space left on the file system containing the directory. .It Bq Er EDQUOT The directory in which the entry for the new link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system to make the directory entry. .It Bq Er EROFS The requested link requires writing in a directory on a read-only file system. .It Bq Er EFAULT One of the pathnames specified is outside the process's allocated address space. .El .Pp In addition to the errors returned by the .Fn link , the .Fn linkat system call may fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa name1 or .Fa name2 argument does not specify an absolute path and the .Fa fd1 or .Fa fd2 argument, respectively, is neither .Dv 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 name1 or .Fa name2 argument is not an absolute path and .Fa fd1 or .Fa fd2 , respectively, is neither .Dv AT_FDCWD nor a file descriptor associated with a directory. .It Bq Er ENOTCAPABLE -The -.Dv AT_BENEATH -flag was specified but .Fa name1 is not strictly relative to the starting directory. For example, .Fa name1 -is absolute or includes a ".." component that escapes the starting directory. +is absolute or includes a ".." component that escapes +the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE +The .Dv AT_BENEATH -flag was specified. +flag was provided to +.Fa linkat +and the absolute path +.Fa name1 +does not have its tail fully contained under the topping directory, +or the relative path +.Fa name1 +escapes it. .El .Sh SEE ALSO .Xr chflags 2 , .Xr readlink 2 , .Xr symlink 2 , .Xr unlink 2 .Sh STANDARDS The .Fn link system call is expected to conform to .St -p1003.1-90 . The .Fn linkat system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn link function appeared in .At v1 . The .Fn linkat system call appeared in .Fx 8.0 . .Pp The .Fn link system call traditionally allows the super-user to link directories which corrupts the file system coherency. This implementation no longer permits it. Index: head/lib/libc/sys/open.2 =================================================================== --- head/lib/libc/sys/open.2 (revision 340346) +++ head/lib/libc/sys/open.2 (revision 340347) @@ -1,566 +1,615 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)open.2 8.2 (Berkeley) 11/16/93 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt OPEN 2 .Os .Sh NAME .Nm open , openat .Nd open or create a file for reading, writing or executing .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In fcntl.h .Ft int .Fn open "const char *path" "int flags" "..." .Ft int .Fn openat "int fd" "const char *path" "int flags" "..." .Sh DESCRIPTION The file name specified by .Fa path is opened for either execution or reading and/or writing as specified by the argument .Fa flags and the file descriptor returned to the calling process. The .Fa flags argument may indicate the file is to be created if it does not exist (by specifying the .Dv O_CREAT flag). In this case .Fn open and .Fn openat require an additional argument .Fa "mode_t mode" , and the file is created with mode .Fa mode as described in .Xr chmod 2 and modified by the process' umask value (see .Xr umask 2 ) . .Pp The .Fn openat function is equivalent to the .Fn open function except in the case where the .Fa path -specifies a relative path. -In this case the file to be opened is determined relative to the directory +specifies a relative path, or the +.Dv O_BENEATH +flag is provided. +For +.Fn openat +and relative +.Fa path , +the file to be opened is determined relative to the directory associated with the file descriptor .Fa fd instead of the current working directory. The .Fa flag parameter and the optional fourth parameter correspond exactly to the parameters of .Fn open . If .Fn openat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fn open . .Pp +When +.Fn openat +is called with an absolute +.Fa path +without the +.Dv O_BENEATH +flag, it ignores the +.Fa fd +argument. +When +.Dv O_BENEATH +is specified with an absolute +.Fa path , +a directory passed by the +.Fa fd +argument is used as the topping point for the resolution. +See the definition of the +.Dv O_BENEATH +flag below. +.Pp In .Xr capsicum 4 capability mode, .Fn open is not permitted. The .Fa path argument to .Fn openat must be strictly relative to a file descriptor .Fa fd , as defined in .Pa sys/kern/vfs_lookup.c . .Fa path -must not be an absolute path and must not contain ".." components. +must not be an absolute path and must not contain ".." components +which cause the path resolution to escape the directory hierarchy +starting at +.Fa fd . Additionally, no symbolic link in .Fa path -may contain ".." components either. +may target absolute path or contain escaping ".." components. .Fa fd must not be .Dv AT_FDCWD . .Pp +If the +.Dv vfs.lookup_cap_dotdot +.Xr sysctl 3 +MIB is set to zero, ".." components in the paths, +used in capability mode, or with the +.Dv O_BENEATH +flag, are completely disabled. +If the +.Dv vfs.lookup_cap_dotdot_nonlocal +MIB is set to zero, ".." is not allowed if found on non-local filesystem. +.Pp The flags specified are formed by .Em or Ns 'ing the following values .Pp .Bd -literal -offset indent -compact O_RDONLY open for reading only O_WRONLY open for writing only O_RDWR open for reading and writing O_EXEC open for execute only O_NONBLOCK do not block on open O_APPEND append on each write O_CREAT create file if it does not exist O_TRUNC truncate size to 0 O_EXCL error if create and file exists O_SHLOCK atomically obtain a shared lock O_EXLOCK atomically obtain an exclusive lock O_DIRECT eliminate or reduce cache effects O_FSYNC synchronous writes O_SYNC synchronous writes O_NOFOLLOW do not follow symlinks O_NOCTTY ignored O_TTY_INIT ignored O_DIRECTORY error if file is not a directory O_CLOEXEC set FD_CLOEXEC upon open O_VERIFY verify the contents of the file -O_BENEATH require path to be strictly relative to starting directory +O_BENEATH require path to be strictly relative to topping directory .Ed .Pp Opening a file with .Dv O_APPEND set causes each write on the file to be appended to the end. If .Dv O_TRUNC is specified and the file exists, the file is truncated to zero length. If .Dv O_EXCL is set with .Dv O_CREAT and the file already exists, .Fn open returns an error. This may be used to implement a simple exclusive access locking mechanism. If .Dv O_EXCL is set and the last component of the pathname is a symbolic link, .Fn open will fail even if the symbolic link points to a non-existent name. If the .Dv O_NONBLOCK flag is specified and the .Fn open system call would result in the process being blocked for some reason (e.g., waiting for carrier on a dialup line), .Fn open returns immediately. The descriptor remains in non-blocking mode for subsequent operations. .Pp If .Dv O_FSYNC is used in the mask, all writes will immediately be written to disk, the kernel will not cache written data and all writes on the descriptor will not return until the data to be written completes. .Pp .Dv O_SYNC is a synonym for .Dv O_FSYNC required by .Tn POSIX . .Pp If .Dv O_NOFOLLOW is used in the mask and the target file passed to .Fn open is a symbolic link then the .Fn open will fail. .Pp When opening a file, a lock with .Xr flock 2 semantics can be obtained by setting .Dv O_SHLOCK for a shared lock, or .Dv O_EXLOCK for an exclusive lock. If creating a file with .Dv O_CREAT , the request for the lock will never fail (provided that the underlying file system supports locking). .Pp .Dv O_DIRECT may be used to minimize or eliminate the cache effects of reading and writing. The system will attempt to avoid caching the data you read or write. If it cannot avoid caching the data, it will minimize the impact the data has on the cache. Use of this flag can drastically reduce performance if not used with care. .Pp .Dv O_NOCTTY may be used to ensure the OS does not assign this file as the controlling terminal when it opens a tty device. This is the default on .Fx , but is present for .Tn POSIX compatibility. The .Fn open system call will not assign controlling terminals on .Fx . .Pp .Dv O_TTY_INIT may be used to ensure the OS restores the terminal attributes when initially opening a TTY. This is the default on .Fx , but is present for .Tn POSIX compatibility. The initial call to .Fn open on a TTY will always restore default terminal attributes on .Fx . .Pp .Dv O_DIRECTORY may be used to ensure the resulting file descriptor refers to a directory. This flag can be used to prevent applications with elevated privileges from opening files which are even unsafe to open with .Dv O_RDONLY , such as device nodes. .Pp .Dv O_CLOEXEC may be used to set .Dv FD_CLOEXEC flag for the newly returned file descriptor. .Pp .Dv O_VERIFY may be used to indicate to the kernel that the contents of the file should be verified before allowing the open to proceed. The details of what .Dq verified means is implementation specific. The run-time linker (rtld) uses this flag to ensure shared objects have been verified before operating on them. .Pp .Dv O_BENEATH returns .Er ENOTCAPABLE -if the specified path, after resolving all symlinks and ".." references -in it, does not reside in the directory hierarchy of children beneath -the starting directory, or is an absolute path. -Starting directory is the process current directory if relative +if the specified relative path, after resolving all symlinks and ".." +references, does not reside in the directory hierarchy of +children beneath the topping directory. +Topping directory is the process current directory if relative .Fa path is used for .Fn open , and the directory referenced by the .Fa fd -argument when specifying relative -.Fa path -for +argument when using .Fn openat . +If the specified path is absolute, +.Dv O_BENEATH +allows arbitrary prefix that ends up at the topping directory, +after which all further resolved components must be under it. .Pp If successful, .Fn open returns a non-negative integer, termed a file descriptor. It returns \-1 on failure. The file pointer used to mark the current position within the file is set to the beginning of the file. .Pp If a sleeping open of a device node from .Xr devfs 5 is interrupted by a signal, the call always fails with .Er EINTR , even if the .Dv SA_RESTART flag is set for the signal. A sleeping open of a fifo (see .Xr mkfifo 2 ) is restarted as normal. .Pp When a new file is created it is given the group of the directory which contains it. .Pp Unless .Dv O_CLOEXEC flag was specified, the new descriptor is set to remain open across .Xr execve 2 system calls; see .Xr close 2 , .Xr fcntl 2 and .Dv O_CLOEXEC description. .Pp The system imposes a limit on the number of file descriptors open simultaneously by one process. The .Xr getdtablesize 2 system call returns the current system limit. .Sh RETURN VALUES If successful, .Fn open and .Fn openat return a non-negative integer, termed a file descriptor. They return \-1 on failure, and set .Va errno to indicate the error. .Sh ERRORS The named file is opened unless: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOENT .Dv O_CREAT is not set and the named file does not exist. .It Bq Er ENOENT A component of the path name that must exist does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EACCES The required permissions (for reading and/or writing) are denied for the given flags. .It Bq Er EACCES .Dv O_TRUNC is specified and write permission is denied. .It Bq Er EACCES .Dv O_CREAT is specified, the file does not exist, and the directory in which it is to be created does not permit writing. .It Bq Er EPERM .Dv O_CREAT is specified, the file does not exist, and the directory in which it is to be created has its immutable flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EPERM The named file has its immutable flag set and the file is to be modified. .It Bq Er EPERM The named file has its append-only flag set, the file is to be modified, and .Dv O_TRUNC is specified or .Dv O_APPEND is not specified. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EISDIR The named file is a directory, and the arguments specify it is to be modified. .It Bq Er EROFS The named file resides on a read-only file system, and the file is to be modified. .It Bq Er EROFS .Dv O_CREAT is specified and the named file would reside on a read-only file system. .It Bq Er EMFILE The process has already reached its limit for open file descriptors. .It Bq Er ENFILE The system file table is full. .It Bq Er EMLINK .Dv O_NOFOLLOW was specified and the target is a symbolic link. .It Bq Er ENXIO The named file is a character special or block special file, and the device associated with this special file does not exist. .It Bq Er ENXIO .Dv O_NONBLOCK is set, the named file is a fifo, .Dv O_WRONLY is set, and no process has the file open for reading. .It Bq Er EINTR The .Fn open operation was interrupted by a signal. .It Bq Er EOPNOTSUPP .Dv O_SHLOCK or .Dv O_EXLOCK is specified but the underlying file system does not support locking. .It Bq Er EOPNOTSUPP The named file is a special file mounted through a file system that does not support access to it (e.g.\& NFS). .It Bq Er EWOULDBLOCK .Dv O_NONBLOCK and one of .Dv O_SHLOCK or .Dv O_EXLOCK is specified and the file is locked. .It Bq Er ENOSPC .Dv O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because there is no space left on the file system containing the directory. .It Bq Er ENOSPC .Dv O_CREAT is specified, the file does not exist, and there are no free inodes on the file system on which the file is being created. .It Bq Er EDQUOT .Dv O_CREAT is specified, the file does not exist, and the directory in which the entry for the new file is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted. .It Bq Er EDQUOT .Dv O_CREAT is specified, the file does not exist, and the user's quota of inodes on the file system on which the file is being created has been exhausted. .It Bq Er EIO An I/O error occurred while making the directory entry or allocating the inode for .Dv O_CREAT . .It Bq Er ETXTBSY The file is a pure procedure (shared text) file that is being executed and the .Fn open system call requests write access. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er EEXIST .Dv O_CREAT and .Dv O_EXCL were specified and the file exists. .It Bq Er EOPNOTSUPP An attempt was made to open a socket (not currently implemented). .It Bq Er EINVAL An attempt was made to open a descriptor with an illegal combination of .Dv O_RDONLY , .Dv O_WRONLY , .Dv O_RDWR and .Dv O_EXEC . .It Bq Er EBADF The .Fa path argument does not specify an absolute path and the .Fa fd argument is neither .Dv AT_FDCWD nor a valid file descriptor open for searching. .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. .It Bq Er ENOTDIR .Dv O_DIRECTORY is specified and the file is not a directory. .It Bq Er ECAPMODE .Dv AT_FDCWD is specified and the process is in capability mode. .It Bq Er ECAPMODE .Fn open was called and the process is in capability mode. .It Bq Er ENOTCAPABLE .Fa path is an absolute path, or contained a ".." component leading to a directory outside of the directory hierarchy specified by .Fa fd , -and the process is in capability mode or the +and the process is in capability mode. +.It Bq Er ENOTCAPABLE +The .Dv O_BENEATH -flag was provided. +flag was provided, and the absolute +.Fa path +does not have its tail fully contained under the topping directory, +or the relative +.Fa path +escapes it. .El .Sh SEE ALSO .Xr chmod 2 , .Xr close 2 , .Xr dup 2 , .Xr fexecve 2 , .Xr fhopen 2 , .Xr getdtablesize 2 , .Xr getfh 2 , .Xr lgetfh 2 , .Xr lseek 2 , .Xr read 2 , .Xr umask 2 , .Xr write 2 , .Xr fopen 3 , .Xr capsicum 4 .Sh STANDARDS These functions are specified by .St -p1003.1-2008 . .Fx sets .Va errno to .Er EMLINK instead of .Er ELOOP as specified by .Tn POSIX when .Dv O_NOFOLLOW is set in flags and the final component of pathname is a symbolic link to distinguish it from the case of too many symbolic link traversals in one of its non-final components. .Sh HISTORY The .Fn open function appeared in .At v1 . The .Fn openat function was introduced in .Fx 8.0 . .Sh BUGS The Open Group Extended API Set 2 specification requires that the test for whether .Fa fd is searchable is based on whether .Fa fd is open for searching, not whether the underlying directory currently permits searches. The present implementation of the .Fa openat checks the current permissions of directory instead. Index: head/lib/libc/sys/stat.2 =================================================================== --- head/lib/libc/sys/stat.2 (revision 340346) +++ head/lib/libc/sys/stat.2 (revision 340347) @@ -1,457 +1,496 @@ .\" Copyright (c) 1980, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)stat.2 8.4 (Berkeley) 5/1/95 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt STAT 2 .Os .Sh NAME .Nm stat , .Nm lstat , .Nm fstat , .Nm fstatat .Nd get file status .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/stat.h .Ft int .Fn stat "const char * restrict path" "struct stat * restrict sb" .Ft int .Fn lstat "const char * restrict path" "struct stat * restrict sb" .Ft int .Fn fstat "int fd" "struct stat *sb" .Ft int .Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag" .Sh DESCRIPTION The .Fn stat system call obtains information about the file pointed to by .Fa path . Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. .Pp The .Fn lstat system call is like .Fn stat except when the named file is a symbolic link, in which case .Fn lstat returns information about the link, while .Fn stat returns information about the file the link references. .Pp The .Fn fstat system call obtains the same information about an open file known by the file descriptor .Fa fd . .Pp The .Fn fstatat system call is equivalent to .Fn stat and .Fn lstat except when the .Fa path -specifies a relative path. -In this case the status is retrieved from a file relative to +specifies a relative path, or the +.Dv AT_BENEATH +flag is provided. +For +.Fn fstatat +and relative +.Fa path , +the status is retrieved from a file relative to the directory associated with the file descriptor .Fa fd instead of the current working directory. +For +.Dv AT_BENEATH +and absolute +.Fa path , +the status is retrieved from a file specified by the +.Fa path , +but additional permission checks are performed, see below. .Pp The values for the .Fa flag are constructed by a bitwise-inclusive OR of flags from this list, defined in .In fcntl.h : .Bl -tag -width indent .It Dv AT_SYMLINK_NOFOLLOW If .Fa path names a symbolic link, the status of the symbolic link is returned. .It Dv AT_BENEATH -Only stat files and directories below the starting directory. +Only stat files and directories below the topping directory. See the description of the .Dv O_BENEATH flag in the .Xr open 2 manual page. .El .Pp If .Fn fstatat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fn stat or .Fn lstat respectively, depending on whether or not the .Dv AT_SYMLINK_NOFOLLOW bit is set in .Fa flag . .Pp +When +.Fn fstatat +is called with an absolute +.Fa path +without the +.Dv AT_BENEATH +flag, it ignores the +.Fa fd +argument. +When +.Dv AT_BENEATH +is specified with an absolute +.Fa path , +a directory passed by the +.Fa fd +argument is used as the topping point for the resolution. +.Pp The .Fa sb argument is a pointer to a .Vt stat structure as defined by .In sys/stat.h and into which information is placed concerning the file. .Pp The fields of .Vt "struct stat" related to the file system are: .Bl -tag -width ".Va st_nlink" .It Va st_dev Numeric ID of the device containing the file. .It Va st_ino The file's inode number. .It Va st_nlink Number of hard links to the file. .It Va st_flags Flags enabled for the file. See .Xr chflags 2 for the list of flags and their description. .El .Pp The .Va st_dev and .Va st_ino fields together identify the file uniquely within the system. .Pp The time-related fields of .Vt "struct stat" are: .Bl -tag -width ".Va st_birthtim" .It Va st_atim Time when file data was last accessed. Changed by the .Xr mknod 2 , .Xr utimes 2 , .Xr read 2 and .Xr readv 2 system calls. .It Va st_mtim Time when file data was last modified. Changed by the .Xr mkdir 2 , .Xr mkfifo 2 , .Xr mknod 2 , .Xr utimes 2 , .Xr write 2 and .Xr writev 2 system calls. .It Va st_ctim Time when file status was last changed (inode data modification). Changed by the .Xr chflags 2 , .Xr chmod 2 , .Xr chown 2 , .Xr creat 2 , .Xr link 2 , .Xr mkdir 2 , .Xr mkfifo 2 , .Xr mknod 2 , .Xr rename 2 , .Xr rmdir 2 , .Xr symlink 2 , .Xr truncate 2 , .Xr unlink 2 , .Xr utimes 2 , .Xr write 2 and .Xr writev 2 system calls. .It Va st_birthtim Time when the inode was created. .El .Pp These time-related macros are defined for compatibility: .Bd -literal #define st_atime st_atim.tv_sec #define st_mtime st_mtim.tv_sec #define st_ctime st_ctim.tv_sec #ifndef _POSIX_SOURCE #define st_birthtime st_birthtim.tv_sec #endif #ifndef _POSIX_SOURCE #define st_atimespec st_atim #define st_mtimespec st_mtim #define st_ctimespec st_ctim #define st_birthtimespec st_birthtim #endif .Ed .Pp Size-related fields of the .Vt "struct stat" are: .Bl -tag -width ".Va st_blksize" .It Va st_size File size in bytes. .It Va st_blksize Optimal I/O block size for the file. .It Va st_blocks Actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. .El .Pp The access-related fields of .Vt "struct stat" are: .Bl -tag -width ".Va st_mode" .It Va st_uid User ID of the file's owner. .It Va st_gid Group ID of the file. .It Va st_mode Status of the file (see below). .El .Pp The status information word .Fa st_mode has these bits: .Bd -literal #define S_IFMT 0170000 /* type of file mask */ #define S_IFIFO 0010000 /* named pipe (fifo) */ #define S_IFCHR 0020000 /* character special */ #define S_IFDIR 0040000 /* directory */ #define S_IFBLK 0060000 /* block special */ #define S_IFREG 0100000 /* regular */ #define S_IFLNK 0120000 /* symbolic link */ #define S_IFSOCK 0140000 /* socket */ #define S_IFWHT 0160000 /* whiteout */ #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 */ #define S_IRWXU 0000700 /* RWX mask for owner */ #define S_IRUSR 0000400 /* read permission, owner */ #define S_IWUSR 0000200 /* write permission, owner */ #define S_IXUSR 0000100 /* execute/search permission, owner */ #define S_IRWXG 0000070 /* RWX mask for group */ #define S_IRGRP 0000040 /* read permission, group */ #define S_IWGRP 0000020 /* write permission, group */ #define S_IXGRP 0000010 /* execute/search permission, group */ #define S_IRWXO 0000007 /* RWX mask for other */ #define S_IROTH 0000004 /* read permission, other */ #define S_IWOTH 0000002 /* write permission, other */ #define S_IXOTH 0000001 /* execute/search permission, other */ .Ed .Pp For a list of access modes, see .In sys/stat.h , .Xr access 2 and .Xr chmod 2 . These macros are available to test whether a .Va st_mode value passed in the .Fa m argument corresponds to a file of the specified type: .Bl -tag -width ".Fn S_ISFIFO m" .It Fn S_ISBLK m Test for a block special file. .It Fn S_ISCHR m Test for a character special file. .It Fn S_ISDIR m Test for a directory. .It Fn S_ISFIFO m Test for a pipe or FIFO special file. .It Fn S_ISLNK m Test for a symbolic link. .It Fn S_ISREG m Test for a regular file. .It Fn S_ISSOCK m Test for a socket. .It Fn S_ISWHT m Test for a whiteout. .El .Pp The macros evaluate to a non-zero value if the test is true or to the value 0 if the test is false. .Sh RETURN VALUES .Rv -std .Sh COMPATIBILITY Previous versions of the system used different types for the .Va st_dev , .Va st_uid , .Va st_gid , .Va st_rdev , .Va st_size , .Va st_blksize and .Va st_blocks fields. .Sh ERRORS The .Fn stat and .Fn lstat system calls will fail if: .Bl -tag -width Er .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EFAULT The .Fa sb or .Fa path argument points to an invalid address. .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. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOENT The named file does not exist. .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er EOVERFLOW The file size in bytes cannot be represented correctly in the structure pointed to by .Fa sb . .El .Pp The .Fn fstat system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid open file descriptor. .It Bq Er EFAULT The .Fa sb argument points to an invalid address. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .It Bq Er EOVERFLOW The file size in bytes cannot be represented correctly in the structure pointed to by .Fa sb . .El .Pp In addition to the errors returned by the .Fn lstat , the .Fn fstatat may fail 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 .Dv 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. .It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE The .Dv AT_BENEATH -flag was specified but +flag was provided to +.Fn fstatat , +and the absolute .Fa path -is not strictly relative to the starting directory. -For example, +does not have its tail fully contained under the topping directory, +or the relative .Fa path -is absolute or includes a ".." component that escapes the starting directory. +escapes it. .El .Sh SEE ALSO .Xr access 2 , .Xr chmod 2 , .Xr chown 2 , .Xr fhstat 2 , .Xr statfs 2 , .Xr utimes 2 , .Xr sticky 7 , .Xr symlink 7 .Sh STANDARDS The .Fn stat and .Fn fstat system calls are expected to conform to .St -p1003.1-90 . The .Fn fstatat system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn stat and .Fn fstat system calls appeared in .At v1 . The .Fn lstat system call appeared in .Bx 4.2 . The .Fn fstatat system call appeared in .Fx 8.0 . .Sh BUGS Applying .Fn fstat to a socket returns a zeroed buffer, except for the blocksize field, and a unique device and inode number. Index: head/lib/libc/sys/unlink.2 =================================================================== --- head/lib/libc/sys/unlink.2 (revision 340346) +++ head/lib/libc/sys/unlink.2 (revision 340347) @@ -1,240 +1,254 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)unlink.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt UNLINK 2 .Os .Sh NAME .Nm unlink , .Nm unlinkat .Nd remove directory entry .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn unlink "const char *path" .Ft int .Fn unlinkat "int fd" "const char *path" "int flag" .Sh DESCRIPTION The .Fn unlink system call removes the link named by .Fa path from its directory and decrements the link count of the file which was referenced by the link. If that decrement reduces the link count of the file to zero, and no process has the file open, then all resources associated with the file are reclaimed. If one or more process have the file open when the last link is removed, the link is removed, but the removal of the file is delayed until all references to it have been closed. The .Fa path argument may not be a directory. .Pp The .Fn unlinkat system call is equivalent to .Fn unlink or .Fn rmdir except in the case where .Fa path specifies a relative path. In this case the directory entry to be removed is determined relative to the directory associated with the file descriptor .Fa fd instead of the current working directory. .Pp The values for .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_REMOVEDIR Remove the directory entry specified by .Fa fd and .Fa path as a directory, not a normal file. .It Dv AT_BENEATH -Only unlink files and directories which are beneath of the starting +Only unlink files and directories which are beneath of the topping directory. +See the description of the +.Dv O_BENEATH +flag in the +.Xr open 2 +manual page. .El .Pp If .Fn unlinkat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fa unlink or .Fa rmdir respectively, depending on whether or not the .Dv AT_REMOVEDIR bit is set in flag. .Sh RETURN VALUES .Rv -std unlink .Sh ERRORS The .Fn unlink succeeds unless: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er EISDIR The named file is a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 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 EACCES Write permission is denied on the directory containing the link to be removed. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EPERM The named file is a directory. .It Bq Er EPERM The named file has its immutable, undeletable or append-only flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EPERM The parent directory of the named file has its immutable or append-only flag set. .It Bq Er EPERM The directory containing the file is marked sticky, and neither the containing directory nor the file to be removed are owned by the effective user ID. .It Bq Er EIO An I/O error occurred while deleting the directory entry or deallocating the inode. .It Bq Er EROFS The named file resides on a read-only file system. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er ENOSPC On file systems supporting copy-on-write or snapshots, there was not enough free space to record metadata for the delete operation of the file. .El .Pp In addition to the errors returned by the .Fn unlink , the .Fn unlinkat may fail 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 .Dv AT_FDCWD nor a valid file descriptor open for searching. .It Bq Er ENOTEMPTY The .Fa flag parameter has the .Dv AT_REMOVEDIR bit set and the .Fa path argument names a directory that is not an empty directory, or there are hard links to the directory other than dot or a single entry in dot-dot. .It Bq Er ENOTDIR The .Fa flag parameter has the .Dv AT_REMOVEDIR bit set and .Fa path does not name a directory. .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. .It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE The .Dv AT_BENEATH -flag was specified but +flag was provided to +.Fn unlinkat , +and the absolute .Fa path -is not strictly relative to the starting directory. -For example, +does not have its tail fully contained under the topping directory, +or the relative .Fa path -is absolute or includes a ".." component that escapes the starting directory. +escapes it. .El .Sh SEE ALSO .Xr chflags 2 , .Xr close 2 , .Xr link 2 , .Xr rmdir 2 , .Xr symlink 7 .Sh STANDARDS The .Fn unlinkat system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn unlink function appeared in .At v1 . The .Fn unlinkat system call appeared in .Fx 8.0 . .Pp The .Fn unlink system call traditionally allows the super-user to unlink directories which can damage the file system integrity. This implementation no longer permits it. Index: head/lib/libc/sys/utimensat.2 =================================================================== --- head/lib/libc/sys/utimensat.2 (revision 340346) +++ head/lib/libc/sys/utimensat.2 (revision 340347) @@ -1,303 +1,317 @@ .\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $ .\" .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" Copyright (c) 2012, Jilles Tjoelker .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)utimes.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd October 20, 2018 +.Dd November 11, 2018 .Dt UTIMENSAT 2 .Os .Sh NAME .Nm futimens , .Nm utimensat .Nd set file access and modification times .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/stat.h .Ft int .Fn futimens "int fd" "const struct timespec times[2]" .Ft int .Fo utimensat .Fa "int fd" .Fa "const char *path" .Fa "const struct timespec times[2]" .Fa "int flag" .Fc .Sh DESCRIPTION The access and modification times of the file named by .Fa path or referenced by .Fa fd are changed as specified by the argument .Fa times . The inode-change-time of the file is set to the current time. .Pp If .Fa path specifies a relative path, it is relative to the current working directory if .Fa fd is .Dv AT_FDCWD and otherwise relative to the directory associated with the file descriptor .Fa fd . .Pp The .Va tv_nsec field of a .Vt timespec structure can be set to the special value .Dv UTIME_NOW to set the current time, or to .Dv UTIME_OMIT to leave the time unchanged. In either case, the .Va tv_sec field is ignored. .Pp If .Fa times is .No non- Ns Dv NULL , it is assumed to point to an array of two timespec structures. The access time is set to the value of the first element, and the modification time is set to the value of the second element. For file systems that support file birth (creation) times (such as .Dv UFS2 ) , the birth time will be set to the value of the second element if the second element is older than the currently set birth time. To set both a birth time and a modification time, two calls are required; the first to set the birth time and the second to set the (presumably newer) modification time. Ideally a new system call will be added that allows the setting of all three times at once. If .Fa times is .Dv NULL , this is equivalent to passing a pointer to an array of two timespec structures with both .Va tv_nsec fields set to .Dv UTIME_NOW . .Pp If both .Va tv_nsec fields are .Dv UTIME_OMIT , the timestamps remain unchanged and no permissions are needed for the file itself, although search permissions may be required for the path prefix. The call may or may not succeed if the named file does not exist. .Pp If both .Va tv_nsec fields are .Dv UTIME_NOW , the caller must be the owner of the file, have permission to write the file, or be the super-user. .Pp For all other values of the timestamps, the caller must be the owner of the file or be the super-user. .Pp The values for the .Fa flag argument of the .Fn utimensat system call 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, the symbolic link's times are changed. By default, .Fn utimensat changes the times of the file referenced by the symbolic link. .It Dv AT_BENEATH Only allow to change the times of a file which is beneath of -the starting directory. +the topping directory. +See the description of the +.Dv O_BENEATH +flag in the +.Xr open 2 +manual page. .El .Sh RETURN VALUES .Rv -std .Sh COMPATIBILITY If the running kernel does not support this system call, a wrapper emulates it using .Xr fstatat 2 , .Xr futimesat 2 and .Xr lutimes 2 . As a result, timestamps will be rounded down to the nearest microsecond, .Dv UTIME_OMIT is not atomic and .Dv AT_SYMLINK_NOFOLLOW is not available with a path relative to a file descriptor. .Sh ERRORS These system calls will fail if: .Bl -tag -width Er .It Bq Er EACCES The .Fa times argument is .Dv NULL , or both .Va tv_nsec values are .Dv UTIME_NOW , and the effective user ID of the process does not match the owner of the file, and is not the super-user, and write access is denied. .It Bq Er EFAULT The .Fa times argument points outside the process's allocated address space. .It Bq Er EINVAL The .Va tv_nsec component of at least one of the values specified by the .Fa times argument has a value less than 0 or greater than 999999999 and is not equal to .Dv UTIME_NOW or .Dv UTIME_OMIT . .It Bq Er EIO An I/O error occurred while reading or writing the affected inode. .It Bq Er EPERM The .Fa times argument is not .Dv NULL nor are both .Va tv_nsec values .Dv UTIME_NOW , nor are both .Va tv_nsec values .Dv UTIME_OMIT and the calling process's effective user ID does not match the owner of the file and is not the super-user. .It Bq Er EPERM The named file has its immutable or append-only flag set, see the .Xr chflags 2 manual page for more information. .It Bq Er EROFS The file system containing the file is mounted read-only. .El .Pp The .Fn futimens system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument does not refer to a valid descriptor. .El .Pp The .Fn utimensat system call will fail if: .Bl -tag -width Er .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EBADF The .Fa path argument does not specify an absolute path and the .Fa fd argument is neither .Dv AT_FDCWD nor a valid file descriptor. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .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 ENOTDIR A component of the path prefix is not a directory. .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. .It Bq Er ENOTCAPABLE +.Fa path +is an absolute path, +or contained a ".." component leading to a +directory outside of the directory hierarchy specified by +.Fa fd , +and the process is in capability mode. +.It Bq Er ENOTCAPABLE The .Dv AT_BENEATH -flag was specified but +flag was provided to +.Fn utimensat , +and the absolute .Fa path -is not strictly relative to the starting directory. -For example, +does not have its tail fully contained under the topping directory, +or the relative .Fa path -is absolute or includes a ".." component that escapes the starting directory. +escapes it. .El .Sh SEE ALSO .Xr chflags 2 , .Xr stat 2 , .Xr symlink 2 , .Xr utimes 2 , .Xr utime 3 , .Xr symlink 7 .Sh STANDARDS The .Fn futimens and .Fn utimensat system calls are expected to conform to .St -p1003.1-2008 . .Sh HISTORY The .Fn futimens and .Fn utimensat system calls appeared in .Fx 10.3 .