Index: stable/12/lib/libc/stdio/fflush.3
===================================================================
--- stable/12/lib/libc/stdio/fflush.3	(revision 362681)
+++ stable/12/lib/libc/stdio/fflush.3	(revision 362682)
@@ -1,127 +1,136 @@
 .\" Copyright (c) 1990, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
 .\" This code is derived from software contributed to Berkeley by
 .\" Chris Torek and the American National Standards Committee X3,
 .\" on Information Processing Systems.
 .\"
 .\" 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.
 .\"
 .\"     @(#)fflush.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd January 23, 2020
+.Dd May 1, 2020
 .Dt FFLUSH 3
 .Os
 .Sh NAME
 .Nm fflush ,
 .Nm fflush_unlocked ,
 .Nm fpurge
 .Nd flush a stream
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In stdio.h
 .Ft int
 .Fn fflush "FILE *stream"
 .Ft int
 .Fn fflush_unlocked "FILE *stream"
 .Ft int
 .Fn fpurge "FILE *stream"
 .Sh DESCRIPTION
 The function
 .Fn fflush
 forces a write of all buffered data for the given output or update
 .Fa stream
 via the stream's underlying write function.
 The open status of the stream is unaffected.
 .Pp
 If the
 .Fa stream
 argument is
 .Dv NULL ,
 .Fn fflush
 flushes
 .Em all
 open output streams.
 .Pp
 The
 .Fn fflush_unlocked
 function is equivalent to
 .Fn fflush ,
 except that the caller is responsible for locking the stream with
 .Xr flockfile 3
 before calling it.
 This function may be used to avoid the overhead of locking the stream and to
 prevent races when multiple threads are operating on the same stream.
 .Pp
 The function
 .Fn fpurge
 erases any input or output buffered in the given
 .Fa stream .
 For output streams this discards any unwritten output.
 For input streams this discards any input read from the underlying object
 but not yet obtained via
 .Xr getc 3 ;
 this includes any text pushed back via
 .Xr ungetc 3 .
 .Sh RETURN VALUES
 Upon successful completion 0 is returned.
 Otherwise,
 .Dv EOF
 is returned and the global variable
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er EBADF
 The
 .Fa stream
 argument
 is not an open stream.
 .El
 .Pp
 The function
 .Fn fflush
 may also fail and set
 .Va errno
 for any of the errors specified for the routine
 .Xr write 2 ,
 except that in case of
 .Fa stream
 being a read-only descriptor,
 .Fn fflush
 returns 0.
 .Sh SEE ALSO
 .Xr write 2 ,
 .Xr fclose 3 ,
 .Xr fopen 3 ,
 .Xr setbuf 3
 .Sh STANDARDS
 The
 .Fn fflush
 function
 conforms to
 .St -isoC .
+.Sh HISTORY
+The
+.Fn fflush
+function first appeared in
+.At v4 .
+The
+.Fn fpurge
+function first appeared in
+.Bx 4.4 .
Index: stable/12/lib/libc/stdio/fopen.3
===================================================================
--- stable/12/lib/libc/stdio/fopen.3	(revision 362681)
+++ stable/12/lib/libc/stdio/fopen.3	(revision 362682)
@@ -1,358 +1,363 @@
 .\" Copyright (c) 1990, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
 .\" This code is derived from software contributed to Berkeley by
 .\" Chris Torek and the American National Standards Committee X3,
 .\" on Information Processing Systems.
 .\"
 .\" 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.
 .\"
 .\"     @(#)fopen.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd January 30, 2013
