diff --git a/bin/ls/ls.1 b/bin/ls/ls.1 index fdfcb50beb06..4f680d97ea0b 100644 --- a/bin/ls/ls.1 +++ b/bin/ls/ls.1 @@ -1,944 +1,944 @@ .\"- .\" Copyright (c) 1980, 1990, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the Institute of Electrical and Electronics Engineers, Inc. .\" .\" 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. .\" .Dd July 18, 2023 .Dt LS 1 .Os .Sh NAME .Nm ls .Nd list directory contents .Sh SYNOPSIS .Nm .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuvwxy1\&, .Op Fl -color Ns = Ns Ar when .Op Fl D Ar format .Op Ar .Sh DESCRIPTION For each operand that names a .Ar file of a type other than directory, .Nm displays its name as well as any requested, associated information. For each operand that names a .Ar file of type directory, .Nm displays the names of files contained within that directory, as well as any requested, associated information. .Pp If no operands are given, the contents of the current directory are displayed. If more than one operand is given, non-directory operands are displayed first; directory and non-directory operands are sorted separately and in lexicographical order. .Pp The following options are available: .Bl -tag -width indent .It Fl A Include directory entries whose names begin with a dot .Pq Sq Pa \&. except for .Pa \&. and .Pa .. . Automatically set for the super-user unless .Fl I is specified. .It Fl B Force printing of non-printable characters (as defined by .Xr ctype 3 and current locale settings) in file names as .Li \e Ns Va xxx , where .Va xxx is the numeric value of the character in octal. This option is not defined in .St -p1003.1-2008 . .It Fl C Force multi-column output; this is the default when output is to a terminal. .It Fl D Ar format When printing in the long .Pq Fl l format, use .Ar format to format the date and time output. The argument .Ar format is a string used by .Xr strftime 3 . Depending on the choice of format string, this may result in a different number of columns in the output. This option overrides the .Fl T option. This option is not defined in .St -p1003.1-2008 . .It Fl F Display a slash .Pq Ql / immediately after each pathname that is a directory, an asterisk .Pq Ql * after each that is executable, an at sign .Pq Ql @ after each symbolic link, an equals sign .Pq Ql = after each socket, a percent sign .Pq Ql % after each whiteout, and a vertical bar .Pq Ql \&| after each that is a .Tn FIFO . .It Fl G Enable colorized output. This option is equivalent to defining .Ev CLICOLOR or .Ev COLORTERM in the environment and setting .Fl -color Ns = Ns Ar auto . (See below.) This functionality can be compiled out by removing the definition of .Ev COLORLS . This option is not defined in .St -p1003.1-2008 . .It Fl H Symbolic links on the command line are followed. This option is assumed if none of the .Fl F , d , or .Fl l options are specified. .It Fl I Prevent .Fl A from being automatically set for the super-user. This option is not defined in .St -p1003.1-2008 . .It Fl L If argument is a symbolic link, list the file or directory the link references rather than the link itself. This option cancels the .Fl P option. .It Fl P If argument is a symbolic link, list the link itself rather than the object the link references. This option cancels the .Fl H and .Fl L options. .It Fl R Recursively list subdirectories encountered. .It Fl S Sort by size (largest file first) before sorting the operands in lexicographical order. .It Fl T When printing in the long .Pq Fl l format, display complete time information for the file, including month, day, hour, minute, second, and year. The .Fl D option gives even more control over the output format. This option is not defined in .St -p1003.1-2008 . .It Fl U Use time when file was created for sorting or printing. This option is not defined in .St -p1003.1-2008 . .It Fl W Display whiteouts when scanning directories. This option is not defined in .St -p1003.1-2008 . .It Fl Z Display each file's MAC label; see .Xr maclabel 7 . This option is not defined in .St -p1003.1-2008 . .It Fl a Include directory entries whose names begin with a dot .Pq Sq Pa \&. . .It Fl b As .Fl B , but use .Tn C escape codes whenever possible. This option is not defined in .St -p1003.1-2008 . .It Fl c Use time when file status was last changed for sorting or printing. .It Fl -color Ns = Ns Ar when Output colored escape sequences based on .Ar when , which may be set to either .Cm always , .Cm auto , or .Cm never . .Pp .Cm always will make .Nm always output color. If .Ev TERM is unset or set to an invalid terminal, then .Nm will fall back to explicit .Tn ANSI escape sequences without the help of .Xr termcap 5 . .Cm always is the default if .Fl -color is specified without an argument. .Pp .Cm auto will make .Nm output escape sequences based on .Xr termcap 5 , but only if .Dv stdout is a tty and either the .Fl G flag is specified or the .Ev COLORTERM environment variable is set and not empty. .Pp .Cm never will disable color regardless of environment variables. .Cm never is the default when neither .Fl -color nor .Fl G is specified. .Pp For compatibility with GNU coreutils, .Nm supports .Cm yes or .Cm force as equivalent to .Cm always , .Cm no or .Cm none as equivalent to .Cm never , and .Cm tty or .Cm if-tty as equivalent to .Cm auto . .It Fl d Directories are listed as plain files (not searched recursively). .It Fl f Output is not sorted. This option turns on .Fl a . It also negates the effect of the .Fl r , .Fl S and .Fl t options. As allowed by .St -p1003.1-2008 , this option has no effect on the .Fl d , .Fl l , .Fl R and .Fl s options. .It Fl g Display the long .Pq Fl l format output without the file owner's name or number. .It Fl h When used with the .Fl l option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte in order to reduce the number of digits to four or fewer using base 2 for sizes. This option is not defined in .St -p1003.1-2008 . .It Fl i For each file, print the file's file serial number (inode number). .It Fl k This has the same effect as setting environment variable .Ev BLOCKSIZE to 1024, except that it also nullifies any .Fl h options to its left. .It Fl l (The lowercase letter .Dq ell . ) List files in the long format, as described in the .Sx The Long Format subsection below. .It Fl m Stream output format; list files across the page, separated by commas. .It Fl n Display user and group IDs numerically rather than converting to a user or group name in a long .Pq Fl l output. .It Fl o Include the file flags in a long .Pq Fl l output. This option is incompatible with .St -p1003.1-2008 . See .Xr chflags 1 for a list of file flags and their meanings. .It Fl p Write a slash .Pq Ql / after each filename if that file is a directory. .It Fl q Force printing of non-graphic characters in file names as the character .Ql \&? ; this is the default when output is to a terminal. .It Fl r Reverse the order of the sort. .It Fl s Display the number of blocks used in the file system by each file. Block sizes and directory totals are handled as described in .Sx The Long Format subsection below, except (if the long format is not also requested) the directory totals are not output when the output is in a single column, even if multi-column output is requested. .It Fl t Sort by descending time modified (most recently modified first). If two files have the same modification timestamp, sort their names in ascending lexicographical order. The .Fl r option reverses both of these sort orders. .Pp Note that these sort orders are contradictory: the time sequence is in descending order, the lexicographical sort is in ascending order. This behavior is mandated by .St -p1003.2 . This feature can cause problems listing files stored with sequential names on FAT file systems, such as from digital cameras, where it is possible to have more than one image with the same timestamp. In such a case, the photos cannot be listed in the sequence in which they were taken. To ensure the same sort order for time and for lexicographical sorting, set the environment variable .Ev LS_SAMESORT or use the .Fl y option. This causes .Nm to reverse the lexicographical sort order when sorting files with the same modification timestamp. .It Fl u Use time of last access, instead of time of last modification of the file for sorting .Pq Fl t or printing .Pq Fl l . .It Fl v Sort following a natural ordering, using .Xr strverscmp 3 instead of .Xr strcoll 3 as the comparison function. E.g., files lexicographically ordered "bloem1", "bloem10", and "bloem9" would instead be ordered "bloem1", "bloem9", and "bloem10", as one would perhaps expect. .It Fl w Force raw printing of non-printable characters. This is the default when output is not to a terminal. This option is not defined in .St -p1003.1-2001 . .It Fl x The same as .Fl C , except that the multi-column output is produced with entries sorted across, rather than down, the columns. .It Fl y When the .Fl t option is set, sort the alphabetical output in the same order as the time output. This has the same effect as setting .Ev LS_SAMESORT . See the description of the .Fl t option for more details. This option is not defined in .St -p1003.1-2001 . .It Fl 1 (The numeric digit .Dq one . ) Force output to be one entry per line. This is the default when output is not to a terminal. .It Fl , (Comma) When the .Fl l option is set, print file sizes grouped and separated by thousands using the non-monetary separator returned by .Xr localeconv 3 , typically a comma or period. If no locale is set, or the locale does not have a non-monetary separator, this option has no effect. This option is not defined in .St -p1003.1-2001 . .El .Pp The .Fl 1 , C , x , and .Fl l options all override each other; the last one specified determines the format used. .Pp The .Fl c , u , and .Fl U options all override each other; the last one specified determines the file time used. .Pp The .Fl S and .Fl t options override each other; the last one specified determines the sort order used. .Pp The .Fl B , b , w , and .Fl q options all override each other; the last one specified determines the format used for non-printable characters. .Pp The .Fl H , L and .Fl P options all override each other (either partially or fully); they are applied in the order specified. .Pp By default, .Nm lists one entry per line to standard output; the exceptions are to terminals or when the .Fl C or .Fl x options are specified. .Pp File information is displayed with one or more .Ao blank Ac Ns s separating the information associated with the .Fl i , s , and .Fl l options. .Ss The Long Format If the .Fl l option is given, the following information is displayed for each file: file mode, number of links, owner name, group name, MAC label, number of bytes in the file, abbreviated month, day-of-month file was last modified, hour file last modified, minute file last modified, and the pathname. .Pp If the modification time of the file is more than 6 months in the past or future, and the .Fl D or .Fl T are not specified, then the year of the last modification is displayed in place of the hour and minute fields. .Pp If the owner or group names are not a known user or group name, or the .Fl n option is given, the numeric ID's are displayed. .Pp If the file is a character special or block special file, the device number for the file is displayed in the size field. If the file is a symbolic link the pathname of the linked-to file is preceded by .Dq Li -> . .Pp The listing of a directory's contents is preceded by a labeled total number of blocks used in the file system by the files which are listed as the directory's contents (which may or may not include .Pa \&. and .Pa .. and other files which start with a dot, depending on other options). .Pp The default block size is 512 bytes. The block size may be set with option .Fl k or environment variable .Ev BLOCKSIZE . Numbers of blocks in the output will have been rounded up so the numbers of bytes is at least as many as used by the corresponding file system blocks (which might have a different size). .Pp The file mode printed under the .Fl l option consists of the entry type and the permissions. The entry type character describes the type of file, as follows: .Pp .Bl -tag -width 4n -offset indent -compact .It Sy \- Regular file. .It Sy b Block special file. .It Sy c Character special file. .It Sy d Directory. .It Sy l Symbolic link. .It Sy p .Tn FIFO . .It Sy s Socket. .It Sy w Whiteout. .El .Pp The next three fields are three characters each: owner permissions, group permissions, and other permissions. Each field has three character positions: .Bl -enum -offset indent .It If .Sy r , the file is readable; if .Sy \- , it is not readable. .It If .Sy w , the file is writable; if .Sy \- , it is not writable. .It The first of the following that applies: .Bl -tag -width 4n -offset indent .It Sy S If in the owner permissions, the file is not executable and set-user-ID mode is set. If in the group permissions, the file is not executable and set-group-ID mode is set. .It Sy s If in the owner permissions, the file is executable and set-user-ID mode is set. If in the group permissions, the file is executable and setgroup-ID mode is set. .It Sy x The file is executable or the directory is searchable. .It Sy \- The file is neither readable, writable, executable, nor set-user-ID nor set-group-ID mode, nor sticky. (See below.) .El .Pp These next two apply only to the third character in the last group (other permissions). .Bl -tag -width 4n -offset indent .It Sy T The sticky bit is set (mode .Li 1000 ) , but not execute or search permission. (See .Xr chmod 1 or .Xr sticky 7 . ) .It Sy t The sticky bit is set (mode .Li 1000 ) , and is searchable or executable. (See .Xr chmod 1 or .Xr sticky 7 . ) .El .El .Pp The next field contains a plus .Pq Ql + character if the file has an ACL, or a space .Pq Ql " " if it does not. The .Nm utility does not show the actual ACL; use .Xr getfacl 1 to do this. .Sh ENVIRONMENT The following environment variables affect the execution of .Nm : .Bl -tag -width ".Ev CLICOLOR_FORCE" .It Ev BLOCKSIZE If this is set, its value, rounded up to 512 or down to a multiple of 512, will be used as the block size in bytes by the .Fl l and .Fl s options. See .Sx The Long Format subsection for more information. .It Ev CLICOLOR Use .Tn ANSI color sequences to distinguish file types. See .Ev LSCOLORS below. In addition to the file types mentioned in the .Fl F option some extra attributes (setuid bit set, etc.) are also displayed. The colorization is dependent on a terminal type with the proper .Xr termcap 5 capabilities. The default .Dq Li cons25 console has the proper capabilities, but to display the colors in an .Xr xterm 1 Pq Pa ports/x11/xterm , for example, the .Ev TERM variable must be set to .Dq Li xterm-color . Other terminal types may require similar adjustments. Colorization is silently disabled if the output is not directed to a terminal unless the .Ev CLICOLOR_FORCE variable is defined or .Fl -color is set to .Dq always . .It Ev CLICOLOR_FORCE Color sequences are normally disabled if the output is not directed to a terminal. This can be overridden by setting this variable. The .Ev TERM variable still needs to reference a color capable terminal however otherwise it is not possible to determine which color sequences to use. .It Ev COLORTERM See description for .Ev CLICOLOR above. .It Ev COLUMNS If this variable contains a string representing a decimal integer, it is used as the column position width for displaying multiple-text-column output. The .Nm utility calculates how many pathname text columns to display based on the width provided. (See .Fl C and .Fl x . ) .It Ev LANG The locale to use when determining the order of day and month in the long .Fl l format output. See .Xr environ 7 for more information. .It Ev LSCOLORS The value of this variable describes what color to use for which attribute when colors are enabled with .Ev CLICOLOR or .Ev COLORTERM . This string is a concatenation of pairs of the format .Ar f Ns Ar b , where .Ar f is the foreground color and .Ar b is the background color. When the background color is capitalized, the text is underlined. .Pp The color designators are as follows: .Pp .Bl -tag -width 4n -offset indent -compact .It Sy a black .It Sy b red .It Sy c green .It Sy d brown .It Sy e blue .It Sy f magenta .It Sy g cyan .It Sy h light grey .It Sy A bold or underlined black, usually shows up as dark grey .It Sy B bold or underlined red .It Sy C bold or underlined green .It Sy D bold or underlined brown, usually shows up as yellow .It Sy E bold or underlined blue .It Sy F bold or underlined magenta .It Sy G bold or underlined cyan .It Sy H bold or underlined light grey; looks like bright white .It Sy x default foreground or background .It Sy X default foreground or background, with an underline or bold .El .Pp Note that the above are standard .Tn ANSI colors. The actual display may differ depending on the color capabilities of the terminal in use. .Pp The order of the attributes are as follows: .Pp .Bl -enum -offset indent -compact .It directory .It symbolic link .It socket .It pipe .It executable .It block special .It character special .It executable with setuid bit set .It executable with setgid bit set .It directory writable to others, with sticky bit .It directory writable to others, without sticky bit .El .Pp The default is .Qq "exfxcxdxbxegedabagacad" , i.e., blue foreground and default background for regular directories, black foreground and red background for setuid executables, etc. .It Ev LS_COLWIDTHS If this variable is set, it is considered to be a colon-delimited list of minimum column widths. Unreasonable and insufficient widths are ignored (thus zero signifies a dynamically sized column). Not all columns have changeable widths. The fields are, in order: inode, block count, number of links, user name, group name, flags, file size, file name. .It Ev LS_SAMESORT If this variable is set, the .Fl t option sorts the names of files with the same modification timestamp in the same sense as the time sort. See the description of the .Fl t option for more details. .It Ev TERM The .Ev CLICOLOR and .Ev COLORTERM functionality depends on a terminal type with color capabilities. .It Ev TZ The timezone to use when displaying dates. See .Xr environ 7 for more information. .El .Sh EXIT STATUS .Ex -std .Sh EXAMPLES List the contents of the current working directory in long format: .Pp .Dl $ ls -l .Pp In addition to listing the contents of the current working directory in long format, show inode numbers, file flags (see .Xr chflags 1 ) , and suffix each filename with a symbol representing its file type: .Pp .Dl $ ls -lioF .Pp List the files in .Pa /var/log , sorting the output such that the mostly recently modified entries are printed first: .Pp .Dl $ ls -lt /var/log .Sh COMPATIBILITY The group field is now automatically included in the long listing for files in order to be compatible with the .St -p1003.2 specification. .Sh SEE ALSO .Xr chflags 1 , .Xr chmod 1 , .Xr getfacl 1 , .Xr sort 1 , .Xr xterm 1 Pq Pa ports/x11/xterm , .Xr localeconv 3 , .Xr strcoll 3 , .Xr strftime 3 , .Xr strmode 3 , .Xr strverscmp 3 , .Xr termcap 5 , .Xr maclabel 7 , .Xr sticky 7 , .Xr symlink 7 , .Xr getfmac 8 .Sh STANDARDS With the exception of options .Fl g , n and .Fl o , the .Nm utility conforms to .St -p1003.1-2001 and .St -p1003.1-2008 . The options .Fl B , D , G , I , T , U , W , Z , b , h , v , w , y and .Fl , are non-standard extensions. .Pp The ACL support is compatible with .Tn IEEE Std\~1003.2c .Pq Dq Tn POSIX Ns .2c Draft\~17 (withdrawn). .Sh HISTORY An .Nm command appeared in .At v1 . .Pp The .Fl v option was added in -.Fx 14.0 . +.Fx 13.2 . .Sh BUGS To maintain backward compatibility, the relationships between the many options are quite complex. .Pp The exception mentioned in the .Fl s option description might be a feature that was based on the fact that single-column output usually goes to something other than a terminal. It is debatable whether this is a design bug. .Pp .St -p1003.2 mandates opposite sort orders for files with the same timestamp when sorting with the .Fl t option. diff --git a/lib/libc/gen/posix_spawn_file_actions_addopen.3 b/lib/libc/gen/posix_spawn_file_actions_addopen.3 index ef6348daa4ba..80bc91454471 100644 --- a/lib/libc/gen/posix_spawn_file_actions_addopen.3 +++ b/lib/libc/gen/posix_spawn_file_actions_addopen.3 @@ -1,275 +1,275 @@ .\" Copyright (c) 2008 Ed Schouten .\" 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 BY THE AUTHOR 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 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. .\" .\" Portions of this text are reprinted and reproduced in electronic form .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- .\" Portable Operating System Interface (POSIX), The Open Group Base .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of .\" Electrical and Electronics Engineers, Inc and The Open Group. In the .\" event of any discrepancy between this version and the original IEEE and .\" The Open Group Standard, the original IEEE and The Open Group Standard is .\" the referee document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" .Dd May 9, 2013 .Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3 .Os .Sh NAME .Nm posix_spawn_file_actions_addopen , .Nm posix_spawn_file_actions_adddup2 , .Nm posix_spawn_file_actions_addclose , .Nm posix_spawn_file_actions_addclosefrom_np , .Nm posix_spawn_file_actions_addchdir_np , .Nm posix_spawn_file_actions_addfchdir_np .Nd "add open, dup2, close, closefrom, or chdir/fchdir actions to spawn file actions object" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In spawn.h .Ft int .Fo posix_spawn_file_actions_addopen .Fa "posix_spawn_file_actions_t * file_actions" .Fa "int fildes" .Fa "const char *restrict path" .Fa "int oflag" .Fa "mode_t mode" .Fc .Ft int .Fo posix_spawn_file_actions_adddup2 .Fa "posix_spawn_file_actions_t * file_actions" .Fa "int fildes" .Fa "int newfildes" .Fc .Ft int .Fo posix_spawn_file_actions_addclose .Fa "posix_spawn_file_actions_t * file_actions" .Fa "int fildes" .Fc .Ft int .Fo posix_spawn_file_actions_addclosefrom_np .Fa "posix_spawn_file_actions_t * file_actions" .Fa "int from" .Fc .Ft int .Fo posix_spawn_file_actions_addchdir_np .Fa "posix_spawn_file_actions_t *restrict file_actions" .Fa "const char *restrict path" .Fc .Ft int .Fo posix_spawn_file_actions_addfchdir_np .Fa "posix_spawn_file_actions_t * file_actions" .Fa "int fildes" .Fc .Sh DESCRIPTION These functions add an open, dup2 or close action to a spawn file actions object. .Pp A spawn file actions object is of type .Vt posix_spawn_file_actions_t (defined in .In spawn.h ) and is used to specify a series of actions to be performed by a .Fn posix_spawn or .Fn posix_spawnp operation in order to arrive at the set of open file descriptors for the child process given the set of open file descriptors of the parent. .Pp A spawn file actions object, when passed to .Fn posix_spawn or .Fn posix_spawnp , specify how the set of open file descriptors in the calling process is transformed into a set of potentially open file descriptors for the spawned process. This transformation is as if the specified sequence of actions was performed exactly once, in the context of the spawned process (prior to execution of the new process image), in the order in which the actions were added to the object; additionally, when the new process image is executed, any file descriptor (from this new set) which has its .Dv FD_CLOEXEC flag set is closed (see .Fn posix_spawn ) . .Pp The .Fn posix_spawn_file_actions_addopen function adds an open action to the object referenced by .Fa file_actions that causes the file named by .Fa path to be opened (as if .Bd -literal -offset indent open(path, oflag, mode) .Ed .Pp had been called, and the returned file descriptor, if not .Fa fildes , had been changed to .Fa fildes ) when a new process is spawned using this file actions object. If .Fa fildes was already an open file descriptor, it is closed before the new file is opened. .Pp The string described by .Fa path is copied by the .Fn posix_spawn_file_actions_addopen function. .Pp The .Fn posix_spawn_file_actions_adddup2 function adds a dup2 action to the object referenced by .Fa file_actions that causes the file descriptor .Fa fildes to be duplicated as .Fa newfildes (as if .Bd -literal -offset indent dup2(fildes, newfildes) .Ed .Pp had been called) when a new process is spawned using this file actions object, except that the .Dv FD_CLOEXEC flag for .Fa newfildes is cleared even if .Fa fildes is equal to .Fa newfildes . The difference from .Fn dup2 is useful for passing a particular file descriptor to a particular child process. .Pp The .Fn posix_spawn_file_actions_addclose function adds a close action to the object referenced by .Fa file_actions that causes the file descriptor .Fa fildes to be closed (as if .Bd -literal -offset indent close(fildes) .Ed .Pp had been called) when a new process is spawned using this file actions object. .Pp The .Fn posix_spawn_file_actions_addclosefrom_np function adds a close action to close all file descriptors numerically equal or greater then the argument .Fa from . For each open file descriptor, logically the close action is performed, and any possible errors encountered are ignored. .Pp The .Fn posix_spawn_file_actions_addchdir_np and .Fn posix_spawn_file_actions_addfchdir_np functions add a change current directory action to the object referenced by .Fa file_actions that affects actions (opens with relative path) performed after the operation, in the order of insertion into the .Fa file_actions object. It also sets the working directory for the spawned program. The .Fn posix_spawn_file_actions_addchdir_np function takes the .Fa path to set as the working directory, while .Fn posix_spawn_file_actions_addfchdir_np takes the directory file descriptor. .Sh RETURN VALUES Upon successful completion, these functions return zero; otherwise, an error number is returned to indicate the error. .Sh ERRORS These functions fail if: .Bl -tag -width Er .It Bq Er EBADF The value specified by .Fa fildes or .Fa newfildes is negative. .It Bq Er ENOMEM Insufficient memory exists to add to the spawn file actions object. .El .Sh SEE ALSO .Xr close 2 , .Xr dup2 2 , .Xr open 2 , .Xr posix_spawn 3 , .Xr posix_spawn_file_actions_destroy 3 , .Xr posix_spawn_file_actions_init 3 , .Xr posix_spawnp 3 .Sh STANDARDS The .Fn posix_spawn_file_actions_addopen , .Fn posix_spawn_file_actions_adddup2 and .Fn posix_spawn_file_actions_addclose functions conform to .St -p1003.1-2001 , with the exception of the behavior of .Fn posix_spawn_file_actions_adddup2 if .Fa fildes is equal to .Fa newfildes (clearing .Dv FD_CLOEXEC ) . A future update of the Standard is expected to require this behavior. .Pp The .Fn posix_spawn_file_actions_addchdir_np , .Fn posix_spawn_file_actions_addfchdir_np , and .Fn posix_spawn_file_actions_addclosefrom_np functions are non-standard functions implemented after the similar functionality provided by glibc. .Sh HISTORY The .Fn posix_spawn_file_actions_addopen , .Fn posix_spawn_file_actions_adddup2 and .Fn posix_spawn_file_actions_addclose functions first appeared in .Fx 8.0 . The .Fn posix_spawn_file_actions_addchdir_np , .Fn posix_spawn_file_actions_addfchdir_np , and .Fn posix_spawn_file_actions_addclosefrom_np functions first appeared in -.Fx 14.0 . +.Fx 13.1 . .Sh AUTHORS .An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2 index e4cd3deea512..32dbc7a39711 100644 --- a/lib/libc/sys/fork.2 +++ b/lib/libc/sys/fork.2 @@ -1,268 +1,268 @@ .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd August 5, 2021 .Dt FORK 2 .Os .Sh NAME .Nm fork .Nd create a new process .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft pid_t .Fn fork void .Ft pid_t .Fn _Fork void .Sh DESCRIPTION The .Fn fork function causes creation of a new process. The new process (child process) is an exact copy of the calling process (parent process) except for the following: .Bl -bullet -offset indent .It The child process has a unique process ID. .It The child process has a different parent process ID (i.e., the process ID of the parent process). .It The child process has its own copy of the parent's descriptors, except for descriptors returned by .Xr kqueue 2 , which are not inherited from the parent process. These descriptors reference the same underlying objects, so that, for instance, file pointers in file objects are shared between the child and the parent, so that an .Xr lseek 2 on a descriptor in the child process can affect a subsequent .Xr read 2 or .Xr write 2 by the parent. This descriptor copying is also used by the shell to establish standard input and output for newly created processes as well as to set up pipes. .It The child process' resource utilizations are set to 0; see .Xr setrlimit 2 . .It All interval timers are cleared; see .Xr setitimer 2 . .It The robust mutexes list (see .Xr pthread_mutexattr_setrobust 3 ) is cleared for the child. .It The atfork handlers established with the .Xr pthread_atfork 3 function are called as appropriate before fork in the parent process, and after the child is created, in parent and child. .It The child process has only one thread, corresponding to the calling thread in the parent process. If the process has more than one thread, locks and other resources held by the other threads are not released and therefore only async-signal-safe functions (see .Xr sigaction 2 ) are guaranteed to work in the child process until a call to .Xr execve 2 or a similar function. The .Fx implementation of .Fn fork provides a usable .Xr malloc 3 , and .Xr rtld 1 services in the child process. .El .Pp The .Fn fork function is not async-signal safe and creates a cancellation point in the parent process. It cannot be safely used from signal handlers, and the atfork handlers established by .Xr pthread_atfork 3 do not need to be async-signal safe either. .Pp The .Fn _Fork function creates a new process, similarly to .Fn fork , but it is async-signal safe. .Fn _Fork does not call atfork handlers, and does not create a cancellation point. It can be used safely from signal handlers, but then no userspace services ( .Xr malloc 3 or .Xr rtld 1 ) are available in the child if forked from multi-threaded parent. In particular, if using dynamic linking, all dynamic symbols used by the child after .Fn _Fork must be pre-resolved. Note: resolving can be done globally by specifying the .Ev LD_BIND_NOW environment variable to the dynamic linker, or per-binary by passing the .Fl z Ar now option to the static linker .Xr ld 1 , or by using each symbol before the .Fn _Fork call to force the binding. .Sh RETURN VALUES Upon successful completion, .Fn fork and .Fn _Fork return a value of 0 to the child process and return the process ID of the child process to the parent process. Otherwise, a value of -1 is returned to the parent process, no child process is created, and the global variable .Va errno is set to indicate the error. .Sh EXAMPLES The following example shows a common pattern of how .Fn fork is used in practice. .Bd -literal -offset indent #include #include #include #include int main(void) { pid_t pid; /* * If child is expected to use stdio(3), state of * the reused io streams must be synchronized between * parent and child, to avoid double output and other * possible issues. */ fflush(stdout); switch (pid = fork()) { case -1: err(1, "Failed to fork"); case 0: printf("Hello from child process!\en"); /* * Since we wrote into stdout, child needs to use * exit(3) and not _exit(2). This causes handlers * registered with atexit(3) to be called twice, * once in parent, and once in the child. If such * behavior is undesirable, consider * terminating child with _exit(2) or _Exit(3). */ exit(0); default: break; } printf("Hello from parent process (child's PID: %d)!\en", pid); return (0); } .Ed .Pp The output of such a program is along the lines of: .Bd -literal -offset indent Hello from parent process (child's PID: 27804)! Hello from child process! .Ed .Sh ERRORS The .Fn fork system call will fail and no child process will be created if: .Bl -tag -width Er .It Bq Er EAGAIN The system-imposed limit on the total number of processes under execution would be exceeded. The limit is given by the .Xr sysctl 3 MIB variable .Dv KERN_MAXPROC . (The limit is actually ten less than this except for the super user). .It Bq Er EAGAIN The user is not the super user, and the system-imposed limit on the total number of processes under execution by a single user would be exceeded. The limit is given by the .Xr sysctl 3 MIB variable .Dv KERN_MAXPROCPERUID . .It Bq Er EAGAIN The user is not the super user, and the soft resource limit corresponding to the .Fa resource argument .Dv RLIMIT_NPROC would be exceeded (see .Xr getrlimit 2 ) . .It Bq Er ENOMEM There is insufficient swap space for the new process. .El .Sh SEE ALSO .Xr execve 2 , .Xr rfork 2 , .Xr setitimer 2 , .Xr setrlimit 2 , .Xr sigaction 2 , .Xr vfork 2 , .Xr wait 2 , .Xr pthread_atfork 3 .Sh HISTORY The .Fn fork function appeared in .At v1 . .Pp The .Fn _Fork function was defined by Austin Group together with the removal of a requirement that the .Fn fork implementation must be async-signal safe. The .Fn _Fork function appeared in -.Fx 14.0 . +.Fx 13.1 . diff --git a/sbin/mount/mntopts.3 b/sbin/mount/mntopts.3 index fe2073c3dc71..2480be2bdc9e 100644 --- a/sbin/mount/mntopts.3 +++ b/sbin/mount/mntopts.3 @@ -1,379 +1,379 @@ .\" Copyright (c) 2023 Marshall Kirk McKusick .\" Copyright (c) 1994 The Regents of the University of California. .\" .\" 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 BY THE AUTHORS 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 AUTHORS 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. .\" .Dd January 19, 2023 .Dt MNTOPTS 3 .Os .Sh NAME .Nm getmntopts , .Nm getmntpoint , .Nm chkdoreload , .Nm build_iovec , .Nm build_iovec_argf , .Nm free_iovec , .Nm checkpath , .Nm rmslashes .Nd "mount point operations" .Sh SYNOPSIS .In mntopts.h .Ft void .Fo getmntopts .Fa "const char *options" "const struct mntopt *mopts" .Fa "int *flagp" "int *altflagp" .Fc .Ft struct statfs * .Fn getmntpoint "const char *name" .Ft int .Fo chkdoreload .Fa "struct statfs *mntp" .Fa "void (*prtmsg)(const char *fmt, ...)" .Fc .Ft void .Fo build_iovec .Fa "struct iovec **iov" "int *iovlen" "const char *name" "void *val" .Fa "size_t len" .Fc .Ft void .Fo build_iovec_argf .Fa "struct iovec **iov" "int *iovlen" "const char *name" .Fa "const char *fmt" "..." .Fc .Ft void .Fn free_iovec "struct iovec **iov" "int *iovlen" .Ft int .Fn checkpath "const char *path" "char *resolved" .Ft void .Fn rmslashes "char *rrpin" "char *rrpout" .Sh DESCRIPTION The .Nm mntopts functions support operations associated with a mount point. For historic reasons are in a file in the sources for the .Xr mount 8 program. Thus, to access them the following lines need to be added to the .Nm Makefile of the program wanting to use them: .Bd -literal SRCS+= getmntopts.c MOUNT= ${SRCTOP}/sbin/mount CFLAGS+= -I${MOUNT} \&.PATH: ${MOUNT} .Ed .Pp The .Fn getmntopts function takes a comma separated option list and a list of valid option names, and computes the bitmask corresponding to the requested set of options. .Pp The string .Fa options is broken down into a sequence of comma separated tokens. Each token is looked up in the table described by .Fa mopts and the bits in the word referenced by either .Fa flagp or .Fa altflagp (depending on the .Va m_altloc field of the option's table entry) are updated. The flag words are not initialized by .Fn getmntopts . The table, .Fa mopts , has the following format: .Bd -literal struct mntopt { char *m_option; /* option name */ int m_inverse; /* is this a negative option, e.g., "dev" */ int m_flag; /* bit to set, e.g., MNT_RDONLY */ int m_altloc; /* non-zero to use altflagp rather than flagp */ }; .Ed .Pp The members of this structure are: .Bl -tag -width m_inverse .It Va m_option the option name, for example .Dq Li suid . .It Va m_inverse tells .Fn getmntopts that the name has the inverse meaning of the bit. For example, .Dq Li suid is the string, whereas the mount flag is .Dv MNT_NOSUID . In this case, the sense of the string and the flag are inverted, so the .Va m_inverse flag should be set. .It Va m_flag the value of the bit to be set or cleared in the flag word when the option is recognized. The bit is set when the option is discovered, but cleared if the option name was preceded by the letters .Dq Li no . The .Va m_inverse flag causes these two operations to be reversed. .It Va m_altloc the bit should be set or cleared in .Fa altflagp rather than .Fa flagp . .El .Pp Each of the user visible .Dv MNT_ flags has a corresponding .Dv MOPT_ macro which defines an appropriate .Vt "struct mntopt" entry. To simplify the program interface and ensure consistency across all programs, a general purpose macro, .Dv MOPT_STDOPTS , is defined which contains an entry for all the generic VFS options. In addition, the macros .Dv MOPT_FORCE and .Dv MOPT_UPDATE exist to enable the .Dv MNT_FORCE and .Dv MNT_UPDATE flags to be set. Finally, the table must be terminated by an entry with a .Dv NULL first element. .Pp The .Fn getmntpoint function takes the pathname of a possible mount point or of a device (with or without .Pa /dev/ prepended to it). If the pathname is a directory or a file, .Fn getmntpoint checks to see if the mount point currently has a filesystem mounted on it. If the pathname is a device, .Fn getmntpoint checks to see if it is currently mounted. If there is an associated mount, a pointer to a .Vt "struct statfs" is returned. The returned result is stored in a static buffer that is over-written each time the .Fn getmntpoint function or the .Xr getmntinfo 3 library routine is called. If no mount is found, NULL is returned. .Pp The .Fn chkdoreload function takes a pointer to a .Vt "struct statfs" . If the filesystem associated with the mount point is mounted read-only, .Fn chkdoreload requests the filesystem to reload all of its metadata from its backing store. The second parameter is the function to call to print an error message if the reload fails. If no error message is desired, a .Dv NULL can be passed as the second argument. The .Fn chkdoreload function returns zero on success or non-zero on failure. .Pp The .Fn build_iovec function adds a parameter to a list of parameters to be passed to the .Xr nmount 2 system call. The parameter list is built up in .Va iov and its length is kept in .Va iovlen . Before the first call to .Fn build_iovec , .Va iov should be set to .Dv NULL and .Va iovlen should be set to 0. The parameter name is passed in .Va name . The value of the parameter name is pointed to by .Va val . The size of the value is passed in .Va len . If the value is a string, a .Va len of -1 is passed to indicate that the length should be determined using .Xr strlen 3 . If the parameter has no value, .Va name should be .Dv NULL and .Va len should be 0. .Pp The .Fn build_iovec_argf function adds a formatted parameter to a list of parameters to be passed to the .Xr nmount 2 system call. The parameter list is built up in .Va iov and its length is kept in .Va iovlen . Before the first call to .Fn build_iovec_argf , .Va iov should be set to .Dv NULL and .Va iovlen should be set to 0. The parameter name is passed in .Va name . The value of the parameter name is described by a format string pointed to by .Va fmt . If the parameter has no value, .Va name should be .Dv NULL . .Pp The .Fn free_iovec function frees the memory in the .Va iov vector of the length specified in .Va iovlen that was previously allocated by the .Fn build_iovec and / or .Fn build_iovec_argf functions. The .Va iov is set to .Dv NULL and the .Va iovlen is set to 0 to indicate that the space has been freed. .Pp The .Fn checkpath function uses .Xr realpath 3 to verify that its .Va path argument is valid and references a directory. The .Fn checkpath function returns zero on success or non-zero on failure. .Pp The .Fn rmslashes function removes all double slashes and trailing slashes from its .Va rrpin pathname parameter and returns the resulting pathname in its .Va rrpout parameter. .Sh EXAMPLES Most commands will use the standard option set. Local file systems which support the .Dv MNT_UPDATE flag, would also have an .Dv MOPT_UPDATE entry. This can be declared and used as follows: .Bd -literal #include "mntopts.h" struct mntopt mopts[] = { MOPT_STDOPTS, MOPT_UPDATE, { NULL } }; ... mntflags = mntaltflags = 0; ... getmntopts(options, mopts, &mntflags, &mntaltflags); ... .Ed .Sh DIAGNOSTICS If the external integer variable .Va getmnt_silent is zero, then the .Fn getmntopts function displays an error message and exits if an unrecognized option is encountered. Otherwise unrecognized options are silently ignored. By default .Va getmnt_silent is zero. .Sh SEE ALSO .Xr err 3 , .Xr mount 8 , .Xr nmount 8 .Sh HISTORY The .Fn getmntopts function appeared in .Bx 4.4 . The .Fn build_iovec , .Fn build_iovec_argf , .Fn free_iovec , .Fn checkpath , and .Fn rmslashes functions were added with .Xr nmount 8 in .Fx 5.0 . The .Fn getmntpoint and .Fn chkdoreload functions were added in -.Fx 14.0 . +.Fx 13.2 . diff --git a/share/man/man4/igc.4 b/share/man/man4/igc.4 index 97b40b6ffb92..f77581edd00b 100644 --- a/share/man/man4/igc.4 +++ b/share/man/man4/igc.4 @@ -1,164 +1,164 @@ .\"- .\" Copyright 2021 Intel Corp .\" Copyright 2021 Rubicon Communications, LLC (Netgate) .\" SPDX-License-Identifier: BSD-3-Clause .\" .Dd May 10, 2021 .Dt IGC 4 .Os .Sh NAME .Nm igc .Nd "Intel Ethernet Controller I225 driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iflib" .Cd "device igc" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent if_igc_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for any PCI Express adapter or LOM (LAN On Motherboard) based on the Intel I225 Multi Gigabit Controller. The driver supports Transmit/Receive checksum offload, Jumbo Frames, MSI/MSI-X, TSO, and RSS. .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 9216 bytes. .Pp This driver version supports VLAN hardware insertion / extraction, and VLAN checksum offload. For information on enabling VLANs, see .Xr ifconfig 8 . The .Nm driver supports the following media types: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm autoselect Enables auto-negotiation for speed and duplex. .It Cm 10baseT/UTP Sets 10Mbps operation. Use the .Cm mediaopt option to select .Cm half-duplex mode. .It Cm 100baseTX Sets 100Mbps operation. Use the .Cm mediaopt option to select .Cm half-duplex mode. .It Cm 1000baseT Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .It Cm 2500baseT Sets 2500Mbps operation. Only .Cm full-duplex mode is supported at this speed. .El .Sh HARDWARE The .Nm driver supports the following models: .Pp .Bl -bullet -compact .It I225-LM .It I225-V .It I225-IT .It I225-K .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.igc.igc_disable_crc_stripping Disable or enable hardware stripping of CRC field. This is mostly useful on BMC/IPMI shared interfaces where stripping the CRC causes remote access over IPMI to fail. Default 0 (enabled). .It Va hw.igc.rx_int_delay This value delays the generation of receive interrupts in units of 1.024 microseconds. The default value is 0, since adapters may hang with this feature being enabled. .It Va hw.igc.rx_abs_int_delay If hw.igc.rx_int_delay is non-zero, this tunable limits the maximum delay in which a receive interrupt is generated. .It Va hw.igc.tx_int_delay This value delays the generation of transmit interrupts in units of 1.024 microseconds. The default value is 64. .It Va hw.igc.tx_abs_int_delay If hw.igc.tx_int_delay is non-zero, this tunable limits the maximum delay in which a transmit interrupt is generated. .It Va hw.igc.sbp Show bad packets when in promiscuous mode. Default is false. .It Va hw.igc.rx_process_limit Maximum number of received packets to process at a time. Default is 100. A value of -1 means unlimited. .It Va hw.igc.eee_setting Disable or enable Energy Efficient Ethernet. Default 1 (disabled). .It Va hw.igc.max_interrupt_rate Maximum device interrupts per second. The default is 8000. .El .Sh DIAGNOSTICS .Bl -diag .It "igc%d: Hardware Initialization Failed" A fatal initialization error has occurred. .It "igc%d: Unable to allocate bus resource: memory" A fatal initialization error has occurred. .It "igc%d: Invalid MAC address" The MAC address programmed into the EEPROM is either empty or a multicast/broadcast address. .El .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr iflib 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in -.Fx 14.0 . +.Fx 13.1 . .Sh AUTHORS .An -nosplit The .Nm was originally written by .An Intel Corporation and converted to the .Xr iflib 4 framework by .An Netgate . diff --git a/share/man/man4/mac_priority.4 b/share/man/man4/mac_priority.4 index 868d027d5233..c63197d5fc29 100644 --- a/share/man/man4/mac_priority.4 +++ b/share/man/man4/mac_priority.4 @@ -1,128 +1,128 @@ .\" Copyright (c) 2021 Florian Walpen .\" .\" 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 BY THE AUTHORS 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 AUTHORS 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. .\" .Dd December 14, 2021 .Dt MAC_PRIORITY 4 .Os .Sh NAME .Nm mac_priority .Nd "policy for scheduling privileges of non-root users" .Sh SYNOPSIS To compile the mac_priority policy into your kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "options MAC" .Cd "options MAC_PRIORITY" .Ed .Pp Alternately, to load the mac_priority policy module at boot time, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "options MAC" .Ed .Pp and in .Xr loader.conf 5 : .Bd -literal -offset indent mac_priority_load="YES" .Ed .Sh DESCRIPTION The .Nm policy grants scheduling privileges based on .Xr group 5 membership. Users or processes in the group .Sq realtime (gid 47) are allowed to run threads and processes with realtime scheduling priority. Users or processes in the group .Sq idletime (gid 48) are allowed to run threads and processes with idle scheduling priority. .Pp With the .Nm realtime policy active, privileged users may use the .Xr rtprio 1 utility to start processes with realtime priority. Privileged applications can promote threads and processes to realtime priority through the .Xr rtprio 2 system calls. .Pp When the idletime policy is active, privileged users may use the .Xr idprio 1 utility to start processes with idle priority. Privileged applications can demote threads and processes to idle priority through the .Xr rtprio 2 system calls. .Ss Privileges Granted The realtime policy grants the following kernel privileges to any process running with the realtime group id: .Bl -inset -offset indent -compact .It Dv PRIV_SCHED_RTPRIO .It Dv PRIV_SCHED_SETPOLICY .El .Pp The kernel privilege granted by the idletime policy is: .Bl -inset -offset indent -compact .It Dv PRIV_SCHED_IDPRIO .El .Ss Runtime Configuration The following .Xr sysctl 8 MIBs are available for fine-tuning this MAC policy. All .Xr sysctl 8 variables can also be set as .Xr loader 8 tunables in .Xr loader.conf 5 . .Bl -tag -width indent .It Va security.mac.priority.realtime Enable the realtime policy. (Default: 1). .It Va security.mac.priority.realtime_gid The numeric gid of the realtime group. (Default: 47). .It Va security.mac.priority.idletime Enable the idletime policy. (Default: 1). .It Va security.mac.priority.idletime_gid The numeric gid of the idletime group. (Default: 48). .El .Sh SEE ALSO .Xr idprio 1 , .Xr rtprio 1 , .Xr rtprio 2 , .Xr mac 4 .Sh HISTORY MAC first appeared in .Fx 5.0 and .Nm first appeared in -.Fx 14.0 . +.Fx 13.1 . diff --git a/share/man/man4/tslog.4 b/share/man/man4/tslog.4 index 40397d14c3e2..e7f69a8d6f3f 100644 --- a/share/man/man4/tslog.4 +++ b/share/man/man4/tslog.4 @@ -1,137 +1,137 @@ .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org> .\" .\" 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 BY THE AUTHOR 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 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. .\" .Dd June 1, 2022 .Dt TSLOG 4 .Os .Sh NAME .Nm tslog .Nd Boot-time event tracing facility .Sh SYNOPSIS To compile this boot-time event tracing facility into the kernel, place the following line in the kernel configuration file: .Bd -ragged -offset indent .Cd "option TSLOG" .Ed .Sh DESCRIPTION .Nm is a boot-time event tracing facility. It is suitable for tracing recursive events based on function entries and exits. Its purpose is to ease pinpointing and reducing the overall .Fx boot time by generating detailed timing information. .Pp .Nm is able to trace the boot loader, kernel initialization, and userland processes. .Pp In userland, it records the following details for each process ID: .Bl -dash .It The timestamp of the .Xr fork 2 which creates the given process ID and the parent process ID. .It The path passed to .Xr execve 2 , if any. .It The first path resolved by .Xr namei 9 , if any. .It The timestamp of the .Xr exit 3 which terminates the process. .El .Sh SYSCTL VARIABLES The following .Xr sysctl 8 variables are available: .Bl -tag -width indent .It Va debug.tslog Dump the .Nm buffer of recorded loader and kernel event timestamps. .It Va debug.tslog_user Dump the .Nm buffer of recorded userland event timestamps. .El .Sh FLAMEGRAPHS The .Nm buffer dumps can be used to generate flamegraphs of the .Fx boot process for visual analysis. See .Lk https://github.com/cperciva/freebsd-boot-profiling for more information. .Sh SEE ALSO .Xr dtrace 1 , .Xr boottrace 4 , .Xr ktr 4 .Sh HISTORY .Nm first appeared in .Fx 12.0 . Support for tracing boot loaders and userland process was added in -.Fx 14.0 . +.Fx 13.2 . .Ss TSLOG vs. Boottrace .Nm is oriented towards system developers while .Xr boottrace 4 is meant to be easy to use by system administrators. Both facilities provide an overview of timing and resource usage of the boot process. .Ss TSLOG vs. DTrace .Xr dtrace 1 is not always the right tool for profiling early kernel initialization. The reason is it requires some kernel subroutines which are not yet available early in the boot process, e.g.: traps, memory allocation, or thread scheduling. .Nm depends on fewer kernel subroutines than .Xr dtrace 1 and because of that can trace early kernel initialization. .Ss TSLOG vs. KTR .Xr ktr 4 has a couple of limitations which prevent it from being able to run at the start of the boot process. In contrast, .Nm is designed for logging timestamped events for boot profiling. .Sh AUTHORS .An -nosplit .Nm was written by .An Colin Percival Aq Mt cperciva@FreeBSD.org . .Pp This manual page was written by .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/share/man/man7/growfs.7 b/share/man/man7/growfs.7 index 241c12cd28f1..43648d8d9f2b 100644 --- a/share/man/man7/growfs.7 +++ b/share/man/man7/growfs.7 @@ -1,140 +1,140 @@ .\" Copyright 2014 John-Mark Gurney .\" 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 BY THE AUTHOR 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 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. .\" .Dd November 22, 2022 .Dt GROWFS 7 .Os .Sh NAME .Nm growfs , .Nm growfs_fstab .Nd start up scripts to grow the root file system and add swap .Sh DESCRIPTION The .Nm script normally runs at the first boot after system installation. If the boot disk is larger than the root file system and boot partitions, and the root file system is in the last partition, .Nm can expand the root file system. It can also add a swap partition, with a default size of 10% of the boot disk. Swap is limited to twice the memory size up to 4 GB, 8 GB up to 8 GB of memory, and memory size over 8 GB. It is also limited to the .Xr sysctl 8 value of .Li vm.swap_maxpages divided by 2. By default, no swap partition is created if an existing swap partition is found or is listed in .Pa /etc/fstab , or the disk is under 15 GB. The .Nm growfs_fstab script adds any new swap partition to .Pa /etc/fstab after the root file system is made writable, and enables its use as a dump partition if the .Va dumpdev variable from .Xr rc.conf 5 is set to .Li AUTO . .Pp The following options in .Pa /etc/rc.conf control the behavior of .Nm : .Bl -tag -width ".Va growfs_swap_size" -offset indent .It Va growfs_enable .Pq Dq Li NO If set to .Dq Li YES , the first time the machine boots, the root file system will be automatically expanded, if possible, to fill up all available space after it, after optionally adding a swap device at the end. .It Va growfs_swap_size .Pq Dq Li \& If set to .Dq Li 0 , the addition of a swap partition is disabled. An empty value .Pq Dq Li \& allows the creation of a swap partition with the default size. If set to another value, the swap partition will be created with the specified size in bytes, even if another swap partition is detected. .El .Pp A setting for .Va growfs_swap_size can be set in the kernel environment, in which case it overrides the value from .Pa /etc/rc.conf . .Pp To expand the root file system without rebooting, run the following command: .Dl % /etc/rc.d/growfs onestart In addition, if a swap partition is added, run the command: .Dl % /etc/rc.d/growfs_fstab onestart Note that if a disk is expanded again, and if the root file system had previously been expanded and a swap partition added, it is necessary to delete the swap partition before this procedure in order to expand the root file system to the new size. A new swap partition can be created during the expansion. .Sh IMPLEMENTATION NOTES The .Nm script only attempts to expand the root file system, and free space must be available immediately after the root partition. It is normally used on images that have a single file system. The script requires that .Xr awk 1 be present and in the path. This usually means that .Pa /usr must be available prior to running the script. .Sh FILES .Bl -tag -compact -width Pa .It Pa /etc/fstab .It Pa /etc/rc.conf .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr fstab 5 , .Xr rc.conf 5 , .Xr growfs 8 , .Xr zpool 8 .Sh HISTORY The .Nm manual page first appeared in .Fx 10.1 . The ability to add a swap partition was added in -.Fx 14.0 . +.Fx 13.2 . .Sh AUTHORS The man page and script were written by .An John-Mark Gurney Aq Mt jmg@FreeBSD.org . The ability to create a swap partition was added by .An Michael Karels Aq Mt karels@FreeBSD.org . diff --git a/share/man/man9/kasan.9 b/share/man/man9/kasan.9 index 209fbb06506c..77d7e8f46aa8 100644 --- a/share/man/man9/kasan.9 +++ b/share/man/man9/kasan.9 @@ -1,185 +1,185 @@ .\"- .\" Copyright (c) 2021 The FreeBSD Foundation .\" .\" This documentation was written by Mark Johnston under sponsorship from .\" the FreeBSD Foundation. .\" .\" 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 BY THE AUTHOR 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 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. .\" .Dd October 13, 2023 .Dt KASAN 9 .Os .Sh NAME .Nm KASAN .Nd Kernel Address SANitizer .Sh SYNOPSIS The .Pa GENERIC-KASAN kernel configuration can be used to compile a KASAN-enabled kernel using .Pa GENERIC as a base configuration. Alternately, to compile KASAN into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "options KASAN" .Ed .Pp .In sys/asan.h .Ft void .Fn kasan_mark "const void *addr" "size_t size" "size_t redzsize" "uint8_t code" .Sh DESCRIPTION .Nm is a subsystem which leverages compiler instrumentation to detect invalid memory accesses in the kernel. Currently it is implemented on the amd64 and arm64 platforms. .Pp When .Nm is compiled into the kernel, the compiler is configured to emit function calls upon every memory access. The functions are implemented by .Nm and permit run-time detection of several types of bugs including use-after-frees, double frees and frees of invalid pointers, and out-of-bounds accesses. These protections apply to memory allocated by .Xr uma 9 , .Xr malloc 9 and related functions, and .Fn kmem_malloc and related functions, as well as global variables and kernel stacks. .Nm is conservative and will not detect all instances of these types of bugs. Memory accesses through the kernel map are sanitized, but accesses via the direct map are not. When .Nm is configured, the kernel aims to minimize its use of the direct map. .Sh IMPLEMENTATION NOTES .Nm is implemented using compiler instrumentation and a kernel runtime. When a kernel is built with the KASAN option enabled, the compiler inserts function calls before most memory accesses in the generated code. The runtime implements the corresponding functions, which decide whether a given access is valid. If not, the runtime prints a warning or panics the kernel, depending on the value of the .Sy debug.kasan.panic_on_violation sysctl/tunable. .Pp The .Nm runtime in a KASAN-configured kernel can be disabled by setting the loader tunable .Sy debug.kasan.disable=1 . .Pp The .Nm runtime works by maintaining a shadow map for the kernel map. There exists a linear mapping between addresses in the kernel map and addresses in the shadow map. The shadow map is used to store information about the current state of allocations from the kernel map. For example, when a buffer is returned by .Xr malloc 9 , the corresponding region of the shadow map is marked to indicate that the buffer is valid. When it is freed, the shadow map is updated to mark the buffer as invalid. Accesses to the buffer are intercepted by the .Nm runtime and validated using the contents of the shadow map. .Pp Upon booting, all kernel memory is marked as valid. Kernel allocators must mark cached but free buffers as invalid, and must mark them valid before freeing the kernel virtual address range. This slightly reduces the effectiveness of .Nm but simplifies its maintenance and integration into the kernel. .Pp Updates to the shadow map are performed by calling .Fn kasan_mark . Parameter .Fa addr is the address of the buffer whose shadow is to be updated, .Fa size is the usable size of the buffer, and .Fa redzsize is the full size of the buffer allocated from lower layers of the system. .Fa redzsize must be greater than or equal to .Fa size . In some cases kernel allocators will return a buffer larger than that requested by the consumer; the unused space at the end is referred to as a red zone and is always marked as invalid. .Fa code allows the caller to specify an identifier used when marking a buffer as invalid. The identifier is included in any reports generated by .Nm and helps identify the source of the invalid access. For instance, when an item is freed to a .Xr uma 9 zone, the item is marked with .Dv KASAN_UMA_FREED . See .In sys/asan.h for the available identifiers. If the entire buffer is to be marked valid, i.e., .Fa size and .Fa redzsize are equal, .Fa code should be 0. .Sh SEE ALSO .Xr build 7 , .Xr KMSAN 9 , .Xr malloc 9 , .Xr memguard 9 , .Xr redzone 9 , .Xr uma 9 .Sh HISTORY .Nm was ported from .Nx and first appeared in -.Fx 14.0 . +.Fx 13.1 . .Sh BUGS Accesses to kernel memory outside of the kernel map are ignored by the .Nm runtime. When .Nm is configured, the kernel memory allocators are configured to use the kernel map, but some uses of the direct map remain. For example, on amd64 and arm64, accesses to page table pages are not tracked. .Pp Some kernel memory allocators explicitly permit accesses after an object has been freed. These cannot be sanitized by .Nm . For example, memory from all .Xr uma 9 zones initialized with the .Dv UMA_ZONE_NOFREE flag are not sanitized.