docs: Added All NetBSD Manuals

1 files changed, 730 insertions, 0 deletions

diff --git a/static/netbsd/man2/fcntl.2 b/static/netbsd/man2/fcntl.2
new file mode 100644
index 00000000..c7918f6f
--- /dev/null
+++ b/static/netbsd/man2/fcntl.2
@@ -0,0 +1,730 @@
+.\"	$NetBSD: fcntl.2,v 1.51 2025/07/17 17:16:07 kre Exp $
+.\"
+.\" Copyright (c) 1983, 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.
+.\"
+.\"     @(#)fcntl.2	8.2 (Berkeley) 1/12/94
+.\"
+.Dd July 8, 2025
+.Dt FCNTL 2
+.Os
+.Sh NAME
+.Nm fcntl
+.Nd file descriptor control
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In fcntl.h
+.Ft int
+.Fn fcntl "int fd" "int cmd" "..."
+.Sh DESCRIPTION
+.Fn fcntl
+provides for control over descriptors.
+The argument
+.Fa fd
+is a descriptor to be operated on by
+.Fa cmd
+as described below.
+The third parameter is called
+.Fa arg
+and is technically a pointer to void, but it is
+interpreted as an int by some commands and ignored by others.
+.Pp
+Commands are:
+.Bl -tag -width F_DUPFD_CLOEXEC
+.It Dv F_DUPFD
+Return a new descriptor as follows:
+.Pp
+.Bl -bullet -compact -offset 4n
+.It
+Lowest numbered available descriptor greater than or equal to
+.Fa arg ,
+which is interpreted as an int.
+.It
+Same object references as the original descriptor.
+.It
+New descriptor shares the same file offset if the object
+was a file.
+.It
+Same access mode (read, write or read/write).
+.It
+Same file status flags (i.e., both file descriptors
+share the same file status flags).
+.It
+The close-on-exec flag associated with the new file descriptor
+is cleared to allow the file descriptor to remain open across
+.Xr execve 2
+system calls.
+.It
+The close-on-fork flag
+.Dv FD_CLOFORK
+associated with the new file descriptor is cleared,
+so the file descriptor will remain open across
+.Xr fork 2
+system calls.
+.El
+.It Dv F_DUPFD_CLOEXEC
+Same as
+.Dv F_DUPFD ,
+but sets the close-on-exec property on the file descriptor created.
+.It Dv F_DUPFD_CLOFORK
+Same as
+.Dv F_DUPFD ,
+but sets the close-on-fork property on the file descriptor created.
+.It Dv F_DUPFD_CLOBOTH
+Same as
+.Dv F_DUPFD ,
+but sets both the close-on-exec and close-on-fork properties on the file
+descriptor created.
+.It Dv F_GETFD
+Get the flags associated with the file descriptor
+.Fa fd
+.Fa ( arg
+is ignored).
+If the returned value ANDed with
+.Dv FD_CLOEXEC
+is 0,
+the file will remain open across
+.Fn exec ,
+otherwise the file will be closed upon execution of
+.Fn exec .
+If the returned value ANDed with
+.Dv FD_CLOFORK
+is not 0,
+the file will be closed upon execution of the
+.Fn fork
+family of system calls.
+.It Dv F_SETFD
+Set flags associated with
+.Fa fd .
+The available flags, passed as
+.Fa arg
+(treated as an integer), are
+.Dv FD_CLOEXEC
+and
+.Dv FD_CLOFORK .
+.It Dv F_GETFL
+Get descriptor status flags, as described below
+.Fa ( arg
+is ignored).
+.It Dv F_SETFL
+Set descriptor status flags to
+.Fa arg ,
+which is interpreted as an int.
+.It Dv F_GETOWN
+Get the process ID or process group
+currently receiving
+.Dv SIGIO
+and
+.Dv SIGURG
+signals; process groups are returned
+as negative values
+.Fa ( arg
+is ignored).
+.It Dv F_SETOWN
+Set the process or process group
+to receive
+.Dv SIGIO
+and
+.Dv SIGURG
+signals;
+process groups are specified by supplying
+.Fa arg
+as negative, otherwise
+.Fa arg
+is interpreted as a process ID.
+The argument
+.Fa arg
+is interpreted as an int.
+.It Dv F_CLOSEM
+Close all file descriptors greater than or equal to
+.Fa fd ,
+.Fa ( arg
+is ignored).
+.It Dv F_MAXFD
+Return the maximum file descriptor number currently open by the process.
+.Fa ( arg
+is ignored).
+.It Dv F_GETNOSIGPIPE
+Return 1 if the
+.Dv O_NOSIGPIPE
+flag is set in the file descriptor, otherwise 0
+.Fa ( arg
+is ignored).
+.It Dv F_SETNOSIGPIPE
+If
+.Fa arg
+is 0, clear the
+.Dv O_NOSIGPIPE
+status in the file descriptor, otherwise set it.
+.It Dv F_GETPATH
+Place a pathname corresponding to
+.Fa fd
+in the buffer pointed to by
+.Fa arg .
+.Fa arg
+should be pointing to a buffer of at least
+.Dv MAXPATHLEN
+bytes.
+.It Dv F_ADD_SEALS
+Add seals specified in
+.Fa arg
+to
+.Fa fd
+to restrict possible operations on
+.Fa fd
+as described below.
+Like flags, multiple seals can be specified at once.
+Additionally, specifying seals that are already associated with
+.Fa fd
+is a no-op.
+.It Dv F_GET_SEALS
+Get the seals currently associated with
+.Fa fd
+as described below
+.Fa ( arg
+is ignored).
+.El
+.Pp
+The set of valid flags for the
+.Dv F_GETFL
+and
+.Dv F_SETFL
+flags are as follows:
+.Dv O_APPEND ,
+.Dv O_ASYNC ,
+.Dv O_SYNC ,
+.Dv O_NONBLOCK ,
+.Dv O_DSYNC ,
+.Dv O_RSYNC ,
+.Dv O_ALT_IO ,
+.Dv O_DIRECT ,
+.Dv O_NOSIGPIPE .
+These flags are described in
+.Xr open 2 .
+.Pp
+Several commands are available for doing advisory file locking;
+they all operate on the following structure:
+.Bd -literal
+struct flock {
+	off_t	l_start;	/* starting offset */
+	off_t	l_len;		/* len = 0 means until end of file */
+	pid_t	l_pid;		/* lock owner */
+	short	l_type;		/* lock type: read/write, etc. */
+	short	l_whence;	/* type of l_start */
+};
+.Ed
+.Pp
+The commands available for advisory record locking are as follows:
+.Bl -tag -width F_SETLKWX
+.It Dv F_GETLK
+Get the first lock that blocks the lock description pointed to by the
+third argument,
+.Fa arg ,
+taken as a pointer to a
+.Fa "struct flock"
+(see above).
+The information retrieved overwrites the information passed to
+.Nm
+in the
+.Fa flock
+structure.
+If no lock is found that would prevent this lock from being created,
+the structure is left unchanged by this function call except for the
+lock type
+.Fa l_type ,
+which is set to
+.Dv F_UNLCK .
+.It Dv F_SETLK
+Set or clear a file segment lock according to the lock description
+pointed to by the third argument,
+.Fa arg ,
+taken as a pointer to a
+.Fa "struct flock"
+(see above).
+As specified by the value of
+.Fa l_type ,
+.Dv F_SETLK
+is used to establish shared (or read) locks
+.Pq Dv F_RDLCK
+or exclusive (or write) locks,
+.Pq Dv F_WRLCK ,
+as well as remove either type of lock
+.Pq Dv F_UNLCK .
+If a shared or exclusive lock cannot be set,
+.Nm
+returns immediately with
+.Er EAGAIN .
+.It Dv F_SETLKW
+This command is the same as
+.Dv F_SETLK
+except that if a shared or exclusive lock is blocked by other locks,
+the process waits until the request can be satisfied.
+If a signal that is to be caught is received while
+.Nm
+is waiting for a region, the
+.Nm
+will be interrupted if the signal handler has not specified the
+.Dv SA_RESTART
+(see
+.Xr sigaction 2 ) .
+.El
+.Pp
+When a shared lock has been set on a segment of a file,
+other processes can set shared locks on that segment
+or a portion of it.
+A shared lock prevents any other process from setting an exclusive
+lock on any portion of the protected area.
+A request for a shared lock fails if the file descriptor was not
+opened with read access.
+.Pp
+An exclusive lock prevents any other process from setting a shared lock or
+an exclusive lock on any portion of the protected area.
+A request for an exclusive lock fails if the file was not
+opened with write access.
+.Pp
+The value of
+.Fa l_whence
+is
+.Dv SEEK_SET ,
+.Dv SEEK_CUR ,
+or
+.Dv SEEK_END
+to indicate that the relative offset,
+.Fa l_start
+bytes, will be measured from the start of the file,
+current position, or end of the file, respectively.
+The value of
+.Fa l_len
+is the number of consecutive bytes to be locked.
+If
+.Fa l_len
+is negative, the result is undefined.
+The
+.Fa l_pid
+field is only used with
+.Dv F_GETLK
+to return the process ID of the process holding a blocking lock.
+After a successful
+.Dv F_GETLK
+request, the value of
+.Fa l_whence
+is
+.Dv SEEK_SET .
+.Pp
+Locks may start and extend beyond the current end of a file,
+but may not start or extend before the beginning of the file.
+A lock is set to extend to the largest possible value of the
+file offset for that file if
+.Fa l_len
+is set to zero.
+If
+.Fa l_whence
+and
+.Fa l_start
+point to the beginning of the file, and
+.Fa l_len
+is zero, the entire file is locked.
+If an application wishes only to do entire file locking, the
+.Xr flock 2
+system call is much more efficient.
+.Pp
+There is at most one type of lock set for each byte in the file.
+Before a successful return from an
+.Dv F_SETLK
+or an
+.Dv F_SETLKW
+request when the calling process has previously existing locks
+on bytes in the region specified by the request,
+the previous lock type for each byte in the specified
+region is replaced by the new lock type.
+As specified above under the descriptions
+of shared locks and exclusive locks, an
+.Dv F_SETLK
+or an
+.Dv F_SETLKW
+request fails or blocks respectively when another process has existing
+locks on bytes in the specified region and the type of any of those
+locks conflicts with the type specified in the request.
+.Pp
+Possible seals are:
+.Bl -tag -width F_SEAL_FUTURE_WRITE
+.It Dv F_SEAL_SEAL
+Prevent any further seals from being added to
+.Fa fd .
+.It Dv F_SEAL_SHRINK
+Prevent the size of
+.Fa fd
+from decreasing.
+.It Dv F_SEAL_GROW
+Prevent the size of
+.Fa fd
+from increasing.
+.It Dv F_SEAL_WRITE
+Prevent any write operations to
+.Fa fd .
+.Dv F_SEAL_WRITE
+cannot be applied if
+.Fa fd
+has any memory mappings.
+.It Dv F_SEAL_FUTURE_WRITE
+Like
+.Dv F_SEAL_WRITE
+but allow any current memory mappings of
+.Fa fd
+to remain open, including those with
+.Dv PROT_WRITE .
+.El
+.Sh NOTES
+For
+.Dv F_GETPATH :
+.Bl -bullet -compact
+.It
+For vnodes, functionality is implemented using the reverse
+.Xr namei 9
+cache.
+The implications of this are
+.Bl -bullet -compact
+.It
+For hard links where the file descriptor can resolve to multiple pathnames,
+the first entry found in the cache is returned.
+.It
+.Dv F_GETPATH
+may fail if the corresponding entry has been evicted from the LRU
+.Xr namei 9
+cache and return
+.Er ENOENT .
+.El
+.It
+For a file descriptor created by
+.Xr memfd_create 2 ,
+the name provided at
+.Fa fd
+creation, with the prefix
+.Dq memfd:
+is used.
+.It
+Other types of file descriptors are not handled, as well as symbolic
+links since there is currently no way to obtain a file descriptor
+pointing to a symbolic link.
+.El
+.Sh RETURN VALUES
+Upon successful completion, the value returned depends on
+.Fa cmd
+as follows:
+.Bl -tag -width F_GET_SEALS -offset indent
+.It Dv F_DUPFD
+A new file descriptor.
+.It Dv F_GETFD
+Value of flag (one or both of the bits
+.Dv FD_CLOEXEC
+and
+.Dv FD_CLOFORK ) .
+.It Dv F_GETFL
+Value of flags.
+.It Dv F_GETOWN
+Value of file descriptor owner.
+.It Dv F_MAXFD
+Value of the highest file descriptor open by the process.
+.It Dv F_GET_SEALS
+Value of the seals currently associated with
+.Fa fd .
+.It other
+Value other than \-1.
+.El
+.Pp
+Otherwise, a value of \-1 is returned and
+.Va errno
+is set to indicate the error.
+.Sh COMPATIBILITY
+This interface follows the completely stupid semantics of
+.At V
+and
+.St -p1003.1-88
+that require that all locks associated with a file for a given process are
+removed when \fIany\fP file descriptor for that file is closed by that process.
+This semantic means that applications must be aware of any files that
+a subroutine library may access.
+For example if an application for updating the password file locks the
+password file database while making the update, and then calls
+.Xr getpwnam 3
+to retrieve a record,
+the lock will be lost because
+.Xr getpwnam 3
+opens, reads, and closes the password database.
+The database close will release all locks that the process has
+associated with the database, even if the library routine never
+requested a lock on the database.
+.Pp
+Another minor semantic problem with this interface is that
+locks are not inherited by a child process created using the
+.Xr fork 2
+function.
+The
+.Xr flock 2
+interface has much more rational last close semantics and
+allows locks to be inherited by child processes.
+Calling
+.Xr flock 2
+is recommended for applications that want to ensure the integrity
+of their locks when using library routines or wish to pass locks
+to their children.
+Note that
+.Xr flock 2
+and
+.Nm
+locks may be safely used concurrently.
+.Pp
+All locks associated with a file for a given process are
+removed when the process terminates.
+.Pp
+A potential for deadlock occurs if a process controlling a locked region
+is put to sleep by attempting to lock the locked region of another process.
+This implementation detects that sleeping until a locked region is unlocked
+would cause a deadlock and fails with an
+.Er EDEADLK
+error.
+.Sh ERRORS
+.Fn fcntl
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EACCES
+The argument
+.Fa cmd
+is
+.Dv F_GETPATH
+and read or search permission was denied for a component of the pathname.
+.It Bq Er EAGAIN
+The argument
+.Fa arg
+is
+.Dv F_SETLK ,
+the type of lock
+.Pq Fa l_type
+is a shared lock
+.Pq Dv F_RDLCK
+or exclusive lock
+.Pq Dv F_WRLCK ,
+and the segment of a file to be locked is already
+exclusive-locked by another process;
+or the type is an exclusive lock and some portion of the
+segment of a file to be locked is already shared-locked or
+exclusive-locked by another process.
+.It Bq Er EBADF
+.Fa fildes
+is not a valid open file descriptor.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_SETLK
+or
+.Dv F_SETLKW ,
+the type of lock
+.Pq Fa l_type
+is a shared lock
+.Pq Dv F_RDLCK ,
+and
+.Fa fildes
+is not a valid file descriptor open for reading.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_SETLK
+or
+.Dv F_SETLKW ,
+the type of lock
+.Pq Fa l_type
+is an exclusive lock
+.Pq Dv F_WRLCK ,
+and
+.Fa fildes
+is not a valid file descriptor open for writing.
+.It Bq Er EBUSY
+The argument
+.Fa cmd
+is
+.Dv F_ADD_SEALS ,
+.Fa arg
+contains
+.Dv F_SEAL_WRITE
+and
+.Fa fd
+is currently mapped by
+.Xr mmap 2 .
+.It Bq Er EDEADLK
+The argument
+.Fa cmd
+is
+.Dv F_SETLKW ,
+and a deadlock condition was detected.
+.It Bq Er EINTR
+The argument
+.Fa cmd
+is
+.Dv F_SETLKW ,
+and the function was interrupted by a signal.
+.It Bq Er EINVAL
+The argument
+.Fa cmd
+is invalid.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_DUPFD
+and
+.Fa arg
+is negative or greater than the maximum allowable number
+(see
+.Xr getdtablesize 3 ) .
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_GETLK ,
+.Dv F_SETLK ,
+or
+.Dv F_SETLKW
+and the data to which
+.Fa arg
+points is not valid, or
+.Fa fildes
+refers to a file that does not support locking.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_ADD_SEALS
+or
+.Dv F_GET_SEALS
+and
+.Fa fd
+does not support seals.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_ADD_SEALS
+and
+.Fa arg
+contains set bits for unsupported seals.
+.It Bq Er EMFILE
+The argument
+.Fa cmd
+is
+.Dv F_DUPFD
+and the maximum number of file descriptors permitted for the
+process are already in use,
+or no file descriptors greater than or equal to
+.Fa arg
+are available.
+.It Bq Er ENFILE
+.Fa cmd
+is
+.Dv F_DUPFD
+and system-wide the maximum allowed number of file descriptors are
+currently open.
+.It Bq Er ENOENT
+The argument
+.Fa cmd
+is
+.Dv F_GETPATH
+and a component of the pathname no longer exists.
+.It Bq Er ENOLCK
+The argument
+.Fa cmd
+is
+.Dv F_SETLK
+or
+.Dv F_SETLKW ,
+and satisfying the lock or unlock request would result in the
+number of locked regions in the system exceeding a system-imposed limit.
+.It Bq Er ENOMEM
+The argument
+.Fa cmd
+is
+.Dv F_GETPATH
+and insufficient memory is available.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_GETLK ,
+.Dv F_SETLK ,
+or
+.Dv F_SETLKW ,
+and the file lock limit for the current unprivileged user
+has been reached.
+It can be modified using the
+.Li kern.maxfiles
+.Xr sysctl 7 .
+.It Bq Er EPERM
+The argument
+.Fa cmd
+is
+.Dv F_ADD_SEALS
+and
+.Fa fd
+already has
+.Dv F_SEAL_SEAL .
+.It Bq Er ERANGE
+The argument
+.Fa cmd
+is
+.Dv F_GETPATH
+and the resulting path would be greater than
+.Dv MAXPATHLEN .
+.It Bq Er ESRCH
+.Fa cmd
+is
+.Dv F_SETOWN
+and
+the process ID given as argument is not in use.
+.El
+.Sh SEE ALSO
+.Xr close 2 ,
+.Xr execve 2 ,
+.Xr flock 2 ,
+.Xr open 2 ,
+.Xr sigaction 2 ,
+.Xr getdtablesize 3
+.Sh STANDARDS
+The
+.Fn fcntl
+function conforms to
+.St -p1003.1-90 .
+.Sh HISTORY
+The
+.Fn fcntl
+function call appeared in
+.Bx 4.2 .
+The
+.Dv F_DUPFD_CLOBOTH
+operation first appeared in
+.Nx 11.0 .