diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2 index 37225f9571d0..ab686266cd21 100644 --- a/lib/libc/sys/link.2 +++ b/lib/libc/sys/link.2 @@ -1,319 +1,319 @@ .\" 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 March 30, 2021 .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_RESOLVE_BENEATH Only walk paths below the directory specified by the .Ar fd1 descriptor. See the description of the .Dv O_RESOLVE_BENEATH flag in the .Xr open 2 manual page. .It Dv AT_EMPTY_PATH If the -.Fa path2 +.Fa name1 argument is an empty string, link the file referenced by the descriptor -.Fa fd2 . +.Fa fd1 . The operation requires that the calling process has the .Dv PRIV_VFS_FHOPEN privilege, effectively being executed with effective user .Dv root . .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 EINTEGRITY Corrupted data was detected while reading from the file system. .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 .Fa name1 is not strictly relative to the starting directory. For example, .Fa name1 is absolute or includes a ".." component that escapes the directory hierarchy specified by .Fa fd , and the process is in capability mode or the .Dv AT_RESOLVE_BENEATH flag was specified. .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. diff --git a/lib/libc/sys/shm_open.2 b/lib/libc/sys/shm_open.2 index edf5440d44c4..4c03288b6bbe 100644 --- a/lib/libc/sys/shm_open.2 +++ b/lib/libc/sys/shm_open.2 @@ -1,473 +1,473 @@ .\" .\" Copyright 2000 Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software and .\" its documentation for any purpose and without fee is hereby .\" granted, provided that both the above copyright notice and this .\" permission notice appear in all copies, that both the above .\" copyright notice and this permission notice appear in all .\" supporting documentation, and that the name of M.I.T. not be used .\" in advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. M.I.T. makes .\" no representations about the suitability of this software for any .\" purpose. It is provided "as is" without express or implied .\" warranty. .\" .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT .\" SHALL M.I.T. 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. .\" .\" $FreeBSD$ .\" .Dd June 25, 2021 .Dt SHM_OPEN 2 .Os .Sh NAME .Nm memfd_create , shm_open , shm_rename, shm_unlink .Nd "shared memory object operations" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/mman.h .In fcntl.h .Ft int .Fn memfd_create "const char *name" "unsigned int flags" .Ft int .Fn shm_open "const char *path" "int flags" "mode_t mode" .Ft int .Fn shm_rename "const char *path_from" "const char *path_to" "int flags" .Ft int .Fn shm_unlink "const char *path" .Sh DESCRIPTION The .Fn shm_open system call opens (or optionally creates) a POSIX shared memory object named .Fa path . The .Fa flags argument contains a subset of the flags used by .Xr open 2 . An access mode of either .Dv O_RDONLY or .Dv O_RDWR must be included in .Fa flags . The optional flags .Dv O_CREAT , .Dv O_EXCL , and .Dv O_TRUNC may also be specified. .Pp If .Dv O_CREAT is specified, then a new shared memory object named .Fa path will be created if it does not exist. In this case, the shared memory object is created with mode .Fa mode subject to the process' umask value. If both the .Dv O_CREAT and .Dv O_EXCL flags are specified and a shared memory object named .Fa path already exists, then .Fn shm_open will fail with .Er EEXIST . .Pp Newly created objects start off with a size of zero. If an existing shared memory object is opened with .Dv O_RDWR and the .Dv O_TRUNC flag is specified, then the shared memory object will be truncated to a size of zero. The size of the object can be adjusted via .Xr ftruncate 2 and queried via .Xr fstat 2 . .Pp The new descriptor is set to close during .Xr execve 2 system calls; see .Xr close 2 and .Xr fcntl 2 . .Pp As a .Fx extension, the constant .Dv SHM_ANON may be used for the .Fa path argument to .Fn shm_open . In this case, an anonymous, unnamed shared memory object is created. Since the object has no name, it cannot be removed via a subsequent call to .Fn shm_unlink , or moved with a call to .Fn shm_rename . Instead, the shared memory object will be garbage collected when the last reference to the shared memory object is removed. The shared memory object may be shared with other processes by sharing the file descriptor via .Xr fork 2 or .Xr sendmsg 2 . Attempting to open an anonymous shared memory object with .Dv O_RDONLY will fail with .Er EINVAL . All other flags are ignored. .Pp The .Fn shm_rename system call atomically removes a shared memory object named .Fa path_from and relinks it at .Fa path_to . If another object is already linked at .Fa path_to , that object will be unlinked, unless one of the following flags are provided: .Bl -tag -offset indent -width Er .It Er SHM_RENAME_EXCHANGE Atomically exchange the shms at .Fa path_from and .Fa path_to . .It Er SHM_RENAME_NOREPLACE Return an error if an shm exists at .Fa path_to , rather than unlinking it. .El .Fn shm_rename is also a .Fx extension. .Pp The .Fn shm_unlink system call removes a shared memory object named .Fa path . .Pp The .Fn memfd_create function creates an anonymous shared memory object, identical to that created by .Fn shm_open when .Dv SHM_ANON is specified. Newly created objects start off with a size of zero. The size of the new object must be adjusted via .Xr ftruncate 2 . .Pp The .Fa name argument must not be .Dv NULL , but it may be an empty string. The length of the .Fa name argument may not exceed .Dv NAME_MAX minus six characters for the prefix .Dq memfd: , which will be prepended. The .Fa name argument is intended solely for debugging purposes and will never be used by the kernel to identify a memfd. Names are therefore not required to be unique. .Pp The following .Fa flags may be specified to .Fn memfd_create : .Bl -tag -width MFD_ALLOW_SEALING .It Dv MFD_CLOEXEC Set .Dv FD_CLOEXEC on the resulting file descriptor. .It Dv MFD_ALLOW_SEALING Allow adding seals to the resulting file descriptor using the .Dv F_ADD_SEALS .Xr fcntl 2 command. .It Dv MFD_HUGETLB This flag is currently unsupported. .El .Sh RETURN VALUES If successful, .Fn memfd_create and .Fn shm_open both return a non-negative integer, and .Fn shm_rename and .Fn shm_unlink return zero. All functions return -1 on failure, and set .Va errno to indicate the error. .Sh COMPATIBILITY The .Fa path , .Fa path_from , and .Fa path_to arguments do not necessarily represent a pathname (although they do in most other implementations). Two processes opening the same .Fa path are guaranteed to access the same shared memory object if and only if .Fa path begins with a slash .Pq Ql \&/ character. .Pp Only the .Dv O_RDONLY , .Dv O_RDWR , .Dv O_CREAT , .Dv O_EXCL , and .Dv O_TRUNC flags may be used in portable programs. .Pp POSIX specifications state that the result of using .Xr open 2 , .Xr read 2 , or .Xr write 2 on a shared memory object, or on the descriptor returned by .Fn shm_open , is undefined. However, the .Fx kernel implementation explicitly includes support for .Xr read 2 and .Xr write 2 . .Pp .Fx also supports zero-copy transmission of data from shared memory objects with .Xr sendfile 2 . .Pp Neither shared memory objects nor their contents persist across reboots. .Pp Writes do not extend shared memory objects, so .Xr ftruncate 2 must be called before any data can be written. See .Sx EXAMPLES . .Sh EXAMPLES This example fails without the call to .Xr ftruncate 2 : .Bd -literal -compact uint8_t buffer[getpagesize()]; ssize_t len; int fd; fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600); if (fd < 0) err(EX_OSERR, "%s: shm_open", __func__); if (ftruncate(fd, getpagesize()) < 0) err(EX_IOERR, "%s: ftruncate", __func__); len = pwrite(fd, buffer, getpagesize(), 0); if (len < 0) err(EX_IOERR, "%s: pwrite", __func__); if (len != getpagesize()) errx(EX_IOERR, "%s: pwrite length mismatch", __func__); .Ed .Sh ERRORS .Fn memfd_create fails with these error codes for these conditions: .Bl -tag -width Er .It Bq Er EBADF The .Fa name argument was NULL. .It Bq Er EINVAL The .Fa name argument was too long. .Pp An invalid or unsupported flag was included in .Fa flags . .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 ENOSYS In .Fa memfd_create , .Dv MFD_HUGETLB was specified in .Fa flags , and this system does not support forced hugetlb mappings. .El .Pp .Fn shm_open fails with these error codes for these conditions: .Bl -tag -width Er .It Bq Er EINVAL A flag other than .Dv O_RDONLY , .Dv O_RDWR , .Dv O_CREAT , .Dv O_EXCL , or .Dv O_TRUNC was included in .Fa flags . .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 EINVAL .Dv O_RDONLY was specified while creating an anonymous shared memory object via .Dv SHM_ANON . .It Bq Er EFAULT The .Fa path argument points outside the process' allocated address space. .It Bq Er ENAMETOOLONG The entire pathname exceeds 1023 characters. .It Bq Er EINVAL The .Fa path does not begin with a slash .Pq Ql \&/ character. .It Bq Er ENOENT .Dv O_CREAT -is specified and the named shared memory object does not exist. +is not specified and the named shared memory object does not exist. .It Bq Er EEXIST .Dv O_CREAT and .Dv O_EXCL are specified and the named shared memory object does exist. .It Bq Er EACCES The required permissions (for reading or reading and writing) are denied. .El .Pp The following errors are defined for .Fn shm_rename : .Bl -tag -width Er .It Bq Er EFAULT The .Fa path_from or .Fa path_to argument points outside the process' allocated address space. .It Bq Er ENAMETOOLONG The entire pathname exceeds 1023 characters. .It Bq Er ENOENT The shared memory object at .Fa path_from does not exist. .It Bq Er EACCES The required permissions are denied. .It Bq Er EEXIST An shm exists at .Fa path_to , and the .Dv SHM_RENAME_NOREPLACE flag was provided. .El .Pp .Fn shm_unlink fails with these error codes for these conditions: .Bl -tag -width Er .It Bq Er EFAULT The .Fa path argument points outside the process' allocated address space. .It Bq Er ENAMETOOLONG The entire pathname exceeds 1023 characters. .It Bq Er ENOENT The named shared memory object does not exist. .It Bq Er EACCES The required permissions are denied. .Fn shm_unlink requires write permission to the shared memory object. .El .Sh SEE ALSO .Xr posixshmcontrol 1 , .Xr close 2 , .Xr fstat 2 , .Xr ftruncate 2 , .Xr mmap 2 , .Xr munmap 2 , .Xr sendfile 2 .Sh STANDARDS The .Fn memfd_create function is expected to be compatible with the Linux system call of the same name. .Pp The .Fn shm_open and .Fn shm_unlink functions are believed to conform to .St -p1003.1b-93 . .Sh HISTORY The .Fn memfd_create function appeared in .Fx 13.0 . .Pp The .Fn shm_open and .Fn shm_unlink functions first appeared in .Fx 4.3 . The functions were reimplemented as system calls using shared memory objects directly rather than files in .Fx 8.0 . .Pp .Fn shm_rename first appeared in .Fx 13.0 as a .Fx extension. .Sh AUTHORS .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org (C library support and this manual page) .Pp .An Matthew Dillon Aq Mt dillon@FreeBSD.org .Pq Dv MAP_NOSYNC .Pp .An Matthew Bryan Aq Mt matthew.bryan@isilon.com .Pq Dv shm_rename implementation