+.Dd May 1, 2020
 .Dt FOPEN 3
 .Os
 .Sh NAME
 .Nm fopen ,
 .Nm fdopen ,
 .Nm freopen ,
 .Nm fmemopen
 .Nd stream open functions
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In stdio.h
 .Ft FILE *
 .Fn fopen "const char * restrict path" "const char * restrict mode"
 .Ft FILE *
 .Fn fdopen "int fildes" "const char *mode"
 .Ft FILE *
 .Fn freopen "const char *path" "const char *mode" "FILE *stream"
 .Ft FILE *
 .Fn fmemopen "void *restrict *buf" "size_t size" "const char * restrict mode"
 .Sh DESCRIPTION
 The
 .Fn fopen
 function
 opens the file whose name is the string pointed to by
 .Fa path
 and associates a stream with it.
 .Pp
 The argument
 .Fa mode
 points to a string beginning with one of the following letters:
 .Bl -tag -width indent
 .It Dq Li r
 Open for reading.
 The stream is positioned at the beginning of the file.
 Fail if the file does not exist.
 .It Dq Li w
 Open for writing.
 The stream is positioned at the beginning of the file.
 Truncate the file to zero length if it exists or create the file if it does not exist.
 .It Dq Li a
 Open for writing.
 The stream is positioned at the end of the file.
 Subsequent writes to the file will always end up at the then current
 end of file, irrespective of any intervening
 .Xr fseek 3
 or similar.
 Create the file if it does not exist.
 .El
 .Pp
 An optional
 .Dq Li +
 following
 .Dq Li r ,
 .Dq Li w ,
 or
 .Dq Li a
 opens the file for both reading and writing.
 An optional
 .Dq Li x
 following
 .Dq Li w
 or
 .Dq Li w+
 causes the
 .Fn fopen
 call to fail if the file already exists.
 An optional
 .Dq Li e
 following the above
 causes the
 .Fn fopen
 call to set the
 .Dv FD_CLOEXEC
 flag on the underlying file descriptor.
 .Pp
 The
 .Fa mode
 string can also include the letter
 .Dq Li b
 after either the
 .Dq Li +
 or the first letter.
 This is strictly for compatibility with
 .St -isoC
 and has effect only for
 .Fn fmemopen ;
 otherwise
 .Dq Li b
 is ignored.
 .Pp
 Any created files will have mode
 .Do Dv S_IRUSR
 \&|
 .Dv S_IWUSR
 \&|
 .Dv S_IRGRP
 \&|
 .Dv S_IWGRP
 \&|
 .Dv S_IROTH
 \&|
 .Dv S_IWOTH Dc
 .Pq Li 0666 ,
 as modified by the process'
 umask value (see
 .Xr umask 2 ) .
 .Pp
 Reads and writes may be intermixed on read/write streams in any order,
 and do not require an intermediate seek as in previous versions of
 .Em stdio .
 This is not portable to other systems, however;
 .Tn ANSI C
 requires that
 a file positioning function intervene between output and input, unless
 an input operation encounters end-of-file.
 .Pp
 The
 .Fn fdopen
 function associates a stream with the existing file descriptor,
 .Fa fildes .
 The mode
 of the stream must be compatible with the mode of the file descriptor.
 The
 .Dq Li x
 mode option is ignored.
 If the
 .Dq Li e
 mode option is present, the
 .Dv FD_CLOEXEC
 flag is set, otherwise it remains unchanged.
 When the stream is closed via
 .Xr fclose 3 ,
 .Fa fildes
 is closed also.
 .Pp
 The
 .Fn freopen
 function
 opens the file whose name is the string pointed to by
 .Fa path
 and associates the stream pointed to by
 .Fa stream
 with it.
 The original stream (if it exists) is closed.
 The
 .Fa mode
 argument is used just as in the
 .Fn fopen
 function.
 .Pp
 If the
 .Fa path
 argument is
 .Dv NULL ,
 .Fn freopen
 attempts to re-open the file associated with
 .Fa stream
 with a new mode.
 The new mode must be compatible with the mode that the stream was originally
 opened with:
 Streams open for reading can only be re-opened for reading,
 streams open for writing can only be re-opened for writing,
 and streams open for reading and writing can be re-opened in any mode.
 The
 .Dq Li x
 mode option is not meaningful in this context.
 .Pp
 The primary use of the
 .Fn freopen
 function
 is to change the file associated with a
 standard text stream
 .Dv ( stderr , stdin ,
 or
 .Dv stdout ) .
 .Pp
 The
 .Fn fmemopen
 function
 associates the buffer given by the
 .Fa buf
 and
 .Fa size
 arguments with a stream.
 The
 .Fa buf
 argument is either a null pointer or point to a buffer that
 is at least
 .Fa size
 bytes long.
 If a null pointer is specified as the
 .Fa buf
 argument,
 .Fn fmemopen
 allocates
 .Fa size
 bytes of memory.
 This buffer is automatically freed when the stream is closed.
 Buffers can be opened in text-mode (default) or binary-mode
 (if
 .Dq Li b
 is present in the second or third position of the
 .Fa mode
 argument).
 Buffers opened in text-mode make sure that writes are terminated with a
 .Dv NULL
 byte, if the last write hasn't filled up the whole buffer.
 Buffers opened in binary-mode never append a
 .Dv NULL
 byte.
 .Sh RETURN VALUES
 Upon successful completion
 .Fn fopen ,
 .Fn fdopen
 and
 .Fn freopen
 return a
 .Tn FILE
 pointer.
 Otherwise,
 .Dv NULL
 is returned and the global variable
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er EINVAL
 The
 .Fa mode
 argument
 to
 .Fn fopen ,
 .Fn fdopen ,
 .Fn freopen ,
 or
 .Fn fmemopen
 was invalid.
 .El
 .Pp
 The
 .Fn fopen ,
 .Fn fdopen ,
 .Fn freopen
 and
 .Fn fmemopen
 functions
 may also fail and set
 .Va errno
 for any of the errors specified for the routine
 .Xr malloc 3 .
 .Pp
 The
 .Fn fopen
 function
 may also fail and set
 .Va errno
 for any of the errors specified for the routine
 .Xr open 2 .
 .Pp
 The
 .Fn fdopen
 function
 may also fail and set
 .Va errno
 for any of the errors specified for the routine
 .Xr fcntl 2 .
 .Pp
 The
 .Fn freopen
 function
 may also fail and set
 .Va errno
 for any of the errors specified for the routines
 .Xr open 2 ,
 .Xr fclose 3
 and
 .Xr fflush 3 .
 .Pp
 The
 .Fn fmemopen
 function
 may also fail and set
 .Va errno
 if the
 .Fa size
 argument is 0.
 .Sh SEE ALSO
 .Xr open 2 ,
 .Xr fclose 3 ,
 .Xr fileno 3 ,
 .Xr fseek 3 ,
 .Xr funopen 3
 .Sh STANDARDS
 The
 .Fn fopen
 and
 .Fn freopen
 functions
 conform to
 .St -isoC ,
 with the exception of the
 .Dq Li x
 mode option which conforms to
 .St -isoC-2011 .
 The
 .Fn fdopen
 function
 conforms to
 .St -p1003.1-88 .
 The
 .Dq Li e
 mode option does not conform to any standard
 but is also supported by glibc.
 The
 .Fn fmemopen
 function
 conforms to
 .St -p1003.1-2008 .
 The
 .Dq Li b
 mode does not conform to any standard
 but is also supported by glibc.
+.Sh HISTORY
+An
+.Fn fopen
+function appeared in
+.At v1 .
Index: stable/12/lib/libc/stdio/setbuf.3
===================================================================
--- stable/12/lib/libc/stdio/setbuf.3	(revision 362681)
+++ stable/12/lib/libc/stdio/setbuf.3	(revision 362682)
@@ -1,200 +1,217 @@
 .\" Copyright (c) 1980, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
 .\" This code is derived from software contributed to Berkeley by
 .\" the American National Standards Committee X3, on Information
 .\" Processing Systems.
 .\"
 .\" 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.
 .\"
 .\"     @(#)setbuf.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd February 18, 2013
+.Dd May 1, 2020
 .Dt SETBUF 3
 .Os
 .Sh NAME
 .Nm setbuf ,
 .Nm setbuffer ,
 .Nm setlinebuf ,
 .Nm setvbuf
 .Nd stream buffering operations
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In stdio.h
 .Ft void
 .Fn setbuf "FILE * restrict stream" "char * restrict buf"
 .Ft void
 .Fn setbuffer "FILE *stream" "char *buf" "int size"
 .Ft int
 .Fn setlinebuf "FILE *stream"
 .Ft int
 .Fn setvbuf "FILE * restrict stream" "char * restrict buf" "int mode" "size_t size"
 .Sh DESCRIPTION
 The three types of buffering available are unbuffered, block buffered,
 and line buffered.
 When an output stream is unbuffered, information appears on the
 destination file or terminal as soon as written;
 when it is block buffered many characters are saved up and written as a block;
 when it is line buffered characters are saved up until a newline is
 output or input is read from any stream attached to a terminal device
 (typically
 .Dv stdin ) .
 The function
 .Xr fflush 3
 may be used to force the block out early.
 (See
 .Xr fclose 3 . )
 .Pp
 Normally all files are block buffered.
 When the first
 .Tn I/O
 operation occurs on a file,
 .Xr malloc 3
 is called,
 and an optimally-sized buffer is obtained.
 If a stream refers to a terminal
 (as
 .Dv stdout
 normally does) it is line buffered.
 The standard error stream
 .Dv stderr
 is always unbuffered.
 Note that these defaults may be altered using the
 .Xr stdbuf 1
 utility.
 .Pp
 The
 .Fn setvbuf
 function
 may be used to alter the buffering behavior of a stream.
 The
 .Fa mode
 argument must be one of the following three macros:
 .Bl -tag -width _IOFBF -offset indent
 .It Dv _IONBF
 unbuffered
 .It Dv _IOLBF
 line buffered
 .It Dv _IOFBF
 fully buffered
 .El
 .Pp
 The
 .Fa size
 argument may be given as zero
 to obtain deferred optimal-size buffer allocation as usual.
 If it is not zero,
 then except for unbuffered files, the
 .Fa buf
 argument should point to a buffer at least
 .Fa size
 bytes long;
 this buffer will be used instead of the current buffer.
 If
 .Fa buf
 is not
 .Dv NULL ,
 it is the caller's responsibility to
 .Xr free 3
 this buffer after closing the stream.
 (If the
 .Fa size
 argument
 is not zero but
 .Fa buf
 is
 .Dv NULL ,
 a buffer of the given size will be allocated immediately,
 and released on close.
 This is an extension to ANSI C;
 portable code should use a size of 0 with any
 .Dv NULL
 buffer.)
 .Pp
 The
 .Fn setvbuf
 function may be used at any time,
 but may have peculiar side effects
 (such as discarding input or flushing output)
 if the stream is ``active''.
 Portable applications should call it only once on any given stream,
 and before any
 .Tn I/O
 is performed.
 .Pp
 The other three calls are, in effect, simply aliases for calls to
 .Fn setvbuf .
 Except for the lack of a return value, the
 .Fn setbuf
 function is exactly equivalent to the call
 .Pp
 .Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);"
 .Pp
 The
 .Fn setbuffer
 function
 is the same, except that the size of the buffer is up to the caller,
 rather than being determined by the default
 .Dv BUFSIZ .
 The
 .Fn setlinebuf
 function
 is exactly equivalent to the call:
 .Pp
 .Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);"
 .Sh RETURN VALUES
 The
 .Fn setvbuf
 function returns 0 on success, or
 .Dv EOF
 if the request cannot be honored
 (note that the stream is still functional in this case).
 .Pp
 The
 .Fn setlinebuf
 function returns what the equivalent
 .Fn setvbuf
 would have returned.
 .Sh SEE ALSO
 .Xr stdbuf 1 ,
 .Xr fclose 3 ,
 .Xr fopen 3 ,
 .Xr fread 3 ,
 .Xr malloc 3 ,
 .Xr printf 3 ,
 .Xr puts 3
 .Sh STANDARDS
 The
 .Fn setbuf
 and
 .Fn setvbuf
 functions
 conform to
 .St -isoC .
+.Sh HISTORY
+The
+.Fn setbuf
+function first appeared in
+.At v7 .
+The
+.Fn setbuffer
+function first appeared in
+.Bx 4.1c .
+The
+.Fn setlinebuf
+function first appeared in
+.Bx 4.2 .
+The
+.Fn setvbuf
+function first appeared in
+.Bx 4.4 .
 .Sh BUGS
 .Fn setbuf
 usually uses a suboptimal buffer size and should be avoided.
Index: stable/12/lib/libc/string/strlcpy.3
===================================================================
--- stable/12/lib/libc/string/strlcpy.3	(revision 362681)
+++ stable/12/lib/libc/string/strlcpy.3	(revision 362682)
@@ -1,200 +1,210 @@
 .\"	$OpenBSD: strlcpy.3,v 1.26 2013/09/30 12:02:35 millert Exp $
 .\"
 .\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
 .\" copyright notice and this permission notice appear in all copies.
 .\"
 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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 February 26, 2016
+.Dd May 1, 2020
 .Dt STRLCPY 3
 .Os
 .Sh NAME
 .Nm strlcpy ,
 .Nm strlcat
 .Nd size-bounded string copying and concatenation
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In string.h
 .Ft size_t
 .Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t dstsize"
 .Ft size_t
 .Fn strlcat "char * restrict dst" "const char * restrict src" "size_t dstsize"
 .Sh DESCRIPTION
 The
 .Fn strlcpy
 and
 .Fn strlcat
 functions copy and concatenate strings with the
 same input parameters and output result as
 .Xr snprintf 3 .
 They are designed to be safer, more consistent, and less error
 prone replacements for the easily misused functions
 .Xr strncpy 3
 and
 .Xr strncat 3 .
 .Pp
 .Fn strlcpy
 and
 .Fn strlcat
 take the full size of the destination buffer and guarantee
 NUL-termination if there is room.
 Note that room for the NUL should be included in
 .Fa dstsize .
 .Pp
 .Fn strlcpy
 copies up to
 .Fa dstsize
 \- 1 characters from the string
 .Fa src
 to
 .Fa dst ,
 NUL-terminating the result if
 .Fa dstsize
 is not 0.
 .Pp
 .Fn strlcat
 appends string
 .Fa src
 to the end of
 .Fa dst .
 It will append at most
 .Fa dstsize
 \- strlen(dst) \- 1 characters.
 It will then NUL-terminate, unless
 .Fa dstsize
 is 0 or the original
 .Fa dst
 string was longer than
 .Fa dstsize
 (in practice this should not happen
 as it means that either
 .Fa dstsize
 is incorrect or that
 .Fa dst
 is not a proper string).
 .Pp
 If the
 .Fa src
 and
 .Fa dst
 strings overlap, the behavior is undefined.
 .Sh RETURN VALUES
 Besides quibbles over the return type
 .Pf ( Va size_t
 versus
 .Va int )
 and signal handler safety
 .Pf ( Xr snprintf 3
 is not entirely safe on some systems), the
 following two are equivalent:
 .Bd -literal -offset indent
 n = strlcpy(dst, src, len);
 n = snprintf(dst, len, "%s", src);
 .Ed
 .Pp
 Like
 .Xr snprintf 3 ,
 the
 .Fn strlcpy
 and
 .Fn strlcat
 functions return the total length of the string they tried to create.
 For
 .Fn strlcpy
 that means the length of
 .Fa src .
 For
 .Fn strlcat
 that means the initial length of
 .Fa dst
 plus
 the length of
 .Fa src .
 .Pp
 If the return value is
 .Cm >=
 .Va dstsize ,
 the output string has been truncated.
 It is the caller's responsibility to handle this.
 .Sh EXAMPLES
 The following code fragment illustrates the simple case:
 .Bd -literal -offset indent
 char *s, *p, buf[BUFSIZ];
 
 \&...
 
 (void)strlcpy(buf, s, sizeof(buf));
 (void)strlcat(buf, p, sizeof(buf));
 .Ed
 .Pp
 To detect truncation, perhaps while building a pathname, something
 like the following might be used:
 .Bd -literal -offset indent
 char *dir, *file, pname[MAXPATHLEN];
 
 \&...
 
 if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
 	goto toolong;
 if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
 	goto toolong;
 .Ed
 .Pp
 Since it is known how many characters were copied the first time, things
 can be sped up a bit by using a copy instead of an append:
 .Bd -literal -offset indent
 char *dir, *file, pname[MAXPATHLEN];
 size_t n;
 
 \&...
 
 n = strlcpy(pname, dir, sizeof(pname));
 if (n >= sizeof(pname))
 	goto toolong;
 if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
 	goto toolong;
 .Ed
 .Pp
 However, one may question the validity of such optimizations, as they
 defeat the whole purpose of
 .Fn strlcpy
 and
 .Fn strlcat .
 As a matter of fact, the first version of this manual page got it wrong.
 .Sh SEE ALSO
 .Xr snprintf 3 ,
 .Xr strncat 3 ,
 .Xr strncpy 3 ,
 .Xr wcslcpy 3
+.Rs
+.%A Todd C. Miller
+.%A Theo de Raadt
+.%T strlcpy and strlcat -- Consistent, Safe, String Copy and Concatenation
+.%I USENIX Association
+.%B Proceedings of the FREENIX Track: 1999 USENIX Annual Technical Conference
+.%D June 6-11, 1999
+.%U http://www.usenix.org/publications/library/proceedings/usenix99/
+.%U full_papers/millert/millert.pdf
+.Re
 .Sh HISTORY
 The
 .Fn strlcpy
 and
 .Fn strlcat
 functions first appeared in
 .Ox 2.4 ,
 and
 .Fx 3.3 .
Index: stable/12/lib/libc/sys/getgid.2
===================================================================
--- stable/12/lib/libc/sys/getgid.2	(revision 362681)
+++ stable/12/lib/libc/sys/getgid.2	(revision 362682)
@@ -1,80 +1,85 @@
 .\" Copyright (c) 1983, 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.
 .\"
 .\"     @(#)getgid.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd December 15, 2015
+.Dd May 1, 2020
 .Dt GETGID 2
 .Os
 .Sh NAME
 .Nm getgid ,
 .Nm getegid
 .Nd get group process identification
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In unistd.h
 .Ft gid_t
 .Fn getgid void
 .Ft gid_t
 .Fn getegid void
 .Sh DESCRIPTION
 The
 .Fn getgid
 system call returns the real group ID of the calling process,
 .Fn getegid
 returns the effective group ID of the calling process.
 .Pp
 The real group ID is specified at login time.
 .Pp
 The real group ID is the group of the user who invoked the program.
 As the effective group ID gives the process additional permissions
 during the execution of
 .Dq Em set-group-ID
 mode processes,
 .Fn getgid
 is used to determine the real-user-id of the calling process.
 .Sh ERRORS
 The
 .Fn getgid
 and
 .Fn getegid
 system calls are always successful, and no return value is reserved to
 indicate an error.
 .Sh SEE ALSO
 .Xr getuid 2 ,
 .Xr issetugid 2 ,
 .Xr setgid 2 ,
 .Xr setregid 2
 .Sh STANDARDS
 The
 .Fn getgid
 and
 .Fn getegid
 system calls are expected to conform to
 .St -p1003.1-90 .
+.Sh HISTORY
+The
+.Fn getgid
+function appeared in
+.At v4 .
Index: stable/12/lib/libc/sys/getitimer.2
===================================================================
--- stable/12/lib/libc/sys/getitimer.2	(revision 362681)
+++ stable/12/lib/libc/sys/getitimer.2	(revision 362682)
@@ -1,180 +1,195 @@
 .\" Copyright (c) 1983, 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.
 .\"
 .\"     @(#)getitimer.2	8.3 (Berkeley) 5/16/95
 .\" $FreeBSD$
 .\"
-.Dd May 16, 1995
+.Dd May 1, 2020 
 .Dt GETITIMER 2
 .Os
 .Sh NAME
 .Nm getitimer ,
 .Nm setitimer
 .Nd get/set value of interval timer
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In sys/time.h
 .Fd "#define ITIMER_REAL      0"
 .Fd "#define ITIMER_VIRTUAL   1"
 .Fd "#define ITIMER_PROF      2"
 .Ft int
 .Fn getitimer "int which" "struct itimerval *value"
 .Ft int
 .Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue"
 .Sh DESCRIPTION
 The system provides each process with three interval timers,
 defined in
 .In sys/time.h .
 The
 .Fn getitimer
 system call returns the current value for the timer specified in
 .Fa which
 in the structure at
 .Fa value .
 The
 .Fn setitimer
 system call sets a timer to the specified
 .Fa value
 (returning the previous value of the timer if
 .Fa ovalue
 is not a null pointer).
 .Pp
 A timer value is defined by the
 .Fa itimerval
 structure:
 .Bd -literal -offset indent
 struct itimerval {
 	struct	timeval it_interval;	/* timer interval */
 	struct	timeval it_value;	/* current value */
 };
 .Ed
 .Pp
 If
 .Fa it_value
 is non-zero, it indicates the time to the next timer expiration.
 If
 .Fa it_interval
 is non-zero, it specifies a value to be used in reloading
 .Fa it_value
 when the timer expires.
 Setting
 .Fa it_value
 to 0 disables a timer, regardless of the value of
 .Fa it_interval .
 Setting
 .Fa it_interval
 to 0 causes a timer to be disabled after its next expiration (assuming
 .Fa it_value
 is non-zero).
 .Pp
 Time values smaller than the resolution of the
 system clock are rounded up to this resolution
 (typically 10 milliseconds).
 .Pp
 The
 .Dv ITIMER_REAL
 timer decrements in real time.
 A
 .Dv SIGALRM
 signal is
 delivered when this timer expires.
 .Pp
 The
 .Dv ITIMER_VIRTUAL
 timer decrements in process virtual time.
 It runs only when the process is executing.
 A
 .Dv SIGVTALRM
 signal
 is delivered when it expires.
 .Pp
 The
 .Dv ITIMER_PROF
 timer decrements both in process virtual time and
 when the system is running on behalf of the process.
 It is designed
 to be used by interpreters in statistically profiling the execution
 of interpreted programs.
 Each time the
 .Dv ITIMER_PROF
 timer expires, the
 .Dv SIGPROF
 signal is
 delivered.
 Because this signal may interrupt in-progress
 system calls, programs using this timer must be prepared to
 restart interrupted system calls.
 .Pp
 The maximum number of seconds allowed for
 .Fa it_interval
 and
 .Fa it_value
 in
 .Fn setitimer
 is 100000000.
 .Sh NOTES
 Three macros for manipulating time values are defined in
 .In sys/time.h .
 The
 .Fn timerclear
 macro
 sets a time value to zero,
 .Fn timerisset
 tests if a time value is non-zero, and
 .Fn timercmp
 compares two time values.
 .Sh RETURN VALUES
 .Rv -std
 .Sh ERRORS
 The
 .Fn getitimer
 and
 .Fn setitimer
 system calls
 will fail if:
 .Bl -tag -width Er
 .It Bq Er EFAULT
 The
 .Fa value
 argument specified a bad address.
 .It Bq Er EINVAL
 The
 .Fa value
 argument specified a time that was too large
 to be handled.
 .El
 .Sh SEE ALSO
 .Xr gettimeofday 2 ,
 .Xr select 2 ,
 .Xr sigaction 2 ,
 .Xr clocks 7
+.Sh STANDARDS
+The
+.Fn getitimer
+and
+.Fn setitimer
+functions conform to
+.St -p1003.1-2001 .
+The later
+.St -p1003.1-2008
+revision however marked both functions as obsolescent,
+recommending the use of
+.Xr timer_gettime 2
+and
+.Xr timer_settime 2
+instead.
 .Sh HISTORY
 The
 .Fn getitimer
 system call appeared in
 .Bx 4.2 .
Index: stable/12/lib/libc/sys/kqueue.2
===================================================================
--- stable/12/lib/libc/sys/kqueue.2	(revision 362681)
+++ stable/12/lib/libc/sys/kqueue.2	(revision 362682)
@@ -1,802 +1,810 @@
 .\" Copyright (c) 2000 Jonathan Lemon
 .\" 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.
 .\"
 .\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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.
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 27, 2020
+.Dd May 1, 2020
 .Dt KQUEUE 2
 .Os
 .Sh NAME
 .Nm kqueue ,
 .Nm kevent
 .Nd kernel event notification mechanism
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In sys/event.h
 .Ft int
 .Fn kqueue "void"
 .Ft int
 .Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout"
 .Fn EV_SET "kev" ident filter flags fflags data udata
 .Sh DESCRIPTION
 The
 .Fn kqueue
 system call
 provides a generic method of notifying the user when an event
 happens or a condition holds, based on the results of small
 pieces of kernel code termed filters.
 A kevent is identified by the (ident, filter) pair; there may only
 be one unique kevent per kqueue.
 .Pp
 The filter is executed upon the initial registration of a kevent
 in order to detect whether a preexisting condition is present, and is also
 executed whenever an event is passed to the filter for evaluation.
 If the filter determines that the condition should be reported,
 then the kevent is placed on the kqueue for the user to retrieve.
 .Pp
 The filter is also run when the user attempts to retrieve the kevent
 from the kqueue.
 If the filter indicates that the condition that triggered
 the event no longer holds, the kevent is removed from the kqueue and
 is not returned.
 .Pp
 Multiple events which trigger the filter do not result in multiple
 kevents being placed on the kqueue; instead, the filter will aggregate
 the events into a single struct kevent.
 Calling
 .Fn close
 on a file descriptor will remove any kevents that reference the descriptor.
 .Pp
 The
 .Fn kqueue
 system call
 creates a new kernel event queue and returns a descriptor.
 The queue is not inherited by a child created with
 .Xr fork 2 .
 However, if
 .Xr rfork 2
 is called without the
 .Dv RFFDG
 flag, then the descriptor table is shared,
 which will allow sharing of the kqueue between two processes.
 .Pp
 The
 .Fn kevent
 system call
 is used to register events with the queue, and return any pending
 events to the user.
 The
 .Fa changelist
 argument
 is a pointer to an array of
 .Va kevent
 structures, as defined in
 .In sys/event.h .
 All changes contained in the
 .Fa changelist
 are applied before any pending events are read from the queue.
 The
 .Fa nchanges
 argument
 gives the size of
 .Fa changelist .
 The
 .Fa eventlist
 argument
 is a pointer to an array of kevent structures.
 The
 .Fa nevents
 argument
 determines the size of
 .Fa eventlist .
 When
 .Fa nevents
 is zero,
 .Fn kevent
 will return immediately even if there is a
 .Fa timeout
 specified unlike
 .Xr select 2 .
 If
 .Fa timeout
 is a non-NULL pointer, it specifies a maximum interval to wait
 for an event, which will be interpreted as a struct timespec.
 If
 .Fa timeout
 is a NULL pointer,
 .Fn kevent
 waits indefinitely.
 To effect a poll, the
 .Fa timeout
 argument should be non-NULL, pointing to a zero-valued
 .Va timespec
 structure.
 The same array may be used for the
 .Fa changelist
 and
 .Fa eventlist .
 .Pp
 The
 .Fn EV_SET
 macro is provided for ease of initializing a
 kevent structure.
 .Pp
 The
 .Va kevent
 structure is defined as:
 .Bd -literal
 struct kevent {
 	uintptr_t  ident;	/* identifier for this event */
 	short	  filter;	/* filter for event */
 	u_short	  flags;	/* action flags for kqueue */
 	u_int	  fflags;	/* filter flag value */
 	int64_t   data;		/* filter data value */
 	void	  *udata;	/* opaque user data identifier */
 	uint64_t  ext[4];	/* extensions */
 };
 .Ed
 .Pp
 The fields of
 .Fa struct kevent
 are:
 .Bl -tag -width "Fa filter"
 .It Fa ident
 Value used to identify this event.
 The exact interpretation is determined by the attached filter,
 but often is a file descriptor.
 .It Fa filter
 Identifies the kernel filter used to process this event.
 The pre-defined
 system filters are described below.
 .It Fa flags
 Actions to perform on the event.
 .It Fa fflags
 Filter-specific flags.
 .It Fa data
 Filter-specific data value.
 .It Fa udata
 Opaque user-defined value passed through the kernel unchanged.
 .It Fa ext
 Extended data passed to and from kernel.
 The
 .Fa ext[0]
 and
 .Fa ext[1]
 members use is defined by the filter.
 If the filter does not use them, the members are copied unchanged.
 The
 .Fa ext[2]
 and
 .Fa ext[3]
 members are always passed through the kernel as-is,
 making additional context available to application.
 .El
 .Pp
 The
 .Va flags
 field can contain the following values:
 .Bl -tag -width EV_DISPATCH
 .It Dv EV_ADD
 Adds the event to the kqueue.
 Re-adding an existing event
 will modify the parameters of the original event, and not result
 in a duplicate entry.
 Adding an event automatically enables it,
 unless overridden by the EV_DISABLE flag.
 .It Dv EV_ENABLE
 Permit
 .Fn kevent
 to return the event if it is triggered.
 .It Dv EV_DISABLE
 Disable the event so
 .Fn kevent
 will not return it.
 The filter itself is not disabled.
 .It Dv EV_DISPATCH
 Disable the event source immediately after delivery of an event.
 See
 .Dv EV_DISABLE
 above.
 .It Dv EV_DELETE
 Removes the event from the kqueue.
 Events which are attached to
 file descriptors are automatically deleted on the last close of
 the descriptor.
 .It Dv EV_RECEIPT
 This flag is useful for making bulk changes to a kqueue without draining
 any pending events.
 When passed as input, it forces
 .Dv EV_ERROR
 to always be returned.
 When a filter is successfully added the
 .Va data
 field will be zero.
 Note that if this flag is encountered and there is no remaining space in
 .Fa eventlist
 to hold the
 .Dv EV_ERROR
 event, then subsequent changes will not get processed.
 .It Dv EV_ONESHOT
 Causes the event to return only the first occurrence of the filter
 being triggered.
 After the user retrieves the event from the kqueue,
 it is deleted.
 .It Dv EV_CLEAR
 After the event is retrieved by the user, its state is reset.
 This is useful for filters which report state transitions
 instead of the current state.
 Note that some filters may automatically
 set this flag internally.
 .It Dv EV_EOF
 Filters may set this flag to indicate filter-specific EOF condition.
 .It Dv EV_ERROR
 See
 .Sx RETURN VALUES
 below.
 .El
 .Pp
 The predefined system filters are listed below.
 Arguments may be passed to and from the filter via the
 .Va fflags
 and
 .Va data
 fields in the kevent structure.
 .Bl -tag -width "Dv EVFILT_PROCDESC"
 .It Dv EVFILT_READ
 Takes a descriptor as the identifier, and returns whenever
 there is data available to read.
 The behavior of the filter is slightly different depending
 on the descriptor type.
 .Bl -tag -width 2n
 .It Sockets
 Sockets which have previously been passed to
 .Fn listen
 return when there is an incoming connection pending.
 .Va data
 contains the size of the listen backlog.
 .Pp
 Other socket descriptors return when there is data to be read,
 subject to the
 .Dv SO_RCVLOWAT
 value of the socket buffer.
 This may be overridden with a per-filter low water mark at the
 time the filter is added by setting the
 .Dv NOTE_LOWAT
 flag in
 .Va fflags ,
 and specifying the new low water mark in
 .Va data .
 On return,
 .Va data
 contains the number of bytes of protocol data available to read.
 .Pp
 If the read direction of the socket has shutdown, then the filter
 also sets
 .Dv EV_EOF
 in
 .Va flags ,
 and returns the socket error (if any) in
 .Va fflags .
 It is possible for EOF to be returned (indicating the connection is gone)
 while there is still data pending in the socket buffer.
 .It Vnodes
 Returns when the file pointer is not at the end of file.
 .Va data
 contains the offset from current position to end of file,
 and may be negative.
 .Pp
 This behavior is different from
 .Xr poll 2 ,
 where read events are triggered for regular files unconditionally.
 This event can be triggered unconditionally by setting the
 .Dv NOTE_FILE_POLL
 flag in
 .Va fflags .
 .It "Fifos, Pipes"
 Returns when the there is data to read;
 .Va data
 contains the number of bytes available.
 .Pp
 When the last writer disconnects, the filter will set
 .Dv EV_EOF
 in
 .Va flags .
 This will be cleared by the filter when a new writer connects,
 at which point the
 filter will resume waiting for data to become available before
 returning.
 .It "BPF devices"
 Returns when the BPF buffer is full, the BPF timeout has expired, or
 when the BPF has
 .Dq immediate mode
 enabled and there is any data to read;
 .Va data
 contains the number of bytes available.
 .El
 .It Dv EVFILT_WRITE
 Takes a descriptor as the identifier, and returns whenever
 it is possible to write to the descriptor.
 For sockets, pipes
 and fifos,
 .Va data
 will contain the amount of space remaining in the write buffer.
 The filter will set
 .Dv EV_EOF
 when the reader disconnects, and for the fifo case, this will be cleared
 when a new reader connects.
 Note that this filter is not supported for vnodes or BPF devices.
 .Pp
 For sockets, the low water mark and socket error handling is
 identical to the
 .Dv EVFILT_READ
 case.
 .It Dv EVFILT_EMPTY
 Takes a descriptor as the identifier, and returns whenever
 there is no remaining data in the write buffer.
 .It Dv EVFILT_AIO
 Events for this filter are not registered with
 .Fn kevent
 directly but are registered via the
 .Va aio_sigevent
 member of an asynchronous I/O request when it is scheduled via an
 asynchronous I/O system call such as
 .Fn aio_read .
 The filter returns under the same conditions as
 .Fn aio_error .
 For more details on this filter see
 .Xr sigevent 3 and
 .Xr aio 4 .
 .It Dv EVFILT_VNODE
 Takes a file descriptor as the identifier and the events to watch for in
 .Va fflags ,
 and returns when one or more of the requested events occurs on the descriptor.
 The events to monitor are:
 .Bl -tag -width "Dv NOTE_CLOSE_WRITE"
 .It Dv NOTE_ATTRIB
 The file referenced by the descriptor had its attributes changed.
 .It Dv NOTE_CLOSE
 A file descriptor referencing the monitored file, was closed.
 The closed file descriptor did not have write access.
 .It Dv NOTE_CLOSE_WRITE
 A file descriptor referencing the monitored file, was closed.
 The closed file descriptor had write access.
 .Pp
 This note, as well as
 .Dv NOTE_CLOSE ,
 are not activated when files are closed forcibly by
 .Xr unmount 2 or
 .Xr revoke 2 .
 Instead,
 .Dv NOTE_REVOKE
 is sent for such events.
 .It Dv NOTE_DELETE
 The
 .Fn unlink
 system call was called on the file referenced by the descriptor.
 .It Dv NOTE_EXTEND
 For regular file, the file referenced by the descriptor was extended.
 .Pp
 For directory, reports that a directory entry was added or removed,
 as the result of rename operation.
 The
 .Dv NOTE_EXTEND
 event is not reported when a name is changed inside the directory.
 .It Dv NOTE_LINK
 The link count on the file changed.
 In particular, the
 .Dv NOTE_LINK
 event is reported if a subdirectory was created or deleted inside
 the directory referenced by the descriptor.
 .It Dv NOTE_OPEN
 The file referenced by the descriptor was opened.
 .It Dv NOTE_READ
 A read occurred on the file referenced by the descriptor.
 .It Dv NOTE_RENAME
 The file referenced by the descriptor was renamed.
 .It Dv NOTE_REVOKE
 Access to the file was revoked via
 .Xr revoke 2
 or the underlying file system was unmounted.
 .It Dv NOTE_WRITE
 A write occurred on the file referenced by the descriptor.
 .El
 .Pp
 On return,
 .Va fflags
 contains the events which triggered the filter.
 .It Dv EVFILT_PROC
 Takes the process ID to monitor as the identifier and the events to watch for
 in
 .Va fflags ,
 and returns when the process performs one or more of the requested events.
 If a process can normally see another process, it can attach an event to it.
 The events to monitor are:
 .Bl -tag -width "Dv NOTE_TRACKERR"
 .It Dv NOTE_EXIT
 The process has exited.
 The exit status will be stored in
 .Va data .
 .It Dv NOTE_FORK
 The process has called
 .Fn fork .
 .It Dv NOTE_EXEC
 The process has executed a new process via
 .Xr execve 2
 or a similar call.
 .It Dv NOTE_TRACK
 Follow a process across
 .Fn fork
 calls.
 The parent process registers a new kevent to monitor the child process
 using the same
 .Va fflags
 as the original event.
 The child process will signal an event with
 .Dv NOTE_CHILD
 set in
 .Va fflags
 and the parent PID in
 .Va data .
 .Pp
 If the parent process fails to register a new kevent
 .Pq usually due to resource limitations ,
 it will signal an event with
 .Dv NOTE_TRACKERR
 set in
 .Va fflags ,
 and the child process will not signal a
 .Dv NOTE_CHILD
 event.
 .El
 .Pp
 On return,
 .Va fflags
 contains the events which triggered the filter.
 .It Dv EVFILT_PROCDESC
 Takes the process descriptor created by
 .Xr pdfork 2
 to monitor as the identifier and the events to watch for in
 .Va fflags ,
 and returns when the associated process performs one or more of the
 requested events.
 The events to monitor are:
 .Bl -tag -width "Dv NOTE_EXIT"
 .It Dv NOTE_EXIT
 The process has exited.
 The exit status will be stored in
 .Va data .
 .El
 .Pp
 On return,
 .Va fflags
 contains the events which triggered the filter.
 .It Dv EVFILT_SIGNAL
 Takes the signal number to monitor as the identifier and returns
 when the given signal is delivered to the process.
 This coexists with the
 .Fn signal
 and
 .Fn sigaction
 facilities, and has a lower precedence.
 The filter will record
 all attempts to deliver a signal to a process, even if the signal has
 been marked as
 .Dv SIG_IGN ,
 except for the
 .Dv SIGCHLD
 signal, which, if ignored, will not be recorded by the filter.
 Event notification happens after normal
 signal delivery processing.
 .Va data
 returns the number of times the signal has occurred since the last call to
 .Fn kevent .
 This filter automatically sets the
 .Dv EV_CLEAR
 flag internally.
 .It Dv EVFILT_TIMER
 Establishes an arbitrary timer identified by
 .Va ident .
 When adding a timer,
 .Va data
 specifies the moment to fire the timer (for
 .Dv NOTE_ABSTIME )
 or the timeout period.
 The timer will be periodic unless
 .Dv EV_ONESHOT
 or
 .Dv NOTE_ABSTIME
 is specified.
 On return,
 .Va data
 contains the number of times the timeout has expired since the last call to
 .Fn kevent .
 For non-monotonic timers, this filter automatically sets the
 .Dv EV_CLEAR
 flag internally.
 .Pp
 The filter accepts the following flags in the
 .Va fflags
 argument:
 .Bl -tag -width "Dv NOTE_MSECONDS"
 .It Dv NOTE_SECONDS
 .Va data
 is in seconds.
 .It Dv NOTE_MSECONDS
 .Va data
 is in milliseconds.
 .It Dv NOTE_USECONDS
 .Va data
 is in microseconds.
 .It Dv NOTE_NSECONDS
 .Va data
 is in nanoseconds.
 .It Dv NOTE_ABSTIME
 The specified expiration time is absolute.
 .El
 .Pp
 If
 .Va fflags
 is not set, the default is milliseconds.
 On return,
 .Va fflags
 contains the events which triggered the filter.
 .Pp
 If an existing timer is re-added, the existing timer will be
 effectively canceled (throwing away any undelivered record of previous
 timer expiration) and re-started using the new parameters contained in
 .Va data
 and
 .Va fflags .
 .Pp
 There is a system wide limit on the number of timers
 which is controlled by the
 .Va kern.kq_calloutmax
 sysctl.
 .It Dv EVFILT_USER
 Establishes a user event identified by
 .Va ident
 which is not associated with any kernel mechanism but is triggered by
 user level code.
 The lower 24 bits of the
 .Va fflags
 may be used for user defined flags and manipulated using the following:
 .Bl -tag -width "Dv NOTE_FFLAGSMASK"
 .It Dv NOTE_FFNOP
 Ignore the input
 .Va fflags .
 .It Dv NOTE_FFAND
 Bitwise AND
 .Va fflags .
 .It Dv NOTE_FFOR
 Bitwise OR
 .Va fflags .
 .It Dv NOTE_FFCOPY
 Copy
 .Va fflags .
 .It Dv NOTE_FFCTRLMASK
 Control mask for
 .Va fflags .
 .It Dv NOTE_FFLAGSMASK
 User defined flag mask for
 .Va fflags .
 .El
 .Pp
 A user event is triggered for output with the following:
 .Bl -tag -width "Dv NOTE_FFLAGSMASK"
 .It Dv NOTE_TRIGGER
 Cause the event to be triggered.
 .El
 .Pp
 On return,
 .Va fflags
 contains the users defined flags in the lower 24 bits.
 .El
 .Sh CANCELLATION BEHAVIOUR
 If
 .Fa nevents
 is non-zero, i.e., the function is potentially blocking, the call
 is a cancellation point.
 Otherwise, i.e., if
 .Fa nevents
 is zero, the call is not cancellable.
 Cancellation can only occur before any changes are made to the kqueue,
 or when the call was blocked and no changes to the queue were requested.
 .Sh RETURN VALUES
 The
 .Fn kqueue
 system call
 creates a new kernel event queue and returns a file descriptor.
 If there was an error creating the kernel event queue, a value of -1 is
 returned and errno set.
 .Pp
 The
 .Fn kevent
 system call
 returns the number of events placed in the
 .Fa eventlist ,
 up to the value given by
 .Fa nevents .
 If an error occurs while processing an element of the
 .Fa changelist
 and there is enough room in the
 .Fa eventlist ,
 then the event will be placed in the
 .Fa eventlist
 with
 .Dv EV_ERROR
 set in
 .Va flags
 and the system error in
 .Va data .
 Otherwise,
 .Dv -1
 will be returned, and
 .Dv errno
 will be set to indicate the error condition.
 If the time limit expires, then
 .Fn kevent
 returns 0.
 .Sh EXAMPLES
 .Bd -literal -compact
 #include <sys/event.h>
 #include <err.h>
 #include <fcntl.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
 int
 main(int argc, char **argv)
 {
     struct kevent event;    /* Event we want to monitor */
     struct kevent tevent;   /* Event triggered */
     int kq, fd, ret;
 
     if (argc != 2)
 	err(EXIT_FAILURE, "Usage: %s path\en", argv[0]);
     fd = open(argv[1], O_RDONLY);
     if (fd == -1)
 	err(EXIT_FAILURE, "Failed to open '%s'", argv[1]);
 
     /* Create kqueue. */
     kq = kqueue();
     if (kq == -1)
 	err(EXIT_FAILURE, "kqueue() failed");
 
     /* Initialize kevent structure. */
     EV_SET(&event, fd, EVFILT_VNODE, EV_ADD | EV_CLEAR, NOTE_WRITE,
 	0, NULL);
     /* Attach event to the kqueue. */
     ret = kevent(kq, &event, 1, NULL, 0, NULL);
     if (ret == -1)
 	err(EXIT_FAILURE, "kevent register");
     if (event.flags & EV_ERROR)
 	errx(EXIT_FAILURE, "Event error: %s", strerror(event.data));
 
     for (;;) {
 	/* Sleep until something happens. */
 	ret = kevent(kq, NULL, 0, &tevent, 1, NULL);
 	if (ret == -1) {
 	    err(EXIT_FAILURE, "kevent wait");
 	} else if (ret > 0) {
 	    printf("Something was written in '%s'\en", argv[1]);
 	}
     }
 }
 .Ed
 .Sh ERRORS
 The
 .Fn kqueue
 system call fails if:
 .Bl -tag -width Er
 .It Bq Er ENOMEM
 The kernel failed to allocate enough memory for the kernel queue.
 .It Bq Er ENOMEM
 The
 .Dv RLIMIT_KQUEUES
 rlimit
 (see
 .Xr getrlimit 2 )
 for the current user would be exceeded.
 .It Bq Er EMFILE
 The per-process descriptor table is full.
 .It Bq Er ENFILE
 The system file table is full.
 .El
 .Pp
 The
 .Fn kevent
 system call fails if:
 .Bl -tag -width Er
 .It Bq Er EACCES
 The process does not have permission to register a filter.
 .It Bq Er EFAULT
 There was an error reading or writing the
 .Va kevent
 structure.
 .It Bq Er EBADF
 The specified descriptor is invalid.
 .It Bq Er EINTR
 A signal was delivered before the timeout expired and before any
 events were placed on the kqueue for return.
 .It Bq Er EINTR
 A cancellation request was delivered to the thread, but not yet handled.
 .It Bq Er EINVAL
 The specified time limit or filter is invalid.
 .It Bq Er ENOENT
 The event could not be found to be modified or deleted.
 .It Bq Er ENOMEM
 No memory was available to register the event
 or, in the special case of a timer, the maximum number of
 timers has been exceeded.
 This maximum is configurable via the
 .Va kern.kq_calloutmax
 sysctl.
 .It Bq Er ESRCH
 The specified process to attach to does not exist.
 .El
 .Pp
 When
 .Fn kevent
 call fails with
 .Er EINTR
 error, all changes in the
 .Fa changelist
 have been applied.
 .Sh SEE ALSO
 .Xr aio_error 2 ,
 .Xr aio_read 2 ,
 .Xr aio_return 2 ,
 .Xr poll 2 ,
 .Xr read 2 ,
 .Xr select 2 ,
 .Xr sigaction 2 ,
 .Xr write 2 ,
 .Xr pthread_setcancelstate 3 ,
 .Xr signal 3
+.Rs
+.%A Jonathan Lemon
+.%T "Kqueue: A Generic and Scalable Event Notification Facility"
+.%I USENIX Association
+.%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference
+.%D June 25-30, 2001
+.\".http://www.usenix.org/event/usenix01/freenix01/full_papers/lemon/lemon.pdf
+.Re
 .Sh HISTORY
 The
 .Fn kqueue
 and
 .Fn kevent
 system calls first appeared in
 .Fx 4.1 .
 .Sh AUTHORS
 The
 .Fn kqueue
 system and this manual page were written by
 .An Jonathan Lemon Aq Mt jlemon@FreeBSD.org .
 .Sh BUGS
 The
 .Fa timeout
 value is limited to 24 hours; longer timeouts will be silently
 reinterpreted as 24 hours.
 .Pp
 In versions older than
 .Fx 12.0 ,
 .In sys/event.h
 failed to parse without including
 .In sys/types.h
 manually.
Index: stable/12
===================================================================
--- stable/12	(revision 362681)
+++ stable/12	(revision 362682)

Property changes on: stable/12
___________________________________________________________________
Modified: svn:mergeinfo
## -0,0 +0,1 ##
   Merged /head:r362171