Index: stable/9/bin/pwait/pwait.1 =================================================================== --- stable/9/bin/pwait/pwait.1 (revision 237215) +++ stable/9/bin/pwait/pwait.1 (revision 237216) @@ -1,78 +1,78 @@ .\" .\" Copyright (c) 2004-2009, Jilles Tjoelker .\" 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 COPYRIGHT HOLDERS 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 .\" COPYRIGHT OWNER 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 November 1, 2009 .Dt PWAIT 1 .Os .Sh NAME .Nm pwait .Nd wait for processes to terminate .Sh SYNOPSIS .Nm .Op Fl v .Ar pid \&... .Sh DESCRIPTION The .Nm -utility will wait until each of the given processes has terminated. +utility will wait until each of the given processes has terminated. .Pp The following option is available: .Bl -tag -width indent .It Fl v Print the exit status when each process terminates. .El .Sh DIAGNOSTICS .Pp The .Nm utility returns 0 on success, and >0 if an error occurs. .Pp Invalid pids elicit a warning message but are otherwise ignored. .Sh SEE ALSO .Xr kill 1 , .Xr pkill 1 , .Xr ps 1 , .Xr wait 1 , .Xr kqueue 2 .Sh NOTES .Nm is not a substitute for the .Xr wait 1 builtin as it will not clean up any zombies or state in the parent process. .Sh HISTORY A .Nm command first appeared in SunOS 5.8. Index: stable/9/bin/pwait =================================================================== --- stable/9/bin/pwait (revision 237215) +++ stable/9/bin/pwait (revision 237216) Property changes on: stable/9/bin/pwait ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/head_mfi/bin/pwait:r233621 Merged /vendor/resolver/dist/bin/pwait:r1540-186085 Merged /projects/quota64/bin/pwait:r184125-207707 Merged /head/bin/pwait:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234782,235122,235297,235316 Merged /projects/largeSMP/bin/pwait:r221273-222812,222815-223757 Index: stable/9/bin/setfacl/setfacl.1 =================================================================== --- stable/9/bin/setfacl/setfacl.1 (revision 237215) +++ stable/9/bin/setfacl/setfacl.1 (revision 237216) @@ -1,480 +1,480 @@ .\"- .\" Copyright (c) 2001 Chris D. Faulhaber .\" Copyright (c) 2011 Edward Tomasz Napierała .\" 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. .\" .\" $FreeBSD$ .\" .Dd April 9, 2011 .Dt SETFACL 1 .Os .Sh NAME .Nm setfacl .Nd set ACL information .Sh SYNOPSIS .Nm .Op Fl bdhkn .Op Fl a Ar position entries .Op Fl m Ar entries .Op Fl M Ar file .Op Fl x Ar entries | position .Op Fl X Ar file .Op Ar .Sh DESCRIPTION The .Nm utility sets discretionary access control information on the specified file(s). If no files are specified, or the list consists of the only .Sq Fl , the file names are taken from the standard input. .Pp The following options are available: .Bl -tag -width indent .It Fl a Ar position entries Modify the ACL on the specified files by inserting new ACL entries specified in .Ar entries , starting at position .Ar position , counting from zero. This option is only applicable to NFSv4 ACLs. .It Fl b Remove all ACL entries except for the three required entries (POSIX.1e ACLs) or six "canonical" entries (NFSv4 ACLs). If the POSIX.1e ACL contains a .Dq Li mask entry, the permissions of the .Dq Li group entry in the resulting ACL will be set to the permission associated with both the .Dq Li group and .Dq Li mask entries of the current ACL. .It Fl d The operations apply to the default ACL entries instead of access ACL entries. Currently only directories may have default ACL's. This option is not applicable to NFSv4 ACLs. .It Fl h If the target of the operation is a symbolic link, perform the operation on the symbolic link itself, rather than following the link. .It Fl k Delete any default ACL entries on the specified files. It is not considered an error if the specified files do not have any default ACL entries. An error will be reported if any of the specified files cannot have a default entry (i.e.\& non-directories). This option is not applicable to NFSv4 ACLs. .It Fl m Ar entries Modify the ACL entries on the specified files by adding new entries and modifying existing ACL entries with the ACL entries specified in .Ar entries . .It Fl M Ar file Modify the ACL entries on the specified files by adding new ACL entries and modifying existing ACL entries with the ACL entries specified in the file .Ar file . If .Ar file is .Fl , the input is taken from stdin. .It Fl n Do not recalculate the permissions associated with the ACL mask entry. This option is not applicable to NFSv4 ACLs. .It Fl x Ar entries | position If .Ar entries is specified, remove the ACL entries specified there from the access or default ACL of the specified files. Otherwise, remove entry at index .Ar position , counting from zero. .It Fl X Ar file Remove the ACL entries specified in the file .Ar file from the access or default ACL of the specified files. .El .Pp The above options are evaluated in the order specified on the command-line. .Sh POSIX.1e ACL ENTRIES A POSIX.1E ACL entry contains three colon-separated fields: an ACL tag, an ACL qualifier, and discretionary access permissions: .Bl -tag -width indent .It Ar "ACL tag" The ACL tag specifies the ACL entry type and consists of one of the following: .Dq Li user or .Ql u specifying the access granted to the owner of the file or a specified user; .Dq Li group or .Ql g specifying the access granted to the file owning group or a specified group; .Dq Li other or .Ql o specifying the access granted to any process that does not match any user or group ACL entry; .Dq Li mask or .Ql m specifying the maximum access granted to any ACL entry except the .Dq Li user ACL entry for the file owner and the .Dq Li other ACL entry. .It Ar "ACL qualifier" The ACL qualifier field describes the user or group associated with the ACL entry. It may consist of one of the following: uid or user name, gid or group name, or empty. For .Dq Li user ACL entries, an empty field specifies access granted to the file owner. For .Dq Li group ACL entries, an empty field specifies access granted to the file owning group. .Dq Li mask and .Dq Li other ACL entries do not use this field. .It Ar "access permissions" The access permissions field contains up to one of each of the following: .Ql r , .Ql w , and .Ql x to set read, write, and execute permissions, respectively. Each of these may be excluded or replaced with a .Ql - character to indicate no access. .El .Pp A .Dq Li mask ACL entry is required on a file with any ACL entries other than the default .Dq Li user , .Dq Li group , and .Dq Li other ACL entries. If the .Fl n option is not specified and no .Dq Li mask ACL entry was specified, the .Nm utility will apply a .Dq Li mask ACL entry consisting of the union of the permissions associated with all .Dq Li group ACL entries in the resulting ACL. .Pp Traditional POSIX interfaces acting on file system object modes have modified semantics in the presence of POSIX.1e extended ACLs. When a mask entry is present on the access ACL of an object, the mask entry is substituted for the group bits; this occurs in programs such as .Xr stat 1 or .Xr ls 1 . When the mode is modified on an object that has a mask entry, the changes applied to the group bits will actually be applied to the mask entry. These semantics provide for greater application compatibility: applications modifying the mode instead of the ACL will see conservative behavior, limiting the effective rights granted by all of the additional user and group entries; this occurs in programs such as .Xr chmod 1 . .Pp ACL entries applied from a file using the .Fl M or .Fl X options shall be of the following form: one ACL entry per line, as previously specified; whitespace is ignored; any text after a .Ql # is ignored (comments). .Pp When POSIX.1e ACL entries are evaluated, the access check algorithm checks the ACL entries in the following order: file owner, .Dq Li user ACL entries, file owning group, .Dq Li group ACL entries, and .Dq Li other ACL entry. .Pp Multiple ACL entries specified on the command line are separated by commas. .Pp It is possible for files and directories to inherit ACL entries from their parent directory. This is accomplished through the use of the default ACL. It should be noted that before you can specify a default ACL, the mandatory ACL entries for user, group, other and mask must be set. For more details see the examples below. Default ACLs can be created by using .Fl d . .Sh NFSv4 ACL ENTRIES An NFSv4 ACL entry contains four or five colon-separated fields: an ACL tag, an ACL qualifier (only for .Dq Li user and .Dq Li group tags), discretionary access permissions, ACL inheritance flags, and ACL type: .Bl -tag -width indent .It Ar "ACL tag" The ACL tag specifies the ACL entry type and consists of one of the following: .Dq Li user or .Ql u specifying the access granted to the specified user; .Dq Li group or .Ql g specifying the access granted to the specified group; .Dq Li owner@ specifying the access granted to the owner of the file; .Dq Li group@ specifying the access granted to the file owning group; .Dq Li everyone@ specifying everyone. Note that .Dq Li everyone@ is not the same as traditional Unix .Dq Li other - it means, literally, everyone, including file owner and owning group. .It Ar "ACL qualifier" The ACL qualifier field describes the user or group associated with the ACL entry. It may consist of one of the following: uid or user name, or gid or group name. In entries whose tag type is -one of +one of .Dq Li owner@ , .Dq Li group@ , or .Dq Li everyone@ , this field is omitted altogether, including the trailing comma. .It Ar "access permissions" Access permissions may be specified in either short or long form. Short and long forms may not be mixed. Permissions in long form are separated by the .Ql / character; in short form, they are concatenated together. Valid permissions are: .Bl -tag -width ".Dv modify_set" .It Short Long .It r read_data .It w write_data .It x execute .It p append_data .It d delete_child .It D delete .It a read_attributes .It A write_attributes .It R read_xattr .It W write_xattr .It c read_acl .It C write_acl .It o write_owner .It S synchronize .El .Pp In addition, the following permission sets may be used: .Bl -tag -width ".Dv modify_set" .It Set Permissions .It full_set all permissions, as shown above .It modify_set all permissions except write_acl and write_owner .It read_set read_data, read_attributes, read_xattr and read_acl .It write_set write_data, append_data, write_attributes and write_xattr .El .It Ar "ACL inheritance flags" Inheritance flags may be specified in either short or long form. Short and long forms may not be mixed. Access flags in long form are separated by the .Ql / character; in short form, they are concatenated together. Valid inheritance flags are: .Bl -tag -width ".Dv short" .It Short Long .It f file_inherit .It d dir_inherit .It i inherit_only .It n no_propagate .El .Pp Inheritance flags may be only set on directories. .It Ar "ACL type" The ACL type field is either .Dq Li allow or .Dq Li deny . .El .Pp ACL entries applied from a file using the .Fl M or .Fl X options shall be of the following form: one ACL entry per line, as previously specified; whitespace is ignored; any text after a .Ql # is ignored (comments). .Pp NFSv4 ACL entries are evaluated in their visible order. .Pp Multiple ACL entries specified on the command line are separated by commas. .Sh EXIT STATUS .Ex -std .Sh EXAMPLES .Dl setfacl -d -m u::rwx,g::rx,o::rx,mask::rwx dir .Dl setfacl -d -m g:admins:rwx dir .Pp The first command sets the mandatory elements of the POSIX.1e default ACL. The second command specifies that users in group admins can have read, write, and execute permissions for directory named "dir". It should be noted that any files or directories created underneath "dir" will inherit these default ACLs upon creation. .Pp .Dl setfacl -m u::rwx,g:mail:rw file .Pp Sets read, write, and execute permissions for the .Pa file owner's POSIX.1e ACL entry and read and write permissions for group mail on .Pa file . .Pp .Dl setfacl -m owner@:rwxp::allow,g:mail:rwp::allow file .Pp Semantically equal to the example above, but for NFSv4 ACL. .Pp .Dl setfacl -M file1 file2 .Pp Sets/updates the ACL entries contained in .Pa file1 on .Pa file2 . .Pp .Dl setfacl -x g:mail:rw file .Pp Remove the group mail POSIX.1e ACL entry containing read/write permissions from .Pa file . .Pp .Dl setfacl -x0 file .Pp Remove the first entry from the NFSv4 ACL from .Pa file . .Pp .Dl setfacl -bn file .Pp Remove all .Dq Li access ACL entries except for the three required from .Pa file . .Pp .Dl getfacl file1 | setfacl -b -n -M - file2 .Pp Copy ACL entries from .Pa file1 to .Pa file2 . .Sh SEE ALSO .Xr getfacl 1 , .Xr acl 3 , .Xr getextattr 8 , .Xr setextattr 8 , .Xr acl 9 , .Xr extattr 9 .Sh STANDARDS The .Nm utility is expected to be .Tn IEEE Std 1003.2c compliant. .Sh HISTORY Extended Attribute and Access Control List support was developed as part of the .Tn TrustedBSD Project and introduced in .Fx 5.0 . NFSv4 ACL support was introduced in .Fx 8.1 . .Sh AUTHORS .An -nosplit The .Nm utility was written by .An Chris D. Faulhaber Aq jedgar@fxp.org . NFSv4 ACL support was implemented by .An Edward Tomasz Napierala Aq trasz@FreeBSD.org . Index: stable/9/bin/setfacl =================================================================== --- stable/9/bin/setfacl (revision 237215) +++ stable/9/bin/setfacl (revision 237216) Property changes on: stable/9/bin/setfacl ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /vendor/resolver/dist/bin/setfacl:r1540-186085 Merged /projects/quota64/bin/setfacl:r184125-207707 Merged /projects/largeSMP/bin/setfacl:r221273-222812,222815-223757 Merged /head/bin/setfacl:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234782,235122,235297,235316 Merged /projects/head_mfi/bin/setfacl:r233621 Index: stable/9/bin/sh/sh.1 =================================================================== --- stable/9/bin/sh/sh.1 (revision 237215) +++ stable/9/bin/sh/sh.1 (revision 237216) @@ -1,2722 +1,2722 @@ .\"- .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Kenneth Almquist. .\" .\" 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. .\" 4. 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. .\" .\" from: @(#)sh.1 8.6 (Berkeley) 5/4/95 .\" $FreeBSD$ .\" .Dd November 5, 2011 .Dt SH 1 .Os .Sh NAME .Nm sh .Nd command interpreter (shell) .Sh SYNOPSIS .Nm .Op Fl /+abCEefIimnPpTuVvx .Op Fl /+o Ar longname .Oo .Ar script .Op Ar arg ... .Oc .Nm .Op Fl /+abCEefIimnPpTuVvx .Op Fl /+o Ar longname .Fl c Ar string .Oo .Ar name .Op Ar arg ... .Oc .Nm .Op Fl /+abCEefIimnPpTuVvx .Op Fl /+o Ar longname .Fl s .Op Ar arg ... .Sh DESCRIPTION The .Nm utility is the standard command interpreter for the system. The current version of .Nm is close to the .St -p1003.1 specification for the shell. It only supports features designated by .Tn POSIX , plus a few Berkeley extensions. This man page is not intended to be a tutorial nor a complete specification of the shell. .Ss Overview The shell is a command that reads lines from either a file or the terminal, interprets them, and generally executes other commands. It is the program that is started when a user logs into the system, although a user can select a different shell with the .Xr chsh 1 command. The shell implements a language that has flow control constructs, a macro facility that provides a variety of features in addition to data storage, along with built-in history and line editing capabilities. It incorporates many features to aid interactive use and has the advantage that the interpretative language is common to both interactive and non-interactive use (shell scripts). That is, commands can be typed directly to the running shell or can be put into a file, which can be executed directly by the shell. .Ss Invocation .\" .\" XXX This next sentence is incredibly confusing. .\" If no arguments are present and if the standard input of the shell is connected to a terminal (or if the .Fl i option is set), the shell is considered an interactive shell. An interactive shell generally prompts before each command and handles programming and command errors differently (as described below). When first starting, the shell inspects argument 0, and if it begins with a dash .Pq Ql - , the shell is also considered a login shell. This is normally done automatically by the system when the user first logs in. A login shell first reads commands from the files .Pa /etc/profile and then .Pa .profile in a user's home directory, if they exist. If the environment variable .Ev ENV is set on entry to a shell, or is set in the .Pa .profile of a login shell, the shell then subjects its value to parameter expansion and arithmetic expansion and reads commands from the named file. Therefore, a user should place commands that are to be executed only at login time in the .Pa .profile file, and commands that are executed for every shell inside the .Ev ENV file. The user can set the .Ev ENV variable to some file by placing the following line in the file .Pa .profile in the home directory, substituting for .Pa .shinit the filename desired: .Pp .Dl "ENV=$HOME/.shinit; export ENV" .Pp The first non-option argument specified on the command line will be treated as the name of a file from which to read commands (a shell script), and the remaining arguments are set as the positional parameters of the shell .Li ( $1 , $2 , etc.). Otherwise, the shell reads commands from its standard input. .Pp Unlike older versions of .Nm the .Ev ENV script is only sourced on invocation of interactive shells. This closes a well-known, and sometimes easily exploitable security hole related to poorly thought out .Ev ENV scripts. .Ss Argument List Processing All of the single letter options to .Nm have a corresponding long name, with the exception of .Fl c and .Fl /+o . These long names are provided next to the single letter options in the descriptions below. The long name for an option may be specified as an argument to the .Fl /+o option of .Nm . Once the shell is running, the long name for an option may be specified as an argument to the .Fl /+o option of the .Ic set built-in command (described later in the section called .Sx Built-in Commands ) . Introducing an option with a dash .Pq Ql - enables the option, while using a plus .Pq Ql + disables the option. A .Dq Li -- or plain .Ql - will stop option processing and will force the remaining words on the command line to be treated as arguments. The .Fl /+o and .Fl c options do not have long names. They take arguments and are described after the single letter options. .Bl -tag -width indent .It Fl a Li allexport Flag variables for export when assignments are made to them. .It Fl b Li notify Enable asynchronous notification of background job completion. (UNIMPLEMENTED) .It Fl C Li noclobber Do not overwrite existing files with .Ql > . .It Fl E Li emacs Enable the built-in .Xr emacs 1 command line editor (disables the .Fl V option if it has been set; set automatically when interactive on terminals). .It Fl e Li errexit Exit immediately if any untested command fails in non-interactive mode. The exit status of a command is considered to be explicitly tested if the command is part of the list used to control an .Ic if , elif , while , or .Ic until ; if the command is the left hand operand of an .Dq Li && or .Dq Li || operator; or if the command is a pipeline preceded by the .Ic !\& operator. If a shell function is executed and its exit status is explicitly tested, all commands of the function are considered to be tested as well. .It Fl f Li noglob Disable pathname expansion. .It Fl h Li trackall A do-nothing option for .Tn POSIX compliance. .It Fl I Li ignoreeof Ignore .Dv EOF Ap s from input when in interactive mode. .It Fl i Li interactive Force the shell to behave interactively. .It Fl m Li monitor Turn on job control (set automatically when interactive). .It Fl n Li noexec If not interactive, read commands but do not execute them. This is useful for checking the syntax of shell scripts. .It Fl P Li physical Change the default for the .Ic cd and .Ic pwd commands from .Fl L (logical directory layout) to .Fl P (physical directory layout). .It Fl p Li privileged Turn on privileged mode. This mode is enabled on startup if either the effective user or group ID is not equal to the real user or group ID. Turning this mode off sets the effective user and group IDs to the real user and group IDs. When this mode is enabled for interactive shells, the file .Pa /etc/suid_profile is sourced instead of .Pa ~/.profile after .Pa /etc/profile is sourced, and the contents of the .Ev ENV variable are ignored. .It Fl s Li stdin Read commands from standard input (set automatically if no file arguments are present). This option has no effect when set after the shell has already started running (i.e., when set with the .Ic set command). .It Fl T Li trapsasync When waiting for a child, execute traps immediately. If this option is not set, traps are executed after the child exits, as specified in .St -p1003.2 . This nonstandard option is useful for putting guarding shells around children that block signals. The surrounding shell may kill the child or it may just return control to the tty and leave the child alone, like this: .Bd -literal -offset indent sh -T -c "trap 'exit 1' 2 ; some-blocking-program" .Ed .It Fl u Li nounset Write a message to standard error when attempting to expand a variable, a positional parameter or the special parameter .Va \&! that is not set, and if the shell is not interactive, exit immediately. .It Fl V Li vi Enable the built-in .Xr vi 1 command line editor (disables .Fl E if it has been set). .It Fl v Li verbose The shell writes its input to standard error as it is read. Useful for debugging. .It Fl x Li xtrace Write each command (preceded by the value of the .Va PS4 variable subjected to parameter expansion and arithmetic expansion) to standard error before it is executed. Useful for debugging. .El .Pp The .Fl c option causes the commands to be read from the .Ar string operand instead of from the standard input. Keep in mind that this option only accepts a single string as its argument, hence multi-word strings must be quoted. .Pp The .Fl /+o option takes as its only argument the long name of an option to be enabled or disabled. For example, the following two invocations of .Nm both enable the built-in .Xr emacs 1 command line editor: .Bd -literal -offset indent set -E set -o emacs .Ed .Pp If used without an argument, the .Fl o option displays the current option settings in a human-readable format. If .Cm +o is used without an argument, the current option settings are output in a format suitable for re-input into the shell. .Ss Lexical Structure The shell reads input in terms of lines from a file and breaks it up into words at whitespace (blanks and tabs), and at certain sequences of characters called .Dq operators , which are special to the shell. There are two types of operators: control operators and redirection operators (their meaning is discussed later). The following is a list of valid operators: .Bl -tag -width indent .It Control operators: .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact .It Li & Ta Li && Ta Li ( Ta Li ) Ta Li \en .It Li ;; Ta Li ;& Ta Li ; Ta Li | Ta Li || .El .It Redirection operators: .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact .It Li < Ta Li > Ta Li << Ta Li >> Ta Li <> .It Li <& Ta Li >& Ta Li <<- Ta Li >| .El .El .Pp The character .Ql # introduces a comment if used at the beginning of a word. The word starting with .Ql # and the rest of the line are ignored. .Pp .Tn ASCII .Dv NUL characters (character code 0) are not allowed in shell input. .Ss Quoting Quoting is used to remove the special meaning of certain characters or words to the shell, such as operators, whitespace, keywords, or alias names. .Pp There are four types of quoting: matched single quotes, dollar-single quotes, matched double quotes, and backslash. .Bl -tag -width indent .It Single Quotes Enclosing characters in single quotes preserves the literal meaning of all the characters (except single quotes, making it impossible to put single-quotes in a single-quoted string). .It Dollar-Single Quotes Enclosing characters between .Li $' and .Li ' preserves the literal meaning of all characters except backslashes and single quotes. A backslash introduces a C-style escape sequence: .Bl -tag -width xUnnnnnnnn .It \ea Alert (ring the terminal bell) .It \eb Backspace .It \ec Ns Ar c The control character denoted by .Li ^ Ns Ar c in .Xr stty 1 . If .Ar c is a backslash, it must be doubled. .It \ee The ESC character .Tn ( ASCII 0x1b) .It \ef Formfeed .It \en Newline .It \er Carriage return .It \et Horizontal tab .It \ev Vertical tab .It \e\e Literal backslash .It \e\&' Literal single-quote .It \e\&" Literal double-quote .It \e Ns Ar nnn The byte whose octal value is .Ar nnn (one to three digits) .It \ex Ns Ar nn The byte whose hexadecimal value is .Ar nn (one or more digits only the last two of which are used) .It \eu Ns Ar nnnn The Unicode code point .Ar nnnn (four hexadecimal digits) .It \eU Ns Ar nnnnnnnn The Unicode code point .Ar nnnnnnnn (eight hexadecimal digits) .El .Pp The sequences for Unicode code points are currently only useful with UTF-8 locales. They reject code point 0 and UTF-16 surrogates. .Pp If an escape sequence would produce a byte with value 0, that byte and the rest of the string until the matching single-quote are ignored. .Pp Any other string starting with a backslash is an error. .It Double Quotes Enclosing characters within double quotes preserves the literal meaning of all characters except dollar sign .Pq Ql $ , backquote .Pq Ql ` , and backslash .Pq Ql \e . The backslash inside double quotes is historically weird. It remains literal unless it precedes the following characters, which it serves to quote: .Bl -column "XXX" "XXX" "XXX" "XXX" "XXX" -offset center -compact .It Li $ Ta Li ` Ta Li \&" Ta Li \e\ Ta Li \en .El .It Backslash A backslash preserves the literal meaning of the following character, with the exception of the newline character .Pq Ql \en . A backslash preceding a newline is treated as a line continuation. .El .Ss Keywords Keywords or reserved words are words that have special meaning to the shell and are recognized at the beginning of a line and after a control operator. The following are keywords: .Bl -column "doneXX" "elifXX" "elseXX" "untilXX" "whileX" -offset center .It Li \&! Ta { Ta } Ta Ic case Ta Ic do .It Ic done Ta Ic elif Ta Ic else Ta Ic esac Ta Ic fi .It Ic for Ta Ic if Ta Ic then Ta Ic until Ta Ic while .El .Ss Aliases An alias is a name and corresponding value set using the .Ic alias built-in command. Wherever the command word of a simple command may occur, and after checking for keywords if a keyword may occur, the shell checks the word to see if it matches an alias. If it does, it replaces it in the input stream with its value. For example, if there is an alias called .Dq Li lf with the value .Dq Li "ls -F" , then the input .Pp .Dl "lf foobar" .Pp would become .Pp .Dl "ls -F foobar" .Pp Aliases provide a convenient way for naive users to create shorthands for commands without having to learn how to create functions with arguments. Using aliases in scripts is discouraged because the command that defines them must be executed before the code that uses them is parsed. This is fragile and not portable. .Pp An alias name may be escaped in a command line, so that it is not replaced by its alias value, by using quoting characters within or adjacent to the alias name. This is most often done by prefixing an alias name with a backslash to execute a function, built-in, or normal program with the same name. See the .Sx Quoting subsection. .Ss Commands The shell interprets the words it reads according to a language, the specification of which is outside the scope of this man page (refer to the BNF in the .St -p1003.2 document). Essentially though, a line is read and if the first word of the line (or after a control operator) is not a keyword, then the shell has recognized a simple command. Otherwise, a complex command or some other special construct may have been recognized. .Ss Simple Commands If a simple command has been recognized, the shell performs the following actions: .Bl -enum .It Leading words of the form .Dq Li name=value are stripped off and assigned to the environment of the simple command. Redirection operators and their arguments (as described below) are stripped off and saved for processing. .It The remaining words are expanded as described in the section called .Sx Word Expansions , and the first remaining word is considered the command name and the command is located. The remaining words are considered the arguments of the command. If no command name resulted, then the .Dq Li name=value variable assignments recognized in 1) affect the current shell. .It Redirections are performed as described in the next section. .El .Ss Redirections Redirections are used to change where a command reads its input or sends its output. In general, redirections open, close, or duplicate an existing reference to a file. The overall format used for redirection is: .Pp .D1 Oo Ar n Oc Ar redir-op file .Pp The .Ar redir-op is one of the redirection operators mentioned previously. The following gives some examples of how these operators can be used. Note that stdin and stdout are commonly used abbreviations for standard input and standard output respectively. .Bl -tag -width "1234567890XX" -offset indent .It Oo Ar n Oc Ns Li > Ar file redirect stdout (or file descriptor .Ar n ) to .Ar file .It Oo Ar n Oc Ns Li >| Ar file same as above, but override the .Fl C option .It Oo Ar n Oc Ns Li >> Ar file append stdout (or file descriptor .Ar n ) to .Ar file .It Oo Ar n Oc Ns Li < Ar file redirect stdin (or file descriptor .Ar n ) from .Ar file .It Oo Ar n Oc Ns Li <> Ar file redirect stdin (or file descriptor .Ar n ) to and from .Ar file .It Oo Ar n1 Oc Ns Li <& Ns Ar n2 duplicate stdin (or file descriptor .Ar n1 ) from file descriptor .Ar n2 .It Oo Ar n Oc Ns Li <&- close stdin (or file descriptor .Ar n ) .It Oo Ar n1 Oc Ns Li >& Ns Ar n2 duplicate stdout (or file descriptor .Ar n1 ) to file descriptor .Ar n2 .It Oo Ar n Oc Ns Li >&- close stdout (or file descriptor .Ar n ) .El .Pp The following redirection is often called a .Dq here-document . .Bd -unfilled -offset indent .Oo Ar n Oc Ns Li << Ar delimiter .D1 Ar here-doc-text .D1 ... .Ar delimiter .Ed .Pp All the text on successive lines up to the delimiter is saved away and made available to the command on standard input, or file descriptor .Ar n if it is specified. If the .Ar delimiter as specified on the initial line is quoted, then the .Ar here-doc-text is treated literally, otherwise the text is subjected to parameter expansion, command substitution, and arithmetic expansion (as described in the section on .Sx Word Expansions ) . If the operator is .Dq Li <<- instead of .Dq Li << , then leading tabs in the .Ar here-doc-text are stripped. .Ss Search and Execution There are three types of commands: shell functions, built-in commands, and normal programs. The command is searched for (by name) in that order. The three types of commands are all executed in a different way. .Pp When a shell function is executed, all of the shell positional parameters (except .Li $0 , which remains unchanged) are set to the arguments of the shell function. The variables which are explicitly placed in the environment of the command (by placing assignments to them before the function name) are made local to the function and are set to the values given. Then the command given in the function definition is executed. The positional parameters are restored to their original values when the command completes. This all occurs within the current shell. .Pp Shell built-in commands are executed internally to the shell, without spawning a new process. There are two kinds of built-in commands: regular and special. Assignments before special builtins persist after they finish executing and assignment errors, redirection errors and certain operand errors cause a script to be aborted. Special builtins cannot be overridden with a function. Both regular and special builtins can affect the shell in ways normal programs cannot. .Pp Otherwise, if the command name does not match a function or built-in command, the command is searched for as a normal program in the file system (as described in the next section). When a normal program is executed, the shell runs the program, passing the arguments and the environment to the program. If the program is not a normal executable file (i.e., if it does not begin with the .Dq "magic number" whose .Tn ASCII representation is .Dq Li #! , resulting in an .Er ENOEXEC return value from .Xr execve 2 ) but appears to be a text file, the shell will run a new instance of .Nm to interpret it. .Pp Note that previous versions of this document and the source code itself misleadingly and sporadically refer to a shell script without a magic number as a .Dq "shell procedure" . .Ss Path Search When locating a command, the shell first looks to see if it has a shell function by that name. Then it looks for a built-in command by that name. If a built-in command is not found, one of two things happen: .Bl -enum .It Command names containing a slash are simply executed without performing any searches. .It The shell searches each entry in the .Va PATH variable in turn for the command. The value of the .Va PATH variable should be a series of entries separated by colons. Each entry consists of a directory name. The current directory may be indicated implicitly by an empty directory name, or explicitly by a single period. .El .Ss Command Exit Status Each command has an exit status that can influence the behavior of other shell commands. The paradigm is that a command exits with zero for normal or success, and non-zero for failure, error, or a false indication. The man page for each command should indicate the various exit codes and what they mean. Additionally, the built-in commands return exit codes, as does an executed shell function. .Pp If a command is terminated by a signal, its exit status is 128 plus the signal number. Signal numbers are defined in the header file .In sys/signal.h . .Ss Complex Commands Complex commands are combinations of simple commands with control operators or keywords, together creating a larger complex command. More generally, a command is one of the following: .Bl -item -offset indent .It simple command .It pipeline .It list or compound-list .It compound command .It function definition .El .Pp Unless otherwise stated, the exit status of a command is that of the last simple command executed by the command. .Ss Pipelines A pipeline is a sequence of one or more commands separated by the control operator .Ql \&| . The standard output of all but the last command is connected to the standard input of the next command. The standard output of the last command is inherited from the shell, as usual. .Pp The format for a pipeline is: .Pp .D1 Oo Li \&! Oc Ar command1 Op Li \&| Ar command2 ... .Pp The standard output of .Ar command1 is connected to the standard input of .Ar command2 . The standard input, standard output, or both of a command is considered to be assigned by the pipeline before any redirection specified by redirection operators that are part of the command. .Pp Note that unlike some other shells, .Nm executes each process in a pipeline with more than one command in a subshell environment and as a child of the .Nm process. .Pp If the pipeline is not in the background (discussed later), the shell waits for all commands to complete. .Pp If the keyword .Ic !\& does not precede the pipeline, the exit status is the exit status of the last command specified in the pipeline. Otherwise, the exit status is the logical NOT of the exit status of the last command. That is, if the last command returns zero, the exit status is 1; if the last command returns greater than zero, the exit status is zero. .Pp Because pipeline assignment of standard input or standard output or both takes place before redirection, it can be modified by redirection. For example: .Pp .Dl "command1 2>&1 | command2" .Pp sends both the standard output and standard error of .Ar command1 to the standard input of .Ar command2 . .Pp A .Ql \&; or newline terminator causes the preceding AND-OR-list (described below in the section called .Sx Short-Circuit List Operators ) to be executed sequentially; an .Ql & causes asynchronous execution of the preceding AND-OR-list. .Ss Background Commands (&) If a command is terminated by the control operator ampersand .Pq Ql & , the shell executes the command in a subshell environment (see .Sx Grouping Commands Together below) and asynchronously; the shell does not wait for the command to finish before executing the next command. .Pp The format for running a command in background is: .Pp .D1 Ar command1 Li & Op Ar command2 Li & Ar ... .Pp If the shell is not interactive, the standard input of an asynchronous command is set to .Pa /dev/null . .Ss Lists (Generally Speaking) A list is a sequence of zero or more commands separated by newlines, semicolons, or ampersands, and optionally terminated by one of these three characters. The commands in a list are executed in the order they are written. If command is followed by an ampersand, the shell starts the command and immediately proceeds onto the next command; otherwise it waits for the command to terminate before proceeding to the next one. .Ss Short-Circuit List Operators .Dq Li && and .Dq Li || are AND-OR list operators. .Dq Li && executes the first command, and then executes the second command if the exit status of the first command is zero. .Dq Li || is similar, but executes the second command if the exit status of the first command is nonzero. .Dq Li && and .Dq Li || both have the same priority. .Ss Flow-Control Constructs (if, while, for, case) The syntax of the .Ic if command is: .Bd -unfilled -offset indent -compact .Ic if Ar list .Ic then Ar list .Oo Ic elif Ar list .Ic then Ar list Oc Ar ... .Op Ic else Ar list .Ic fi .Ed .Pp The syntax of the .Ic while command is: .Bd -unfilled -offset indent -compact .Ic while Ar list .Ic do Ar list .Ic done .Ed .Pp The two lists are executed repeatedly while the exit status of the first list is zero. The .Ic until command is similar, but has the word .Ic until in place of .Ic while , which causes it to repeat until the exit status of the first list is zero. .Pp The syntax of the .Ic for command is: .Bd -unfilled -offset indent -compact .Ic for Ar variable Op Ic in Ar word ... .Ic do Ar list .Ic done .Ed .Pp If .Ic in and the following words are omitted, .Ic in Li \&"$@\&" is used instead. The words are expanded, and then the list is executed repeatedly with the variable set to each word in turn. The .Ic do and .Ic done commands may be replaced with .Ql { and .Ql } . .Pp The syntax of the .Ic break and .Ic continue commands is: .D1 Ic break Op Ar num .D1 Ic continue Op Ar num .Pp The .Ic break command terminates the .Ar num innermost .Ic for or .Ic while loops. The .Ic continue command continues with the next iteration of the innermost loop. These are implemented as special built-in commands. .Pp The syntax of the .Ic case command is: .Bd -unfilled -offset indent -compact .Ic case Ar word Ic in .Ar pattern Ns Li ) Ar list Li ;; .Ar ... .Ic esac .Ed .Pp The pattern can actually be one or more patterns (see .Sx Shell Patterns described later), separated by .Ql \&| characters. Tilde expansion, parameter expansion, command substitution, arithmetic expansion and quote removal are applied to the word. Then, each pattern is expanded in turn using tilde expansion, parameter expansion, command substitution and arithmetic expansion and the expanded form of the word is checked against it. If a match is found, the corresponding list is executed. If the selected list is terminated by the control operator .Ql ;& instead of .Ql ;; , execution continues with the next list, continuing until a list terminated with .Ql ;; or the end of the .Ic case command. The exit code of the .Ic case command is the exit code of the last command executed in the list or zero if no patterns were matched. .Ss Grouping Commands Together Commands may be grouped by writing either .Pp .D1 Li \&( Ns Ar list Ns Li \%) .Pp or .Pp .D1 Li { Ar list Ns Li \&; } .Pp The first form executes the commands in a subshell environment. A subshell environment has its own copy of: .Pp .Bl -enum .It The current working directory as set by .Ic cd . .It The file creation mask as set by .Ic umask . .It References to open files. .It Traps as set by .Ic trap . .It Known jobs. .It Positional parameters and variables. .It Shell options. .It Shell functions. .It Shell aliases. .El .Pp These are copied from the parent shell environment, except that trapped (but not ignored) signals are reset to the default action and known jobs are cleared. Any changes do not affect the parent shell environment. .Pp A subshell environment may be implemented as a child process or differently. If job control is enabled in an interactive shell, commands grouped in parentheses can be suspended and continued as a unit. .Pp The second form never forks another shell, so it is slightly more efficient. Grouping commands together this way allows the user to redirect their output as though they were one program: .Bd -literal -offset indent { echo -n "hello"; echo " world"; } > greeting .Ed .Ss Functions The syntax of a function definition is .Pp .D1 Ar name Li \&( \&) Ar command .Pp A function definition is an executable statement; when executed it installs a function named .Ar name and returns an exit status of zero. The .Ar command is normally a list enclosed between .Ql { and .Ql } . .Pp Variables may be declared to be local to a function by using the .Ic local command. This should appear as the first statement of a function, and the syntax is: .Pp .D1 Ic local Oo Ar variable ... Oc Op Fl .Pp The .Ic local command is implemented as a built-in command. .Pp When a variable is made local, it inherits the initial value and exported and readonly flags from the variable with the same name in the surrounding scope, if there is one. Otherwise, the variable is initially unset. The shell uses dynamic scoping, so that if the variable .Va x is made local to function .Em f , which then calls function .Em g , references to the variable .Va x made inside .Em g will refer to the variable .Va x declared inside .Em f , not to the global variable named .Va x . .Pp The only special parameter that can be made local is .Ql - . Making .Ql - local causes any shell options that are changed via the .Ic set command inside the function to be restored to their original values when the function returns. .Pp The syntax of the .Ic return command is .Pp .D1 Ic return Op Ar exitstatus .Pp It terminates the current executional scope, returning from the previous nested function, sourced script, or shell instance, in that order. The .Ic return command is implemented as a special built-in command. .Ss Variables and Parameters The shell maintains a set of parameters. A parameter denoted by a name is called a variable. When starting up, the shell turns all the environment variables into shell variables. New variables can be set using the form .Pp .D1 Ar name Ns = Ns Ar value .Pp Variables set by the user must have a name consisting solely of alphabetics, numerics, and underscores. The first letter of a variable name must not be numeric. A parameter can also be denoted by a number or a special character as explained below. .Pp Assignments are expanded differently from other words: tilde expansion is also performed after the equals sign and after any colon and usernames are also terminated by colons, and field splitting and pathname expansion are not performed. .Ss Positional Parameters A positional parameter is a parameter denoted by a number greater than zero. The shell sets these initially to the values of its command line arguments that follow the name of the shell script. The .Ic set built-in command can also be used to set or reset them. .Ss Special Parameters Special parameters are parameters denoted by a single special character or the digit zero. They are shown in the following list, exactly as they would appear in input typed by the user or in the source of a shell script. .Bl -hang .It Li $* Expands to the positional parameters, starting from one. When the expansion occurs within a double-quoted string it expands to a single field with the value of each parameter separated by the first character of the .Va IFS variable, or by a space if .Va IFS is unset. .It Li $@ Expands to the positional parameters, starting from one. When the expansion occurs within double-quotes, each positional parameter expands as a separate argument. If there are no positional parameters, the expansion of .Li @ generates zero arguments, even when .Li @ is double-quoted. What this basically means, for example, is if .Li $1 is .Dq Li abc and .Li $2 is .Dq Li "def ghi" , then .Li \&"$@\&" expands to the two arguments: .Bd -literal -offset indent "abc" "def ghi" .Ed .It Li $# Expands to the number of positional parameters. .It Li $? Expands to the exit status of the most recent pipeline. .It Li $- (hyphen) Expands to the current option flags (the single-letter option names concatenated into a string) as specified on invocation, by the .Ic set built-in command, or implicitly by the shell. .It Li $$ Expands to the process ID of the invoked shell. A subshell retains the same value of .Va $ as its parent. .It Li $! Expands to the process ID of the most recent background command executed from the current shell. For a pipeline, the process ID is that of the last command in the pipeline. If this parameter is referenced, the shell will remember the process ID and its exit status until the .Ic wait built-in command reports completion of the process. .It Li $0 (zero) Expands to the name of the shell script if passed on the command line, the .Ar name operand if given (with .Fl c ) or otherwise argument 0 passed to the shell. .El .Ss Special Variables The following variables are set by the shell or have special meaning to it: .Bl -tag -width ".Va HISTSIZE" .It Va CDPATH The search path used with the .Ic cd built-in. .It Va EDITOR The fallback editor used with the .Ic fc built-in. If not set, the default editor is .Xr ed 1 . .It Va FCEDIT The default editor used with the .Ic fc built-in. .It Va HISTSIZE The number of previous commands that are accessible. .It Va HOME The user's home directory, used in tilde expansion and as a default directory for the .Ic cd built-in. .It Va IFS Input Field Separators. The default value is .Aq space , .Aq tab , and .Aq newline in that order. This default also applies if .Va IFS is unset, but not if it is set to the empty string. See the .Sx White Space Splitting section for more details. .It Va LINENO The current line number in the script or function. .It Va MAIL The name of a mail file, that will be checked for the arrival of new mail. Overridden by .Va MAILPATH . .It Va MAILPATH A colon .Pq Ql \&: separated list of file names, for the shell to check for incoming mail. This variable overrides the .Va MAIL setting. There is a maximum of 10 mailboxes that can be monitored at once. .It Va PATH The default search path for executables. See the .Sx Path Search section for details. .It Va PPID The parent process ID of the invoked shell. This is set at startup unless this variable is in the environment. A later change of parent process ID is not reflected. A subshell retains the same value of .Va PPID . .It Va PS1 The primary prompt string, which defaults to .Dq Li "$ " , unless you are the superuser, in which case it defaults to .Dq Li "# " . .It Va PS2 The secondary prompt string, which defaults to .Dq Li "> " . .It Va PS4 The prefix for the trace output (if .Fl x is active). The default is .Dq Li "+ " . .El .Ss Word Expansions This clause describes the various expansions that are performed on words. Not all expansions are performed on every word, as explained later. .Pp Tilde expansions, parameter expansions, command substitutions, arithmetic expansions, and quote removals that occur within a single word expand to a single field. It is only field splitting or pathname expansion that can create multiple fields from a single word. The single exception to this rule is the expansion of the special parameter .Va @ within double-quotes, as was described above. .Pp The order of word expansion is: .Bl -enum .It Tilde Expansion, Parameter Expansion, Command Substitution, Arithmetic Expansion (these all occur at the same time). .It Field Splitting is performed on fields generated by step (1) unless the .Va IFS variable is null. .It Pathname Expansion (unless the .Fl f option is in effect). .It Quote Removal. .El .Pp The .Ql $ character is used to introduce parameter expansion, command substitution, or arithmetic expansion. .Ss Tilde Expansion (substituting a user's home directory) A word beginning with an unquoted tilde character .Pq Ql ~ is subjected to tilde expansion. All the characters up to a slash .Pq Ql / or the end of the word are treated as a username and are replaced with the user's home directory. If the username is missing (as in .Pa ~/foobar ) , the tilde is replaced with the value of the .Va HOME variable (the current user's home directory). .Ss Parameter Expansion The format for parameter expansion is as follows: .Pp .D1 Li ${ Ns Ar expression Ns Li } .Pp where .Ar expression consists of all characters until the matching .Ql } . Any .Ql } escaped by a backslash or within a single-quoted or double-quoted string, and characters in embedded arithmetic expansions, command substitutions, and variable expansions, are not examined in determining the matching .Ql } . If the variants with .Ql + , .Ql - , .Ql = or .Ql ?\& occur within a double-quoted string, as an extension there may be unquoted parts (via double-quotes inside the expansion); .Ql } within such parts are also not examined in determining the matching .Ql } . .Pp The simplest form for parameter expansion is: .Pp .D1 Li ${ Ns Ar parameter Ns Li } .Pp The value, if any, of .Ar parameter is substituted. .Pp The parameter name or symbol can be enclosed in braces, which are optional except for positional parameters with more than one digit or when parameter is followed by a character that could be interpreted as part of the name. If a parameter expansion occurs inside double-quotes: .Bl -enum .It Field splitting is not performed on the results of the expansion, with the exception of the special parameter .Va @ . .It Pathname expansion is not performed on the results of the expansion. .El .Pp In addition, a parameter expansion can be modified by using one of the following formats. .Bl -tag -width indent .It Li ${ Ns Ar parameter Ns Li :- Ns Ar word Ns Li } Use Default Values. If .Ar parameter is unset or null, the expansion of .Ar word is substituted; otherwise, the value of .Ar parameter is substituted. .It Li ${ Ns Ar parameter Ns Li := Ns Ar word Ns Li } Assign Default Values. If .Ar parameter is unset or null, the expansion of .Ar word is assigned to .Ar parameter . In all cases, the final value of .Ar parameter is substituted. Quoting inside .Ar word does not prevent field splitting or pathname expansion. Only variables, not positional parameters or special parameters, can be assigned in this way. .It Li ${ Ns Ar parameter Ns Li :? Ns Oo Ar word Oc Ns Li } Indicate Error if Null or Unset. If .Ar parameter is unset or null, the expansion of .Ar word (or a message indicating it is unset if .Ar word is omitted) is written to standard error and the shell exits with a nonzero exit status. Otherwise, the value of .Ar parameter is substituted. An interactive shell need not exit. .It Li ${ Ns Ar parameter Ns Li :+ Ns Ar word Ns Li } Use Alternate Value. If .Ar parameter is unset or null, null is substituted; otherwise, the expansion of .Ar word is substituted. .El .Pp In the parameter expansions shown previously, use of the colon in the format results in a test for a parameter that is unset or null; omission of the colon results in a test for a parameter that is only unset. .Pp The .Ar word inherits the type of quoting (unquoted, double-quoted or here-document) from the surroundings, with the exception that a backslash that quotes a closing brace is removed during quote removal. .Bl -tag -width indent .It Li ${# Ns Ar parameter Ns Li } String Length. The length in characters of the value of .Ar parameter . .El .Pp The following four varieties of parameter expansion provide for substring processing. In each case, pattern matching notation (see .Sx Shell Patterns ) , rather than regular expression notation, is used to evaluate the patterns. If parameter is one of the special parameters .Va * or .Va @ , the result of the expansion is unspecified. Enclosing the full parameter expansion string in double-quotes does not cause the following four varieties of pattern characters to be quoted, whereas quoting characters within the braces has this effect. .Bl -tag -width indent .It Li ${ Ns Ar parameter Ns Li % Ns Ar word Ns Li } Remove Smallest Suffix Pattern. The .Ar word is expanded to produce a pattern. The parameter expansion then results in .Ar parameter , with the smallest portion of the suffix matched by the pattern deleted. .It Li ${ Ns Ar parameter Ns Li %% Ns Ar word Ns Li } Remove Largest Suffix Pattern. The .Ar word is expanded to produce a pattern. The parameter expansion then results in .Ar parameter , with the largest portion of the suffix matched by the pattern deleted. .It Li ${ Ns Ar parameter Ns Li # Ns Ar word Ns Li } Remove Smallest Prefix Pattern. The .Ar word is expanded to produce a pattern. The parameter expansion then results in .Ar parameter , with the smallest portion of the prefix matched by the pattern deleted. .It Li ${ Ns Ar parameter Ns Li ## Ns Ar word Ns Li } Remove Largest Prefix Pattern. The .Ar word is expanded to produce a pattern. The parameter expansion then results in .Ar parameter , with the largest portion of the prefix matched by the pattern deleted. .El .Ss Command Substitution Command substitution allows the output of a command to be substituted in place of the command name itself. Command substitution occurs when the command is enclosed as follows: .Pp .D1 Li $( Ns Ar command Ns Li )\& .Pp or the backquoted version: .Pp .D1 Li ` Ns Ar command Ns Li ` .Pp The shell expands the command substitution by executing command and replacing the command substitution with the standard output of the command, removing sequences of one or more newlines at the end of the substitution. Embedded newlines before the end of the output are not removed; however, during field splitting, they may be translated into spaces depending on the value of .Va IFS and the quoting that is in effect. The command is executed in a subshell environment, except that the built-in commands .Ic jobid , .Ic jobs , and .Ic trap return information about the parent shell environment and .Ic times returns information about the same process if they are the only command in a command substitution. .Ss Arithmetic Expansion Arithmetic expansion provides a mechanism for evaluating an arithmetic expression and substituting its value. The format for arithmetic expansion is as follows: .Pp .D1 Li $(( Ns Ar expression Ns Li )) .Pp The .Ar expression is treated as if it were in double-quotes, except that a double-quote inside the expression is not treated specially. The shell expands all tokens in the .Ar expression for parameter expansion, command substitution, arithmetic expansion and quote removal. .Pp The allowed expressions are a subset of C expressions, summarized below. .Bl -tag -width "Variables" -offset indent .It Values All values are of type .Ft intmax_t . .It Constants Decimal, octal (starting with .Li 0 ) -and hexadecimal (starting with +and hexadecimal (starting with .Li 0x ) integer constants. .It Variables Shell variables can be read and written and contain integer constants. .It Unary operators .Li "! ~ + -" .It Binary operators .Li "* / % + - << >> < <= > >= == != & ^ | && ||" .It Assignment operators .Li "= += -= *= /= %= <<= >>= &= ^= |=" .It Conditional operator .Li "? :" .El .Pp The result of the expression is substituted in decimal. .Ss White Space Splitting (Field Splitting) In certain contexts, after parameter expansion, command substitution, and arithmetic expansion the shell scans the results of expansions and substitutions that did not occur in double-quotes for field splitting and multiple fields can result. .Pp Characters in .Va IFS that are whitespace .Po .Aq space , .Aq tab , and .Aq newline .Pc are treated differently from other characters in .Va IFS . .Pp Whitespace in .Va IFS at the beginning or end of a word is discarded. .Pp Subsequently, a field is delimited by either .Bl -enum .It a non-whitespace character in .Va IFS with any whitespace in .Va IFS surrounding it, or .It one or more whitespace characters in .Va IFS . .El .Pp If a word ends with a non-whitespace character in .Va IFS , there is no empty field after this character. .Pp If no field is delimited, the word is discarded. In particular, if a word consists solely of an unquoted substitution and the result of the substitution is null, it is removed by field splitting even if .Va IFS is null. .Ss Pathname Expansion (File Name Generation) Unless the .Fl f option is set, file name generation is performed after word splitting is complete. Each word is viewed as a series of patterns, separated by slashes. The process of expansion replaces the word with the names of all existing files whose names can be formed by replacing each pattern with a string that matches the specified pattern. There are two restrictions on this: first, a pattern cannot match a string containing a slash, and second, a pattern cannot match a string starting with a period unless the first character of the pattern is a period. The next section describes the patterns used for Pathname Expansion, the four varieties of parameter expansion for substring processing and the .Ic case command. .Ss Shell Patterns A pattern consists of normal characters, which match themselves, and meta-characters. The meta-characters are .Ql * , .Ql \&? , and .Ql \&[ . These characters lose their special meanings if they are quoted. When command or variable substitution is performed and the dollar sign or back quotes are not double-quoted, the value of the variable or the output of the command is scanned for these characters and they are turned into meta-characters. .Pp An asterisk .Pq Ql * matches any string of characters. A question mark .Pq Ql \&? matches any single character. A left bracket .Pq Ql \&[ introduces a character class. The end of the character class is indicated by a .Ql \&] ; if the .Ql \&] is missing then the .Ql \&[ matches a .Ql \&[ rather than introducing a character class. A character class matches any of the characters between the square brackets. A locale-dependent range of characters may be specified using a minus sign. A named class of characters (see .Xr wctype 3 ) may be specified by surrounding the name with .Ql \&[: and .Ql :\&] . For example, .Ql \&[\&[:alpha:\&]\&] is a shell pattern that matches a single letter. The character class may be complemented by making an exclamation point .Pq Ql !\& the first character of the character class. A caret .Pq Ql ^ has the same effect but is non-standard. .Pp To include a .Ql \&] in a character class, make it the first character listed (after the .Ql \&! or .Ql ^ , if any). To include a .Ql - , make it the first or last character listed. .Ss Built-in Commands This section lists the built-in commands. .Bl -tag -width indent .It Ic \&: A null command that returns a 0 (true) exit value. .It Ic \&. Ar file The commands in the specified file are read and executed by the shell. The .Ic return command may be used to return to the .Ic \&. command's caller. If .Ar file contains any .Ql / characters, it is used as is. Otherwise, the shell searches the .Va PATH for the file. If it is not found in the .Va PATH , it is sought in the current working directory. .It Ic \&[ A built-in equivalent of .Xr test 1 . .It Ic alias Oo Ar name Ns Oo = Ns Ar string Oc ... Oc If .Ar name Ns = Ns Ar string is specified, the shell defines the alias .Ar name with value .Ar string . If just .Ar name is specified, the value of the alias .Ar name is printed. With no arguments, the .Ic alias built-in command prints the names and values of all defined aliases (see .Ic unalias ) . Alias values are written with appropriate quoting so that they are suitable for re-input to the shell. Also see the .Sx Aliases subsection. .It Ic bg Op Ar job ... Continue the specified jobs (or the current job if no jobs are given) in the background. .It Ic bind Oo Fl aeklrsv Oc Oo Ar key Oo Ar command Oc Oc List or alter key bindings for the line editor. This command is documented in .Xr editrc 5 . .It Ic break Op Ar num See the .Sx Flow-Control Constructs subsection. .It Ic builtin Ar cmd Op Ar arg ... Execute the specified built-in command, .Ar cmd . This is useful when the user wishes to override a shell function with the same name as a built-in command. .It Ic cd Oo Fl L | P Oc Oo Fl e Oc Op Ar directory Switch to the specified .Ar directory , or to the directory specified in the .Va HOME environment variable if no .Ar directory is specified. If .Ar directory does not begin with .Pa / , \&. , or .Pa .. , then the directories listed in the .Va CDPATH variable will be searched for the specified .Ar directory . If .Va CDPATH is unset, the current directory is searched. The format of .Va CDPATH is the same as that of .Va PATH . In an interactive shell, the .Ic cd command will print out the name of the directory that it actually switched to if this is different from the name that the user gave. These may be different either because the .Va CDPATH mechanism was used or because a symbolic link was crossed. .Pp If the .Fl P option is specified, .Pa .. is handled physically and symbolic links are resolved before .Pa .. components are processed. If the .Fl L option is specified, .Pa .. is handled logically. This is the default. .Pp The .Fl e option causes .Ic cd to return exit status 1 if the full pathname of the new directory cannot be determined reliably or at all. Normally this is not considered an error, although a warning is printed. .It Ic chdir A synonym for the .Ic cd built-in command. .It Ic command Oo Fl p Oc Op Ar utility Op Ar argument ... .It Ic command Oo Fl p Oc Fl v Ar utility .It Ic command Oo Fl p Oc Fl V Ar utility The first form of invocation executes the specified .Ar utility , ignoring shell functions in the search. If .Ar utility is a special builtin, it is executed as if it were a regular builtin. .Pp If the .Fl p option is specified, the command search is performed using a default value of .Va PATH that is guaranteed to find all of the standard utilities. .Pp If the .Fl v option is specified, .Ar utility is not executed but a description of its interpretation by the shell is printed. For ordinary commands the output is the path name; for shell built-in commands, shell functions and keywords only the name is written. Aliases are printed as .Dq Ic alias Ar name Ns = Ns Ar value . .Pp The .Fl V option is identical to .Fl v except for the output. It prints .Dq Ar utility Ic is Ar description where .Ar description is either the path name to .Ar utility , a special shell builtin, a shell builtin, a shell function, a shell keyword or an alias for .Ar value . .It Ic continue Op Ar num See the .Sx Flow-Control Constructs subsection. .It Ic echo Oo Fl e | n Oc Op Ar string ... Print a space-separated list of the arguments to the standard output and append a newline character. .Bl -tag -width indent .It Fl n Suppress the output of the trailing newline. .It Fl e Process C-style backslash escape sequences. The .Ic echo command understands the following character escapes: .Bl -tag -width indent .It \ea Alert (ring the terminal bell) .It \eb Backspace .It \ec Suppress the trailing newline (this has the side-effect of truncating the line if it is not the last character) .It \ee The ESC character .Tn ( ASCII 0x1b) .It \ef Formfeed .It \en Newline .It \er Carriage return .It \et Horizontal tab .It \ev Vertical tab .It \e\e Literal backslash .It \e0nnn (Zero) The character whose octal value is .Ar nnn .El .Pp If .Ar string is not enclosed in quotes then the backslash itself must be escaped with a backslash to protect it from the shell. For example .Bd -literal -offset indent $ echo -e "a\evb" a b $ echo -e a\e\evb a b $ echo -e "a\e\eb" a\eb $ echo -e a\e\e\e\eb a\eb .Ed .El .Pp Only one of the .Fl e and .Fl n options may be specified. .It Ic eval Ar string ... Concatenate all the arguments with spaces. Then re-parse and execute the command. .It Ic exec Op Ar command Op arg ... Unless .Ar command is omitted, the shell process is replaced with the specified program (which must be a real program, not a shell built-in command or function). Any redirections on the .Ic exec command are marked as permanent, so that they are not undone when the .Ic exec command finishes. .It Ic exit Op Ar exitstatus Terminate the shell process. If .Ar exitstatus is given it is used as the exit status of the shell. Otherwise, if the shell is executing an .Cm EXIT trap, the exit status of the last command before the trap is used; if the shell is executing a trap for a signal, the shell exits by resending the signal to itself. Otherwise, the exit status of the preceding command is used. The exit status should be an integer between 0 and 255. .It Ic export Ar name ... .It Ic export Op Fl p The specified names are exported so that they will appear in the environment of subsequent commands. The only way to un-export a variable is to .Ic unset it. The shell allows the value of a variable to be set at the same time as it is exported by writing .Pp .D1 Ic export Ar name Ns = Ns Ar value .Pp With no arguments the .Ic export command lists the names of all exported variables. If the .Fl p option is specified, the exported variables are printed as .Dq Ic export Ar name Ns = Ns Ar value lines, suitable for re-input to the shell. .It Ic false A null command that returns a non-zero (false) exit value. .It Ic fc Oo Fl e Ar editor Oc Op Ar first Op Ar last .It Ic fc Fl l Oo Fl nr Oc Op Ar first Op Ar last .It Ic fc Fl s Oo Ar old Ns = Ns Ar new Oc Op Ar first The .Ic fc built-in command lists, or edits and re-executes, commands previously entered to an interactive shell. .Bl -tag -width indent .It Fl e Ar editor Use the editor named by .Ar editor to edit the commands. The .Ar editor string is a command name, subject to search via the .Va PATH variable. The value in the .Va FCEDIT variable is used as a default when .Fl e is not specified. If .Va FCEDIT is null or unset, the value of the .Va EDITOR variable is used. If .Va EDITOR is null or unset, .Xr ed 1 is used as the editor. .It Fl l No (ell) List the commands rather than invoking an editor on them. The commands are written in the sequence indicated by the .Ar first and .Ar last operands, as affected by .Fl r , with each command preceded by the command number. .It Fl n Suppress command numbers when listing with .Fl l . .It Fl r Reverse the order of the commands listed (with .Fl l ) or edited (with neither .Fl l nor .Fl s ) . .It Fl s Re-execute the command without invoking an editor. .It Ar first .It Ar last Select the commands to list or edit. The number of previous commands that can be accessed are determined by the value of the .Va HISTSIZE variable. The value of .Ar first or .Ar last or both are one of the following: .Bl -tag -width indent .It Oo Cm + Oc Ns Ar num A positive number representing a command number; command numbers can be displayed with the .Fl l option. .It Fl Ar num A negative decimal number representing the command that was executed .Ar num of commands previously. For example, \-1 is the immediately previous command. .It Ar string A string indicating the most recently entered command that begins with that string. If the .Ar old Ns = Ns Ar new operand is not also specified with .Fl s , the string form of the first operand cannot contain an embedded equal sign. .El .El .Pp The following variables affect the execution of .Ic fc : .Bl -tag -width ".Va HISTSIZE" .It Va FCEDIT Name of the editor to use for history editing. .It Va HISTSIZE The number of previous commands that are accessible. .El .It Ic fg Op Ar job Move the specified .Ar job or the current job to the foreground. .It Ic getopts Ar optstring var The .Tn POSIX .Ic getopts command. The .Ic getopts command deprecates the older .Xr getopt 1 command. The first argument should be a series of letters, each possibly followed by a colon which indicates that the option takes an argument. The specified variable is set to the parsed option. The index of the next argument is placed into the shell variable .Va OPTIND . If an option takes an argument, it is placed into the shell variable .Va OPTARG . If an invalid option is encountered, .Ar var is set to .Ql \&? . It returns a false value (1) when it encounters the end of the options. .It Ic hash Oo Fl rv Oc Op Ar command ... The shell maintains a hash table which remembers the locations of commands. With no arguments whatsoever, the .Ic hash command prints out the contents of this table. Entries which have not been looked at since the last .Ic cd command are marked with an asterisk; it is possible for these entries to be invalid. .Pp With arguments, the .Ic hash command removes each specified .Ar command from the hash table (unless they are functions) and then locates it. With the .Fl v option, .Ic hash prints the locations of the commands as it finds them. The .Fl r option causes the .Ic hash command to delete all the entries in the hash table except for functions. .It Ic jobid Op Ar job Print the process IDs of the processes in the specified .Ar job . If the .Ar job argument is omitted, use the current job. .It Ic jobs Oo Fl lps Oc Op Ar job ... Print information about the specified jobs, or all jobs if no .Ar job argument is given. The information printed includes job ID, status and command name. .Pp If the .Fl l option is specified, the PID of each job is also printed. If the .Fl p option is specified, only the process IDs for the process group leaders are printed, one per line. If the .Fl s option is specified, only the PIDs of the job commands are printed, one per line. .It Ic kill A built-in equivalent of .Xr kill 1 that additionally supports sending signals to jobs. .It Ic local Oo Ar variable ... Oc Op Fl See the .Sx Functions subsection. .It Ic printf A built-in equivalent of .Xr printf 1 . .It Ic pwd Op Fl L | P Print the path of the current directory. The built-in command may differ from the program of the same name because the built-in command remembers what the current directory is rather than recomputing it each time. This makes it faster. However, if the current directory is renamed, the built-in version of .Xr pwd 1 will continue to print the old name for the directory. .Pp If the .Fl P option is specified, symbolic links are resolved. If the .Fl L option is specified, the shell's notion of the current directory is printed (symbolic links are not resolved). This is the default. .It Ic read Oo Fl p Ar prompt Oc Oo .Fl t Ar timeout Oc Oo Fl er Oc Ar variable ... The .Ar prompt is printed if the .Fl p option is specified and the standard input is a terminal. Then a line is read from the standard input. The trailing newline is deleted from the line and the line is split as described in the section on .Sx White Space Splitting (Field Splitting) above, and the pieces are assigned to the variables in order. If there are more pieces than variables, the remaining pieces (along with the characters in .Va IFS that separated them) are assigned to the last variable. If there are more variables than pieces, the remaining variables are assigned the null string. .Pp Backslashes are treated specially, unless the .Fl r option is specified. If a backslash is followed by a newline, the backslash and the newline will be deleted. If a backslash is followed by any other character, the backslash will be deleted and the following character will be treated as though it were not in .Va IFS , even if it is. .Pp If the .Fl t option is specified and the .Ar timeout elapses before a complete line of input is supplied, the .Ic read command will return an exit status of 1 without assigning any values. The .Ar timeout value may optionally be followed by one of .Ql s , .Ql m or .Ql h to explicitly specify seconds, minutes or hours. If none is supplied, .Ql s is assumed. .Pp The .Fl e option exists only for backward compatibility with older scripts. .It Ic readonly Oo Fl p Oc Op Ar name ... Each specified .Ar name is marked as read only, so that it cannot be subsequently modified or unset. The shell allows the value of a variable to be set at the same time as it is marked read only by using the following form: .Pp .D1 Ic readonly Ar name Ns = Ns Ar value .Pp With no arguments the .Ic readonly command lists the names of all read only variables. If the .Fl p option is specified, the read-only variables are printed as .Dq Ic readonly Ar name Ns = Ns Ar value lines, suitable for re-input to the shell. .It Ic return Op Ar exitstatus See the .Sx Functions subsection. .It Ic set Oo Fl /+abCEefIimnpTuVvx Oc Oo Fl /+o Ar longname Oc Oo .Fl c Ar string Oc Op Fl - Ar arg ... The .Ic set command performs three different functions: .Bl -item .It With no arguments, it lists the values of all shell variables. .It If options are given, either in short form or using the long .Dq Fl /+o Ar longname form, it sets or clears the specified options as described in the section called .Sx Argument List Processing . .It If the .Dq Fl - option is specified, .Ic set will replace the shell's positional parameters with the subsequent arguments. If no arguments follow the .Dq Fl - option, all the positional parameters will be cleared, which is equivalent to executing the command .Dq Li "shift $#" . The .Dq Fl - flag may be omitted when specifying arguments to be used as positional replacement parameters. This is not recommended, because the first argument may begin with a dash .Pq Ql - or a plus .Pq Ql + , which the .Ic set command will interpret as a request to enable or disable options. .El .It Ic setvar Ar variable value Assigns the specified .Ar value to the specified .Ar variable . The .Ic setvar command is intended to be used in functions that assign values to variables whose names are passed as parameters. In general it is better to write .Dq Ar variable Ns = Ns Ar value rather than using .Ic setvar . .It Ic shift Op Ar n Shift the positional parameters .Ar n times, or once if .Ar n is not specified. A shift sets the value of .Li $1 to the value of .Li $2 , the value of .Li $2 to the value of .Li $3 , and so on, decreasing the value of .Li $# by one. If there are zero positional parameters, shifting does not do anything. .It Ic test A built-in equivalent of .Xr test 1 . .It Ic times Print the amount of time spent executing the shell process and its children. The first output line shows the user and system times for the shell process itself, the second one contains the user and system times for the children. .It Ic trap Oo Ar action Oc Ar signal ... .It Ic trap Fl l Cause the shell to parse and execute .Ar action when any specified .Ar signal is received. The signals are specified by name or number. In addition, the pseudo-signal .Cm EXIT may be used to specify an .Ar action that is performed when the shell terminates. The .Ar action may be an empty string or a dash .Pq Ql - ; the former causes the specified signal to be ignored and the latter causes the default action to be taken. Omitting the .Ar action is another way to request the default action, for compatibility reasons this usage is not recommended though. In a subshell or utility environment, the shell resets trapped (but not ignored) signals to the default action. The .Ic trap command has no effect on signals that were ignored on entry to the shell. .Pp Option .Fl l causes the .Ic trap command to display a list of valid signal names. .It Ic true A null command that returns a 0 (true) exit value. .It Ic type Op Ar name ... Interpret each .Ar name as a command and print the resolution of the command search. Possible resolutions are: shell keyword, alias, special shell builtin, shell builtin, command, tracked alias and not found. For aliases the alias expansion is printed; for commands and tracked aliases the complete pathname of the command is printed. .It Ic ulimit Oo Fl HSabcdflmnpstuvw Oc Op Ar limit Set or display resource limits (see .Xr getrlimit 2 ) . If .Ar limit is specified, the named resource will be set; otherwise the current resource value will be displayed. .Pp If .Fl H is specified, the hard limits will be set or displayed. While everybody is allowed to reduce a hard limit, only the superuser can increase it. The .Fl S option specifies the soft limits instead. When displaying limits, only one of .Fl S or .Fl H can be given. The default is to display the soft limits, and to set both the hard and the soft limits. .Pp Option .Fl a causes the .Ic ulimit command to display all resources. The parameter .Ar limit is not acceptable in this mode. .Pp The remaining options specify which resource value is to be displayed or modified. They are mutually exclusive. .Bl -tag -width indent .It Fl b Ar sbsize The maximum size of socket buffer usage, in bytes. .It Fl c Ar coredumpsize The maximal size of core dump files, in 512-byte blocks. .It Fl d Ar datasize The maximal size of the data segment of a process, in kilobytes. .It Fl f Ar filesize The maximal size of a file, in 512-byte blocks. .It Fl l Ar lockedmem The maximal size of memory that can be locked by a process, in kilobytes. .It Fl m Ar memoryuse The maximal resident set size of a process, in kilobytes. .It Fl n Ar nofiles The maximal number of descriptors that could be opened by a process. .It Fl p Ar pseudoterminals The maximal number of pseudo-terminals for this user ID. .It Fl s Ar stacksize The maximal size of the stack segment, in kilobytes. .It Fl t Ar time The maximal amount of CPU time to be used by each process, in seconds. .It Fl u Ar userproc The maximal number of simultaneous processes for this user ID. .It Fl v Ar virtualmem The maximal virtual size of a process, in kilobytes. .It Fl w Ar swapuse The maximum amount of swap space reserved or used for this user ID, in kilobytes. .El .It Ic umask Oo Fl S Oc Op Ar mask Set the file creation mask (see .Xr umask 2 ) to the octal or symbolic (see .Xr chmod 1 ) value specified by .Ar mask . If the argument is omitted, the current mask value is printed. If the .Fl S option is specified, the output is symbolic, otherwise the output is octal. .It Ic unalias Oo Fl a Oc Op Ar name ... The specified alias names are removed. If .Fl a is specified, all aliases are removed. .It Ic unset Oo Fl fv Oc Ar name ... The specified variables or functions are unset and unexported. If the .Fl v option is specified or no options are given, the .Ar name arguments are treated as variable names. If the .Fl f option is specified, the .Ar name arguments are treated as function names. .It Ic wait Op Ar job Wait for the specified .Ar job to complete and return the exit status of the last process in the .Ar job . If the argument is omitted, wait for all jobs to complete and return an exit status of zero. .El .Ss Commandline Editing When .Nm is being used interactively from a terminal, the current command and the command history (see .Ic fc in .Sx Built-in Commands ) can be edited using .Nm vi Ns -mode command line editing. This mode uses commands similar to a subset of those described in the .Xr vi 1 man page. The command .Dq Li "set -o vi" (or .Dq Li "set -V" ) enables .Nm vi Ns -mode editing and places .Nm into .Nm vi insert mode. With .Nm vi Ns -mode enabled, .Nm can be switched between insert mode and command mode by typing .Aq ESC . Hitting .Aq return while in command mode will pass the line to the shell. .Pp Similarly, the .Dq Li "set -o emacs" (or .Dq Li "set -E" ) command can be used to enable a subset of .Nm emacs Ns -style command line editing features. .Sh ENVIRONMENT The following environment variables affect the execution of .Nm : .Bl -tag -width ".Ev LANGXXXXXX" .It Ev ENV Initialization file for interactive shells. .It Ev LANG , Ev LC_* Locale settings. These are inherited by children of the shell, and is used in a limited manner by the shell itself. .It Ev PWD An absolute pathname for the current directory, possibly containing symbolic links. This is used and updated by the shell. .It Ev TERM The default terminal setting for the shell. This is inherited by children of the shell, and is used in the history editing modes. .El .Pp Additionally, all environment variables are turned into shell variables at startup, which may affect the shell as described under .Sx Special Variables . .Sh EXIT STATUS Errors that are detected by the shell, such as a syntax error, will cause the shell to exit with a non-zero exit status. If the shell is not an interactive shell, the execution of the shell file will be aborted. Otherwise the shell will return the exit status of the last command executed, or if the .Ic exit builtin is used with a numeric argument, it will return the argument. .Sh SEE ALSO .Xr builtin 1 , .Xr chsh 1 , .Xr echo 1 , .Xr ed 1 , .Xr emacs 1 , .Xr kill 1 , .Xr printf 1 , .Xr pwd 1 , .Xr test 1 , .Xr vi 1 , .Xr execve 2 , .Xr getrlimit 2 , .Xr umask 2 , .Xr wctype 3 , .Xr editrc 5 .Sh HISTORY A .Nm command, the Thompson shell, appeared in .At v1 . It was superseded in .At v7 by the Bourne shell, which inherited the name .Nm . .Pp This version of .Nm was rewritten in 1989 under the .Bx license after the Bourne shell from .At V.4 . .Sh AUTHORS This version of .Nm was originally written by .An Kenneth Almquist . .Sh BUGS The .Nm utility does not recognize multibyte characters other than UTF-8. Splitting using .Va IFS and the line editing library .Xr editline 3 do not recognize multibyte characters. Index: stable/9/bin/sh =================================================================== --- stable/9/bin/sh (revision 237215) +++ stable/9/bin/sh (revision 237216) Property changes on: stable/9/bin/sh ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/bin/sh:r233648 Index: stable/9/games/pom/pom.6 =================================================================== --- stable/9/games/pom/pom.6 (revision 237215) +++ stable/9/games/pom/pom.6 (revision 237216) @@ -1,66 +1,66 @@ .\" Copyright (c) 1989, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)pom.6 8.1 (Berkeley) 5/31/93 .\" $FreeBSD$ .\" .Dd July 14, 2010 .Dt POM 6 .Os .Sh NAME .Nm pom .Nd display the phase of the moon .Sh SYNOPSIS -.Nm +.Nm .Op Fl p .Op Fl d Ar yyyy.mm.dd .Op Fl t Ar hh:mm:ss .Sh DESCRIPTION The .Nm utility displays the current phase of the moon. Useful for selecting software completion target dates and predicting managerial behavior. .Pp Use the .Fl p option to print just the phase as a percentage. .Pp Use the arguments .Fl d and .Fl t to specify a specific date and time for which the phase of the moon has to be calculated. If .Fl d but not .Fl t has been specified, it will calculate the phase of the moon on that day at midnight. .Sh SEE ALSO `Practical Astronomy with Your Calculator' by Duffett-Smith. Index: stable/9/games/pom =================================================================== --- stable/9/games/pom (revision 237215) +++ stable/9/games/pom (revision 237216) Property changes on: stable/9/games/pom ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/head_mfi/games/pom:r233621 Merged /vendor/resolver/dist/games/pom:r1540-186085 Merged /projects/quota64/games/pom:r184125-207707 Merged /head/games/pom:r226702,226785,227006,228761,229067,229997,230127,230587,231544,233648,233713,234313,234782,235122,236338-236339,236346-236347,236365,236977 Merged /projects/largeSMP/games/pom:r221273-222812,222815-223757 Index: stable/9/lib/libbluetooth/bluetooth.3 =================================================================== --- stable/9/lib/libbluetooth/bluetooth.3 (revision 237215) +++ stable/9/lib/libbluetooth/bluetooth.3 (revision 237216) @@ -1,727 +1,727 @@ .\" Copyright (c) 2003-2009 Maksim Yevmenkin .\" 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. .\" .\" $Id: bluetooth.3,v 1.5 2003/05/20 23:04:30 max Exp $ .\" $FreeBSD$ .\" .Dd April 9, 2009 .Dt BLUETOOTH 3 .Os .Sh NAME .Nm bt_gethostbyname , .Nm bt_gethostbyaddr , .Nm bt_gethostent , .Nm bt_sethostent , .Nm bt_endhostent , .Nm bt_getprotobyname , .Nm bt_getprotobynumber , .Nm bt_getprotoent , .Nm bt_setprotoent , .Nm bt_endprotoent , .Nm bt_aton , .Nm bt_ntoa , .Nm bt_devaddr , .Nm bt_devname , .Nm bt_devinfo , .Nm bt_devenum , .Nm bt_devopen , .Nm bt_devclose , .Nm bt_devsend , .Nm bt_devrecv , .Nm bt_devreq , .Nm bt_devfilter , .Nm bt_devfilter_pkt_set , .Nm bt_devfilter_pkt_clr , .Nm bt_devfilter_pkt_tst , .Nm bt_devfilter_evt_set , .Nm bt_devfilter_evt_clr , .Nm bt_devfilter_evt_tst , .Nm bt_devinquiry , .Nm bdaddr_same , .Nm bdaddr_any , .Nm bdaddr_copy .Nd Bluetooth routines .Sh LIBRARY .Lb libbluetooth .Sh SYNOPSIS .In bluetooth.h .Ft struct hostent * .Fn bt_gethostbyname "const char *name" .Ft struct hostent * .Fn bt_gethostbyaddr "const char *addr" "int len" "int type" .Ft struct hostent * .Fn bt_gethostent void .Ft void .Fn bt_sethostent "int stayopen" .Ft void .Fn bt_endhostent void .Ft struct protoent * .Fn bt_getprotobyname "const char *name" .Ft struct protoent * .Fn bt_getprotobynumber "int proto" .Ft struct protoent * .Fn bt_getprotoent void .Ft void .Fn bt_setprotoent "int stayopen" .Ft void .Fn bt_endprotoent void .Ft int .Fn bt_aton "const char *str" "bdaddr_t *ba" .Ft const char * .Fn bt_ntoa "const bdaddr_t *ba" "char *str" .Ft int .Fn bt_devaddr "const char *devname" "bdaddr_t *addr" .Ft int .Fn bt_devname "char *devname" "const bdaddr_t *addr" .Ft int .Fn (bt_devenum_cb_t) "int s" "struct bt_devinfo const *di" "void *arg" .Ft int .Fn bt_devinfo "struct bt_devinfo *di" .Ft int .Fn bt_devenum "bt_devenum_cb_t *cb" "void *arg" .Ft int .Fn bt_devopen "char const *devname" .Ft int .Fn bt_devclose "int s" .Ft int .Fn bt_devsend "int s" "uint16_t opcode" "void *param" "size_t plen" .Ft ssize_t .Fn bt_devrecv "int s" "void *buf" "size_t size" "time_t to" .Ft int .Fn bt_devreq "int s" "struct bt_devreq *r" "time_t to" .Ft int .Fn bt_devfilter "int s" "struct bt_devfilter const *new" "struct bt_devfilter *old" .Ft void .Fn bt_devfilter_pkt_set "struct bt_devfilter *filter" "uint8_t type" .Ft void .Fn bt_devfilter_pkt_clt "struct bt_devfilter *filter" "uint8_t type" .Ft int .Fn bt_devfilter_pkt_tst "struct bt_devfilter const *filter" "uint8_t type" .Ft void .Fn bt_devfilter_evt_set "struct bt_devfilter *filter" "uint8_t event" .Ft void .Fn bt_devfilter_evt_clt "struct bt_devfilter *filter" "uint8_t event" .Ft int .Fn bt_devfilter_evt_tst "struct bt_devfilter const *filter" "uint8_t event" .Ft int .Fn bt_devinquiry "char const *devname" "time_t length" "int num_rsp" "struct bt_devinquiry **ii" .Ft int .Fn bdaddr_same "const bdaddr_t *a" "const bdaddr_t *b" .Ft int .Fn bdaddr_any "const bdaddr_t *a" .Ft int .Fn bdaddr_copy "const bdaddr_t *dst" "const bdaddr_t *src" .Sh DESCRIPTION The .Fn bt_gethostent , .Fn bt_gethostbyname and .Fn bt_gethostbyaddr functions each return a pointer to an object with the .Vt hostent structure describing a Bluetooth host referenced by name or by address, respectively. .Pp The .Fa name argument passed to .Fn bt_gethostbyname should point to a .Dv NUL Ns -terminated hostname. The .Fa addr argument passed to .Fn bt_gethostbyaddr should point to an address which is .Fa len bytes long, in binary form (i.e., not a Bluetooth BD_ADDR in human readable .Tn ASCII form). The .Fa type argument specifies the address family of this address and must be set to .Dv AF_BLUETOOTH . .Pp The structure returned contains the information obtained from a line in .Pa /etc/bluetooth/hosts file. .Pp The .Fn bt_sethostent function controls whether .Pa /etc/bluetooth/hosts file should stay open after each call to .Fn bt_gethostbyname or .Fn bt_gethostbyaddr . If the .Fa stayopen flag is non-zero, the file will not be closed. .Pp The .Fn bt_endhostent function closes the .Pa /etc/bluetooth/hosts file. .Pp The .Fn bt_getprotoent , .Fn bt_getprotobyname and .Fn bt_getprotobynumber functions each return a pointer to an object with the .Vt protoent structure describing a Bluetooth Protocol Service Multiplexor referenced by name or number, respectively. .Pp The .Fa name argument passed to .Fn bt_getprotobyname should point to a .Dv NUL Ns -terminated Bluetooth Protocol Service Multiplexor name. The .Fa proto argument passed to .Fn bt_getprotobynumber should have numeric value of the desired Bluetooth Protocol Service Multiplexor. .Pp The structure returned contains the information obtained from a line in .Pa /etc/bluetooth/protocols file. .Pp The .Fn bt_setprotoent function controls whether .Pa /etc/bluetooth/protocols file should stay open after each call to .Fn bt_getprotobyname or .Fn bt_getprotobynumber . If the .Fa stayopen flag is non-zero, the file will not be closed. .Pp The .Fn bt_endprotoent function closes the .Pa /etc/bluetooth/protocols file. .Pp The .Fn bt_aton routine interprets the specified character string as a Bluetooth address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. .Pp The routine .Fn bt_ntoa takes a Bluetooth address and places an .Tn ASCII string representing the address into the buffer provided. It is up to the caller to ensure that provided buffer has enough space. If no buffer was provided then internal static buffer will be used. .Pp The .Fn bt_devaddr function interprets the specified .Fa devname string as the address or device name of a Bluetooth device on the local system, and places the device address in the provided .Fa bdaddr , if any. The function returns 1 if the string was successfully interpreted, or 0 if the string did not match any local device. The .Fn bt_devname function takes a Bluetooth device address and copies the local device name associated with that address into the buffer provided, if any. Caller must ensure that provided buffer is at least .Dv HCI_DEVNAME_SIZE characters in size. The function returns 1 when the device was found, otherwise 0. .Pp The .Fn bt_devinfo function populates provided .Vt bt_devinfo structure with the information about given Bluetooth device. The caller is expected to pass Bluetooth device name in the .Fa devname field of the passed .Vt bt_devinfo structure. The function returns 0 when successful, otherwise -1. The .Vt bt_devinfo structure is defined as follows .Bd -literal -offset indent struct bt_devinfo { char devname[HCI_DEVNAME_SIZE]; uint32_t state; bdaddr_t bdaddr; uint16_t _reserved0; uint8_t features[HCI_DEVFEATURES_SIZE]; /* buffer info */ uint16_t _reserved1; uint16_t cmd_free; uint16_t sco_size; uint16_t sco_pkts; uint16_t sco_free; uint16_t acl_size; uint16_t acl_pkts; uint16_t acl_free; /* stats */ uint32_t cmd_sent; uint32_t evnt_recv; uint32_t acl_recv; uint32_t acl_sent; uint32_t sco_recv; uint32_t sco_sent; uint32_t bytes_recv; uint32_t bytes_sent; /* misc/specific */ uint16_t link_policy_info; uint16_t packet_type_info; uint16_t role_switch_info; uint16_t debug; uint8_t _padding[20]; }; .Ed .Pp The .Fn bt_devenum function enumerates Bluetooth devices present in the system. For every device found, the function will call provided .Fa cb callback function which should be of .Vt bt_devenum_cb_t type. The callback function is passed a .Dv HCI socket .Fa s , fully populated .Vt bt_devinfo structure .Fa di and .Fa arg argument provided to the .Fn bt_devenum . The callback function can stop enumeration by returning a value that is greater than zero. The function returns number of successfully enumerated devices, or -1 if an error occurred. .Pp The .Fn bt_devopen function opens a Bluetooth device with the given .Fa devname and returns a connected and bound .Dv HCI socket handle. The function returns -1 if an error has occurred. .Pp The .Fn bt_devclose closes the passed .Dv HCI socket handle .Fa s , previously obtained with .Xr bt_devopen 3 . .Pp The .Fn bt_devsend function sends a Bluetooth .Dv HCI command with the given .Fa opcode to the provided socket .Fa s , previously obtained with .Xr bt_devopen 3 . The .Fa opcode parameter is expected to be in the host byte order. The .Fa param and .Fa plen parameters specify command parameters. The .Fn bt_devsend function does not modify the .Dv HCI filter on the provided socket .Fa s . The function returns 0 on success, or -1 if an error occurred. .Pp The .Fn bt_devrecv function receives one Bluetooth .Dv HCI packet from the socket .Fa s , previously obtained with .Xr bt_devopen 3 . The packet is placed into the provided buffer .Fa buf of size .Fa size . The .Fa to parameter specifies receive timeout in seconds. Infinite timeout can be specified by passing negative value in the .Fa to parameter. The .Fn bt_devrecv function does not modify the .Dv HCI filter on the provided socket .Fa s . The function returns total number of bytes received, or -1 if an error occurred. .Pp The .Fn bt_devreq function makes a Bluetooth .Dv HCI request to the socket .Fa s , previously obtained with .Xr bt_devopen 3 . The function will send the specified command and will wait for the specified event, or timeout .Fa to seconds to occur. The .Vt bt_devreq structure is defined as follows .Bd -literal -offset indent struct bt_devreq { uint16_t opcode; uint8_t event; void *cparam; size_t clen; void *rparam; size_t rlen; }; .Ed .Pp The .Fa opcode field specifies the command and is expected to be in the host byte order. The .Fa cparam and .Fa clen fields specify command parameters data and command parameters data size respectively. The .Fa event field specifies which Bluetooth .Dv HCI event ID the function should wait for, otherwise it should be set to zero. The .Dv HCI Command Complete and Command Status events are enabled by default. The .Fa rparam and .Fa rlen parameters specify buffer and buffer size respectively where return parameters should be placed. The .Fn bt_devreq function temporarily modifies filter on the provided .Dv HCI socket .Fa s . The function returns 0 on success, or -1 if an error occurred. .Pp The .Fn bt_devfilter controls the local .Dv HCI filter associated with the socket .Fa s , previously obtained with .Xr bt_devopen 3 . Filtering can be done on packet types, i.e. .Dv ACL , .Dv SCO or .Dv HCI , command and event packets, and, in addition, on .Dv HCI event IDs. Before applying the .Fa new filter (if provided) the function will try to obtain the current filter from the socket .Fa s and place it into the .Fa old parameter (if provided). The function returns 0 on success, or -1 if an error occurred. .Pp The .Fn bt_devfilter_pkt_set , -.Fn bt_devfilter_pkt_clr +.Fn bt_devfilter_pkt_clr and .Fn bt_devfilter_pkt_tst functions can be used to modify and test the .Dv HCI filter .Fa filter . The .Fa type parameter specifies .Dv HCI packet type. .Pp The .Fn bt_devfilter_evt_set , -.Fn bt_devfilter_evt_clr +.Fn bt_devfilter_evt_clr and .Fn bt_devfilter_evt_tst functions can be used to modify and test the .Dv HCI event filter .Fa filter . The .Fa event parameter specifies .Dv HCI event ID. .Pp The .Fn bt_devinquiry function performs Bluetooth inquiry. The .Fa devname parameter specifies which local Bluetooth device should perform an inquiry. If not specified, i.e. .Dv NULL , then first available device will be used. The .Fa length parameters specifies the total length of an inquiry in seconds. If not specified, i.e. 0, default value will be used. The .Fa num_rsp parameter specifies the number of responses that can be received before the inquiry is halted. If not specified, i.e. 0, default value will be used. The .Fa ii parameter specifies where to place inquiry results. On success, the function will return total number of inquiry results, will allocate, using .Xr calloc 3 , buffer to store all the inquiry results and will return pointer to the allocated buffer in the .Fa ii parameter. It is up to the caller of the function to dispose of the buffer using .Xr free 3 call. The function returns -1 if an error has occurred. The .Vt bt_devinquiry structure is defined as follows .Bd -literal -offset indent struct bt_devinquiry { bdaddr_t bdaddr; uint8_t pscan_rep_mode; uint8_t pscan_period_mode; uint8_t dev_class[3]; uint16_t clock_offset; int8_t rssi; uint8_t data[240]; }; .Ed .Pp The .Fn bdaddr_same , .Fn bdaddr_any and .Fn bdaddr_copy are handy shorthand Bluetooth address utility functions. The .Fn bdaddr_same function will test if two provided BD_ADDRs are the same. The .Fn bdaddr_any function will test if provided BD_ADDR is .Dv ANY BD_ADDR. The .Fn bdaddr_copy function will copy provided .Fa src BD_ADDR into provided .Fa dst BD_ADDR. .Sh FILES .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact .It Pa /etc/bluetooth/hosts .It Pa /etc/bluetooth/protocols .El .Sh EXAMPLES Print out the hostname associated with a specific BD_ADDR: .Bd -literal -offset indent const char *bdstr = "00:01:02:03:04:05"; bdaddr_t bd; struct hostent *hp; if (!bt_aton(bdstr, &bd)) errx(1, "can't parse BD_ADDR %s", bdstr); if ((hp = bt_gethostbyaddr((const char *)&bd, sizeof(bd), AF_BLUETOOTH)) == NULL) errx(1, "no name associated with %s", bdstr); printf("name associated with %s is %s\en", bdstr, hp->h_name); .Ed .Sh DIAGNOSTICS Error return status from .Fn bt_gethostent , .Fn bt_gethostbyname and .Fn bt_gethostbyaddr is indicated by return of a .Dv NULL pointer. The external integer .Va h_errno may then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .Xr herror 3 can be used to print an error message describing the failure. If its argument .Fa string is .Pf non- Dv NULL , it is printed, followed by a colon and a space. The error message is printed with a trailing newline. .Pp The variable .Va h_errno can have the following values: .Bl -tag -width ".Dv HOST_NOT_FOUND" .It Dv HOST_NOT_FOUND No such host is known. .It Dv NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .El .Pp The .Fn bt_getprotoent , .Fn bt_getprotobyname and .Fn bt_getprotobynumber return .Dv NULL on EOF or error. .Sh SEE ALSO .Xr gethostbyaddr 3 , .Xr gethostbyname 3 , .Xr getprotobyname 3 , .Xr getprotobynumber 3 , .Xr herror 3 , .Xr inet_aton 3 , .Xr inet_ntoa 3 , .Xr ng_hci 4 .Sh CAVEAT The .Fn bt_gethostent function reads the next line of .Pa /etc/bluetooth/hosts , opening the file if necessary. .Pp The .Fn bt_sethostent function opens and/or rewinds the .Pa /etc/bluetooth/hosts file. .Pp The .Fn bt_getprotoent function reads the next line of .Pa /etc/bluetooth/protocols , opening the file if necessary. .Pp The .Fn bt_setprotoent function opens and/or rewinds the .Pa /etc/bluetooth/protocols file. .Pp The .Fn bt_devenum function enumerates up to .Dv HCI_DEVMAX Bluetooth devices. During enumeration the .Fn bt_devenum function uses the same .Dv HCI socket. The function guarantees that the socket, passed to the callback function, will be bound and connected to the Bluetooth device being enumerated. .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com .Sh BUGS Some of those functions use static data storage; if the data is needed for future use, it should be copied before any subsequent calls overwrite it. Index: stable/9/lib/libbluetooth =================================================================== --- stable/9/lib/libbluetooth (revision 237215) +++ stable/9/lib/libbluetooth (revision 237216) Property changes on: stable/9/lib/libbluetooth ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libbluetooth:r233648 Index: stable/9/lib/libc/gen/fts.3 =================================================================== --- stable/9/lib/libc/gen/fts.3 (revision 237215) +++ stable/9/lib/libc/gen/fts.3 (revision 237216) @@ -1,813 +1,813 @@ .\" Copyright (c) 1989, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. 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. .\" .\" @(#)fts.3 8.5 (Berkeley) 4/16/94 .\" $FreeBSD$ .\" .Dd March 18, 2012 .Dt FTS 3 .Os .Sh NAME .Nm fts .Nd traverse a file hierarchy .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/stat.h .In fts.h .Ft FTS * .Fn fts_open "char * const *path_argv" "int options" "int (*compar)(const FTSENT * const *, const FTSENT * const *)" .Ft FTSENT * .Fn fts_read "FTS *ftsp" .Ft FTSENT * .Fn fts_children "FTS *ftsp" "int options" .Ft int .Fn fts_set "FTS *ftsp" "FTSENT *f" "int options" .Ft void .Fn fts_set_clientptr "FTS *ftsp" "void *clientdata" .Ft void * .Fn fts_get_clientptr "FTS *ftsp" .Ft FTS * .Fn fts_get_stream "FTSENT *f" .Ft int .Fn fts_close "FTS *ftsp" .Sh DESCRIPTION The .Nm functions are provided for traversing .Ux file hierarchies. A simple overview is that the .Fn fts_open function returns a .Dq handle on a file hierarchy, which is then supplied to the other .Nm functions. The function .Fn fts_read returns a pointer to a structure describing one of the files in the file hierarchy. The function .Fn fts_children returns a pointer to a linked list of structures, each of which describes one of the files contained in a directory in the hierarchy. In general, directories are visited two distinguishable times; in pre-order (before any of their descendants are visited) and in post-order (after all of their descendants have been visited). Files are visited once. It is possible to walk the hierarchy .Dq logically (ignoring symbolic links) or physically (visiting symbolic links), order the walk of the hierarchy or prune and/or re-visit portions of the hierarchy. .Pp Two structures are defined (and typedef'd) in the include file .In fts.h . The first is .Vt FTS , the structure that represents the file hierarchy itself. The second is .Vt FTSENT , the structure that represents a file in the file hierarchy. Normally, an .Vt FTSENT structure is returned for every file in the file hierarchy. In this manual page, .Dq file and .Dq Vt FTSENT No structure are generally interchangeable. .Pp The .Vt FTS structure contains space for a single pointer, which may be used to store application data or per-hierarchy state. The .Fn fts_set_clientptr and .Fn fts_get_clientptr functions may be used to set and retrieve this pointer. This is likely to be useful only when accessed from the sort comparison function, which can determine the original .Vt FTS stream of its arguments using the .Fn fts_get_stream function. The two .Li get functions are also available as macros of the same name. .Pp The .Vt FTSENT structure contains at least the following fields, which are described in greater detail below: .Bd -literal typedef struct _ftsent { int fts_info; /* status for FTSENT structure */ char *fts_accpath; /* access path */ char *fts_path; /* root path */ size_t fts_pathlen; /* strlen(fts_path) */ char *fts_name; /* file name */ size_t fts_namelen; /* strlen(fts_name) */ long fts_level; /* depth (\-1 to N) */ int fts_errno; /* file errno */ long long fts_number; /* local numeric value */ void *fts_pointer; /* local address value */ struct ftsent *fts_parent; /* parent directory */ struct ftsent *fts_link; /* next file structure */ struct ftsent *fts_cycle; /* cycle structure */ struct stat *fts_statp; /* stat(2) information */ } FTSENT; .Ed .Pp These fields are defined as follows: .Bl -tag -width "fts_namelen" .It Fa fts_info One of the following values describing the returned .Vt FTSENT structure and the file it represents. With the exception of directories without errors .Pq Dv FTS_D , all of these entries are terminal, that is, they will not be revisited, nor will any of their descendants be visited. .Bl -tag -width FTS_DEFAULT .It Dv FTS_D A directory being visited in pre-order. .It Dv FTS_DC A directory that causes a cycle in the tree. (The .Fa fts_cycle field of the .Vt FTSENT structure will be filled in as well.) .It Dv FTS_DEFAULT Any .Vt FTSENT structure that represents a file type not explicitly described by one of the other .Fa fts_info values. .It Dv FTS_DNR A directory which cannot be read. This is an error return, and the .Fa fts_errno field will be set to indicate what caused the error. .It Dv FTS_DOT A file named .Ql .\& or .Ql ..\& which was not specified as a file name to .Fn fts_open (see .Dv FTS_SEEDOT ) . .It Dv FTS_DP A directory being visited in post-order. The contents of the .Vt FTSENT structure will be unchanged from when the directory was visited in pre-order, except for the .Fa fts_info field. .It Dv FTS_ERR This is an error return, and the .Fa fts_errno field will be set to indicate what caused the error. .It Dv FTS_F A regular file. .It Dv FTS_NS A file for which no .Xr stat 2 information was available. The contents of the .Fa fts_statp field are undefined. This is an error return, and the .Fa fts_errno field will be set to indicate what caused the error. .It Dv FTS_NSOK A file for which no .Xr stat 2 information was requested. The contents of the .Fa fts_statp field are undefined. .It Dv FTS_SL A symbolic link. .It Dv FTS_SLNONE A symbolic link with a non-existent target. The contents of the .Fa fts_statp field reference the file characteristic information for the symbolic link itself. .El .It Fa fts_accpath A path for accessing the file from the current directory. .It Fa fts_path The path for the file relative to the root of the traversal. This path contains the path specified to .Fn fts_open as a prefix. .It Fa fts_pathlen The length of the string referenced by .Fa fts_path . .It Fa fts_name The name of the file. .It Fa fts_namelen The length of the string referenced by .Fa fts_name . .It Fa fts_level The depth of the traversal, numbered from \-1 to N, where this file was found. The .Vt FTSENT structure representing the parent of the starting point (or root) of the traversal is numbered .Dv FTS_ROOTPARENTLEVEL (\-1), and the .Vt FTSENT structure for the root itself is numbered .Dv FTS_ROOTLEVEL (0). .It Fa fts_errno Upon return of a .Vt FTSENT structure from the .Fn fts_children or .Fn fts_read functions, with its .Fa fts_info field set to .Dv FTS_DNR , .Dv FTS_ERR or .Dv FTS_NS , the .Fa fts_errno field contains the value of the external variable .Va errno specifying the cause of the error. Otherwise, the contents of the .Fa fts_errno field are undefined. .It Fa fts_number This field is provided for the use of the application program and is not modified by the .Nm functions. It is initialized to 0. .It Fa fts_pointer This field is provided for the use of the application program and is not modified by the .Nm functions. It is initialized to .Dv NULL . .It Fa fts_parent A pointer to the .Vt FTSENT structure referencing the file in the hierarchy immediately above the current file, i.e., the directory of which this file is a member. A parent structure for the initial entry point is provided as well, however, only the .Fa fts_level , .Fa fts_bignum , .Fa fts_number and .Fa fts_pointer fields are guaranteed to be initialized. .It Fa fts_link Upon return from the .Fn fts_children function, the .Fa fts_link field points to the next structure in the NULL-terminated linked list of directory members. Otherwise, the contents of the .Fa fts_link field are undefined. .It Fa fts_cycle If a directory causes a cycle in the hierarchy (see .Dv FTS_DC ) , either because of a hard link between two directories, or a symbolic link pointing to a directory, the .Fa fts_cycle field of the structure will point to the .Vt FTSENT structure in the hierarchy that references the same file as the current .Vt FTSENT structure. Otherwise, the contents of the .Fa fts_cycle field are undefined. .It Fa fts_statp A pointer to .Xr stat 2 information for the file. .El .Pp A single buffer is used for all of the paths of all of the files in the file hierarchy. Therefore, the .Fa fts_path and .Fa fts_accpath fields are guaranteed to be .Dv NUL Ns -terminated .Em only for the file most recently returned by .Fn fts_read . To use these fields to reference any files represented by other .Vt FTSENT structures will require that the path buffer be modified using the information contained in that .Vt FTSENT structure's .Fa fts_pathlen field. Any such modifications should be undone before further calls to .Fn fts_read are attempted. The .Fa fts_name field is always .Dv NUL Ns -terminated . .Pp Note that the use of .Fa fts_bignum is mutually exclusive with the use of .Fa fts_number or .Fa fts_pointer . .Sh FTS_OPEN The .Fn fts_open function takes a pointer to an array of character pointers naming one or more paths which make up a logical file hierarchy to be traversed. The array must be terminated by a .Dv NULL pointer. .Pp There are a number of options, at least one of which (either .Dv FTS_LOGICAL or .Dv FTS_PHYSICAL ) must be specified. The options are selected by .Em or Ns 'ing the following values: .Bl -tag -width "FTS_PHYSICAL" .It Dv FTS_COMFOLLOW This option causes any symbolic link specified as a root path to be followed immediately whether or not .Dv FTS_LOGICAL is also specified. .It Dv FTS_LOGICAL This option causes the .Nm routines to return .Vt FTSENT structures for the targets of symbolic links instead of the symbolic links themselves. If this option is set, the only symbolic links for which .Vt FTSENT structures are returned to the application are those referencing non-existent files. Either .Dv FTS_LOGICAL or .Dv FTS_PHYSICAL .Em must be provided to the .Fn fts_open function. .It Dv FTS_NOCHDIR To allow descending to arbitrary depths (independent of .Brq Dv PATH_MAX ) and improve performance, the .Nm functions change directories as they walk the file hierarchy. This has the side-effect that an application cannot rely on being in any particular directory during the traversal. The .Dv FTS_NOCHDIR option turns off this feature, and the .Nm functions will not change the current directory. Note that applications should not themselves change their current directory and try to access files unless .Dv FTS_NOCHDIR is specified and absolute pathnames were provided as arguments to .Fn fts_open . .It Dv FTS_NOSTAT By default, returned .Vt FTSENT structures reference file characteristic information (the .Fa statp field) for each file visited. This option relaxes that requirement as a performance optimization, allowing the .Nm functions to set the .Fa fts_info field to .Dv FTS_NSOK and leave the contents of the .Fa statp field undefined. .It Dv FTS_PHYSICAL This option causes the .Nm routines to return .Vt FTSENT structures for symbolic links themselves instead of the target files they point to. If this option is set, .Vt FTSENT structures for all symbolic links in the hierarchy are returned to the application. Either .Dv FTS_LOGICAL or .Dv FTS_PHYSICAL .Em must be provided to the .Fn fts_open function. .It Dv FTS_SEEDOT By default, unless they are specified as path arguments to .Fn fts_open , any files named .Ql .\& or .Ql ..\& encountered in the file hierarchy are ignored. This option causes the .Nm routines to return .Vt FTSENT structures for them. .It Dv FTS_XDEV This option prevents .Nm from descending into directories that have a different device number than the file from which the descent began. .El .Pp The argument .Fn compar specifies a user-defined function which may be used to order the traversal of the hierarchy. It takes two pointers to pointers to .Vt FTSENT structures as arguments and should return a negative value, zero, or a positive value to indicate if the file referenced by its first argument comes before, in any order with respect to, or after, the file referenced by its second argument. The .Fa fts_accpath , .Fa fts_path and .Fa fts_pathlen fields of the .Vt FTSENT structures may .Em never be used in this comparison. If the .Fa fts_info field is set to .Dv FTS_NS or .Dv FTS_NSOK , the .Fa fts_statp field may not either. If the .Fn compar argument is .Dv NULL , the directory traversal order is in the order listed in .Fa path_argv for the root paths, and in the order listed in the directory for everything else. .Sh FTS_READ The .Fn fts_read function returns a pointer to an .Vt FTSENT structure describing a file in the hierarchy. Directories (that are readable and do not cause cycles) are visited at least twice, once in pre-order and once in post-order. All other files are visited at least once. (Hard links between directories that do not cause cycles or symbolic links to symbolic links may cause files to be visited more than once, or directories more than twice.) .Pp If all the members of the hierarchy have been returned, .Fn fts_read returns .Dv NULL and sets the external variable .Va errno to 0. If an error unrelated to a file in the hierarchy occurs, .Fn fts_read returns .Dv NULL and sets .Va errno appropriately. If an error related to a returned file occurs, a pointer to an .Vt FTSENT structure is returned, and .Va errno may or may not have been set (see .Fa fts_info ) . .Pp The .Vt FTSENT structures returned by .Fn fts_read may be overwritten after a call to .Fn fts_close on the same file hierarchy stream, or, after a call to .Fn fts_read on the same file hierarchy stream unless they represent a file of type directory, in which case they will not be overwritten until after a call to .Fn fts_read after the .Vt FTSENT structure has been returned by the function .Fn fts_read in post-order. .Sh FTS_CHILDREN The .Fn fts_children function returns a pointer to an .Vt FTSENT structure describing the first entry in a NULL-terminated linked list of the files in the directory represented by the .Vt FTSENT structure most recently returned by .Fn fts_read . The list is linked through the .Fa fts_link field of the .Vt FTSENT structure, and is ordered by the user-specified comparison function, if any. Repeated calls to .Fn fts_children will recreate this linked list. .Pp As a special case, if .Fn fts_read has not yet been called for a hierarchy, .Fn fts_children will return a pointer to the files in the logical directory specified to .Fn fts_open , i.e., the arguments specified to .Fn fts_open . Otherwise, if the .Vt FTSENT structure most recently returned by .Fn fts_read is not a directory being visited in pre-order, or the directory does not contain any files, .Fn fts_children returns .Dv NULL and sets .Va errno to zero. If an error occurs, .Fn fts_children returns .Dv NULL and sets .Va errno appropriately. .Pp The .Vt FTSENT structures returned by .Fn fts_children may be overwritten after a call to .Fn fts_children , .Fn fts_close or .Fn fts_read on the same file hierarchy stream. .Pp .Em Option may be set to the following value: .Bl -tag -width FTS_NAMEONLY .It Dv FTS_NAMEONLY Only the names of the files are needed. The contents of all the fields in the returned linked list of structures are undefined with the exception of the .Fa fts_name and .Fa fts_namelen fields. .El .Sh FTS_SET The function .Fn fts_set allows the user application to determine further processing for the file .Fa f of the stream .Fa ftsp . The .Fn fts_set function returns 0 on success, and \-1 if an error occurs. .Em Option must be set to one of the following values: .Bl -tag -width FTS_PHYSICAL .It Dv FTS_AGAIN Re-visit the file; any file type may be re-visited. The next call to .Fn fts_read will return the referenced file. The .Fa fts_stat and .Fa fts_info fields of the structure will be reinitialized at that time, but no other fields will have been changed. This option is meaningful only for the most recently returned file from .Fn fts_read . Normal use is for post-order directory visits, where it causes the directory to be re-visited (in both pre and post-order) as well as all of its descendants. .It Dv FTS_FOLLOW The referenced file must be a symbolic link. If the referenced file is the one most recently returned by .Fn fts_read , the next call to .Fn fts_read returns the file with the .Fa fts_info and .Fa fts_statp fields reinitialized to reflect the target of the symbolic link instead of the symbolic link itself. If the file is one of those most recently returned by .Fn fts_children , the .Fa fts_info and .Fa fts_statp fields of the structure, when returned by .Fn fts_read , will reflect the target of the symbolic link instead of the symbolic link itself. In either case, if the target of the symbolic link does not exist the fields of the returned structure will be unchanged and the .Fa fts_info field will be set to .Dv FTS_SLNONE . .Pp If the target of the link is a directory, the pre-order return, followed by the return of all of its descendants, followed by a post-order return, is done. .It Dv FTS_SKIP No descendants of this file are visited. The file may be one of those most recently returned by either .Fn fts_children or .Fn fts_read . .El .Sh FTS_CLOSE The .Fn fts_close function closes a file hierarchy stream .Fa ftsp and restores the current directory to the directory from which .Fn fts_open was called to open .Fa ftsp . The .Fn fts_close function returns 0 on success, and \-1 if an error occurs. .Sh ERRORS The function .Fn fts_open may fail and set .Va errno for any of the errors specified for the library functions .Xr open 2 and .Xr malloc 3 . .Pp The function .Fn fts_close may fail and set .Va errno for any of the errors specified for the library functions .Xr chdir 2 and .Xr close 2 . .Pp The functions .Fn fts_read and .Fn fts_children may fail and set .Va errno for any of the errors specified for the library functions .Xr chdir 2 , .Xr malloc 3 , .Xr opendir 3 , .Xr readdir 3 and .Xr stat 2 . .Pp In addition, .Fn fts_children , .Fn fts_open and .Fn fts_set may fail and set .Va errno as follows: .Bl -tag -width Er .It Bq Er EINVAL The options were invalid, or the list were empty. .El .Sh SEE ALSO .Xr find 1 , .Xr chdir 2 , .Xr stat 2 , .Xr ftw 3 , .Xr qsort 3 .Sh HISTORY The .Nm interface was first introduced in .Bx 4.4 . The .Fn fts_get_clientptr , .Fn fts_get_stream , and .Fn fts_set_clientptr functions were introduced in .Fx 5.0 , principally to provide for alternative interfaces to the .Nm functionality using different data structures. .Sh BUGS -The +The .Fn fts_open function will automatically set the .Dv FTS_NOCHDIR -option if the +option if the .Dv FTS_LOGICAL -option is provided, or if it cannot +option is provided, or if it cannot .Xr open 2 the current directory. Index: stable/9/lib/libc/gen/getpagesizes.3 =================================================================== --- stable/9/lib/libc/gen/getpagesizes.3 (revision 237215) +++ stable/9/lib/libc/gen/getpagesizes.3 (revision 237216) @@ -1,99 +1,99 @@ .\" Copyright (c) 2009 Alan L. Cox .\" 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. .\" .\" $FreeBSD$ .\" .Dd September 21, 2009 .Dt GETPAGESIZES 3 .Os .Sh NAME .Nm getpagesizes .Nd "get system page sizes" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/mman.h .Ft int .Fn getpagesizes "size_t pagesize[]" "int nelem" .Sh DESCRIPTION The .Fn getpagesizes function retrieves page size information from the system. When it is called with .Fa pagesize specified as .Dv NULL and .Fa nelem specified as 0, it returns the number of distinct page sizes that are supported by the system. Otherwise, it assigns up to .Fa nelem of the system-supported page sizes to consecutive elements of the array referenced by .Fa pagesize . These page sizes are expressed in bytes. In this case, .Fn getpagesizes -returns the number of such page sizes that it assigned to the array. +returns the number of such page sizes that it assigned to the array. .Sh RETURN VALUES If successful, the .Fn getpagesizes function returns either the number of page sizes that are supported by the system or the number of supported page sizes that it assigned to the array referenced by .Fa pagesize . Otherwise, it returns the value\~\-1 and sets .Va errno to indicate the error. .Sh ERRORS The .Fn getpagesizes function will succeed unless: .Bl -tag -width Er .It Bq Er EINVAL The .Fa pagesize argument is .Dv NULL and the .Fa nelem argument is non-zero. .It Bq Er EINVAL The .Fa nelem argument is less than zero. .El .Sh SEE ALSO .Xr getpagesize 3 .Sh HISTORY The .Fn getpagesizes function first appeared in Solaris 9. This manual page was written in conjunction with a new but compatible implementation that was first released in .Fx 7.3 . .Sh AUTHORS This manual page was written by .An Alan L. Cox Aq alc@cs.rice.edu . Index: stable/9/lib/libc/gen/sysconf.3 =================================================================== --- stable/9/lib/libc/gen/sysconf.3 (revision 237215) +++ stable/9/lib/libc/gen/sysconf.3 (revision 237216) @@ -1,276 +1,276 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)sysconf.3 8.3 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd February 13, 2011 .Dt SYSCONF 3 .Os .Sh NAME .Nm sysconf .Nd get configurable system variables .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft long .Fn sysconf "int name" .Sh DESCRIPTION This interface is defined by .St -p1003.1-88 . A far more complete interface is available using .Xr sysctl 3 . .Pp The .Fn sysconf function provides a method for applications to determine the current value of a configurable system limit or option variable. The .Fa name argument specifies the system variable to be queried. Symbolic constants for each name value are found in the include file .In unistd.h . Shell programmers who need access to these parameters should use the .Xr getconf 1 utility. .Pp The available values are as follows: .Bl -tag -width 6n .It Li _SC_ARG_MAX The maximum bytes of argument to .Xr execve 2 . .It Li _SC_CHILD_MAX The maximum number of simultaneous processes per user id. .It Li _SC_CLK_TCK The frequency of the statistics clock in ticks per second. .It Li _SC_IOV_MAX The maximum number of elements in the I/O vector used by .Xr readv 2 , .Xr writev 2 , .Xr recvmsg 2 , and .Xr sendmsg 2 . .It Li _SC_NGROUPS_MAX The maximum number of supplemental groups. .It Li _SC_NPROCESSORS_CONF The number of processors configured. .It Li _SC_NPROCESSORS_ONLN The number of processors currently online. .It Li _SC_OPEN_MAX The maximum number of open files per user id. .It Li _SC_PAGESIZE The size of a system page in bytes. .It Li _SC_PAGE_SIZE Equivalent to .Li _SC_PAGESIZE . .It Li _SC_STREAM_MAX The minimum maximum number of streams that a process may have open at any one time. .It Li _SC_TZNAME_MAX The minimum maximum number of types supported for the name of a timezone. .It Li _SC_JOB_CONTROL Return 1 if job control is available on this system, otherwise \-1. .It Li _SC_SAVED_IDS Returns 1 if saved set-group and saved set-user ID is available, otherwise \-1. .It Li _SC_VERSION The version of .St -p1003.1 with which the system attempts to comply. .It Li _SC_BC_BASE_MAX The maximum ibase/obase values in the .Xr bc 1 utility. .It Li _SC_BC_DIM_MAX The maximum array size in the .Xr bc 1 utility. .It Li _SC_BC_SCALE_MAX The maximum scale value in the .Xr bc 1 utility. .It Li _SC_BC_STRING_MAX The maximum string length in the .Xr bc 1 utility. .It Li _SC_COLL_WEIGHTS_MAX The maximum number of weights that can be assigned to any entry of the LC_COLLATE order keyword in the locale definition file. .It Li _SC_EXPR_NEST_MAX The maximum number of expressions that can be nested within parenthesis by the .Xr expr 1 utility. .It Li _SC_LINE_MAX The maximum length in bytes of a text-processing utility's input line. .It Li _SC_RE_DUP_MAX The maximum number of repeated occurrences of a regular expression permitted when using interval notation. .It Li _SC_2_VERSION The version of .St -p1003.2 with which the system attempts to comply. .It Li _SC_2_C_BIND Return 1 if the system's C-language development facilities support the C-Language Bindings Option, otherwise \-1. .It Li _SC_2_C_DEV Return 1 if the system supports the C-Language Development Utilities Option, otherwise \-1. .It Li _SC_2_CHAR_TERM Return 1 if the system supports at least one terminal type capable of all operations described in .St -p1003.2 , otherwise \-1. .It Li _SC_2_FORT_DEV Return 1 if the system supports the FORTRAN Development Utilities Option, otherwise \-1. .It Li _SC_2_FORT_RUN Return 1 if the system supports the FORTRAN Runtime Utilities Option, otherwise \-1. .It Li _SC_2_LOCALEDEF Return 1 if the system supports the creation of locales, otherwise \-1. .It Li _SC_2_SW_DEV Return 1 if the system supports the Software Development Utilities Option, otherwise \-1. .It Li _SC_2_UPE Return 1 if the system supports the User Portability Utilities Option, otherwise \-1. .It Li _SC_AIO_LISTIO_MAX Maximum number of I/O operations in a single list I/O call supported. .It Li _SC_AIO_MAX Maximum number of outstanding asynchronous I/O operations supported. .It Li _SC_AIO_PRIO_DELTA_MAX The maximum amount by which a process can decrease its asynchronous I/O priority level from its own scheduling priority. .It Li _SC_DELAYTIMER_MAX Maximum number of timer expiration overruns. .It Li _SC_MQ_OPEN_MAX The maximum number of open message queue descriptors a process may hold. .It Li _SC_RTSIG_MAX Maximum number of realtime signals reserved for application use. .It Li _SC_SEM_NSEMS_MAX Maximum number of semaphores that a process may have. .It Li _SC_SEM_VALUE_MAX The maximum value a semaphore may have. .It Li _SC_SIGQUEUE_MAX Maximum number of queued signals that a process may send and have pending at the receiver(s) at any time. .It Li _SC_TIMER_MAX Maximum number of timers per process supported. .It Li _SC_GETGR_R_SIZE_MAX Suggested initial value for the size of the group entry buffer. .It Li _SC_GETPW_R_SIZE_MAX Suggested initial value for the size of the password entry buffer. .It Li _SC_HOST_NAME_MAX Maximum length of a host name (not including the terminating null) as returned from the .Fn gethostname function. .It Li _SC_LOGIN_NAME_MAX Maximum length of a login name. .It Li _SC_THREAD_STACK_MIN Minimum size in bytes of thread stack storage. .It Li _SC_THREAD_THREADS_MAX Maximum number of threads that can be created per process. .It Li _SC_TTY_NAME_MAX Maximum length of terminal device name. .It Li _SC_SYMLOOP_MAX Maximum number of symbolic links that can be reliably traversed in the resolution of a pathname in the absence of a loop. .It Li _SC_ATEXIT_MAX Maximum number of functions that may be registered with .Fn atexit . .It Li _SC_XOPEN_VERSION An integer value greater than or equal to 4, indicating the version of the X/Open Portability Guide to which this -system conforms. +system conforms. .It Li _SC_XOPEN_XCU_VERSION An integer value indicating the version of the XCU Specification to which this system conforms. .El .Pp These values also exist, but may not be standard: .Bl -tag -width 6n .It Li _SC_CPUSET_SIZE Size of the kernel cpuset. .It Li _SC_PHYS_PAGES The number of pages of physical memory. Note that it is possible that the product of this value and the value of .Li _SC_PAGESIZE will overflow a .Vt long in some configurations on a 32bit machine. .El .Sh RETURN VALUES If the call to .Fn sysconf is not successful, \-1 is returned and .Va errno is set appropriately. Otherwise, if the variable is associated with functionality that is not supported, \-1 is returned and .Va errno is not modified. Otherwise, the current variable value is returned. .Sh ERRORS The .Fn sysconf function may fail and set .Va errno for any of the errors specified for the library function .Xr sysctl 3 . In addition, the following error may be reported: .Bl -tag -width Er .It Bq Er EINVAL The value of the .Fa name argument is invalid. .El .Sh SEE ALSO .Xr getconf 1 , .Xr pathconf 2 , .Xr confstr 3 , .Xr sysctl 3 .Sh STANDARDS Except for the fact that values returned by .Fn sysconf may change over the lifetime of the calling process, this function conforms to .St -p1003.1-88 . .Sh HISTORY The .Fn sysconf function first appeared in .Bx 4.4 . .Sh BUGS The value for _SC_STREAM_MAX is a minimum maximum, and required to be the same as ANSI C's FOPEN_MAX, so the returned value is a ridiculously small and misleading number. Index: stable/9/lib/libc/locale/ctype.3 =================================================================== --- stable/9/lib/libc/locale/ctype.3 (revision 237215) +++ stable/9/lib/libc/locale/ctype.3 (revision 237216) @@ -1,151 +1,151 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)ctype.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd March 30, 2004 .Dt CTYPE 3 .Os .Sh NAME .Nm digittoint , .Nm isalnum , .Nm isalpha , .Nm isascii , .Nm isblank , .Nm iscntrl , .Nm isdigit , .Nm isgraph , .Nm ishexnumber , .Nm isideogram , .Nm islower , .Nm isnumber , .Nm isphonogram , .Nm isprint , .Nm ispunct , .Nm isrune , .Nm isspace , .Nm isspecial , .Nm isupper , .Nm isxdigit , .Nm toascii , .Nm tolower , .Nm toupper -.Nd character classification functions +.Nd character classification functions .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn digittoint "int c" .Ft int .Fn isalnum "int c" .Ft int .Fn isalpha "int c" .Ft int .Fn isascii "int c" .Ft int .Fn iscntrl "int c" .Ft int .Fn isdigit "int c" .Ft int .Fn isgraph "int c" .Ft int .Fn ishexnumber "int c" .Ft int .Fn isideogram "int c" .Ft int .Fn islower "int c" .Ft int .Fn isnumber "int c" .Ft int .Fn isphonogram "int c" .Ft int .Fn isspecial "int c" .Ft int .Fn isprint "int c" .Ft int .Fn ispunct "int c" .Ft int .Fn isrune "int c" .Ft int .Fn isspace "int c" .Ft int .Fn isupper "int c" .Ft int .Fn isxdigit "int c" .Ft int .Fn toascii "int c" .Ft int .Fn tolower "int c" .Ft int .Fn toupper "int c" .Sh DESCRIPTION The above functions perform character tests and conversions on the integer .Fa c . They are available as macros, defined in the include file .In ctype.h , or as true functions in the C library. See the specific manual pages for more information. .Sh SEE ALSO .Xr digittoint 3 , .Xr isalnum 3 , .Xr isalpha 3 , .Xr isascii 3 , .Xr isblank 3 , .Xr iscntrl 3 , .Xr isdigit 3 , .Xr isgraph 3 , .Xr isideogram 3 , .Xr islower 3 , .Xr isphonogram 3 , .Xr isprint 3 , .Xr ispunct 3 , .Xr isrune 3 , .Xr isspace 3 , .Xr isspecial 3 , .Xr isupper 3 , .Xr isxdigit 3 , .Xr toascii 3 , .Xr tolower 3 , .Xr toupper 3 , .Xr wctype 3 , .Xr ascii 7 .Sh STANDARDS These functions, except for .Fn digittoint , .Fn isascii , .Fn ishexnumber , .Fn isideogram , .Fn isnumber , .Fn isphonogram , .Fn isrune , .Fn isspecial and .Fn toascii , conform to .St -isoC . Index: stable/9/lib/libc/locale/ctype_l.3 =================================================================== --- stable/9/lib/libc/locale/ctype_l.3 (revision 237215) +++ stable/9/lib/libc/locale/ctype_l.3 (revision 237216) @@ -1,138 +1,138 @@ .\" Copyright (c) 2011 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by David Chisnall 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 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. .\" .\" $FreeBSD$ .\" .Dd March 6, 2012 .Dt CTYPE_L 3 .Os .Sh NAME .Nm digittoint_l , .Nm isalnum_l , .Nm isalpha_l , .Nm isascii_l , .Nm isblank_l , .Nm iscntrl_l , .Nm isdigit_l , .Nm isgraph_l , .Nm ishexnumber_l , .Nm isideogram_l , .Nm islower_l , .Nm isnumber_l , .Nm isphonogram_l , .Nm isprint_l , .Nm ispunct_l , .Nm isrune_l , .Nm isspace_l , .Nm isspecial_l , .Nm isupper_l , .Nm isxdigit_l , .Nm tolower_l , .Nm toupper_l .Nd character classification functions .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn digittoint_l "int c" "locale_t loc" .Ft int .Fn isalnum_l "int c" "locale_t loc" .Ft int .Fn isalpha_l "int c" "locale_t loc" .Ft int .Fn isascii_l "int c" "locale_t loc" .Ft int .Fn iscntrl_l "int c" "locale_t loc" .Ft int .Fn isdigit_l "int c" "locale_t loc" .Ft int .Fn isgraph_l "int c" "locale_t loc" .Ft int .Fn ishexnumber_l "int c" "locale_t loc" .Ft int .Fn isideogram_l "int c" "locale_t loc" .Ft int .Fn islower_l "int c" "locale_t loc" .Ft int .Fn isnumber_l "int c" "locale_t loc" .Ft int .Fn isphonogram_l "int c" "locale_t loc" .Ft int .Fn isspecial_l "int c" "locale_t loc" .Ft int .Fn isprint_l "int c" "locale_t loc" .Ft int .Fn ispunct_l "int c" "locale_t loc" .Ft int .Fn isrune_l "int c" "locale_t loc" .Ft int .Fn isspace_l "int c" "locale_t loc" .Ft int .Fn isupper_l "int c" "locale_t loc" .Ft int .Fn isxdigit_l "int c" "locale_t loc" .Ft int .Fn tolower_l "int c" "locale_t loc" .Ft int .Fn toupper_l "int c" "locale_t loc" .Sh DESCRIPTION The above functions perform character tests and conversions on the integer -.Fa c +.Fa c in the locale .Fa loc . They behave in the same way as the versions without the _l suffix, but use the -specified locale rather than the global or per-thread locale. +specified locale rather than the global or per-thread locale. .In ctype.h , or as true functions in the C library. See the specific manual pages for more information. .Sh SEE ALSO .Xr digittoint 3 , .Xr isalnum 3 , .Xr isalpha 3 , .Xr isascii 3 , .Xr isblank 3 , .Xr iscntrl 3 , .Xr isdigit 3 , .Xr isgraph 3 , .Xr isideogram 3 , .Xr islower 3 , .Xr isphonogram 3 , .Xr isprint 3 , .Xr ispunct 3 , .Xr isrune 3 , .Xr isspace 3 , .Xr isspecial 3 , .Xr isupper 3 , .Xr isxdigit 3 , .Xr tolower 3 , .Xr toupper 3 , .Xr wctype 3 , .Xr xlocale 3 .Sh STANDARDS These functions conform to .St -p1003.1-2008 . Index: stable/9/lib/libc/locale/digittoint.3 =================================================================== --- stable/9/lib/libc/locale/digittoint.3 (revision 237215) +++ stable/9/lib/libc/locale/digittoint.3 (revision 237216) @@ -1,68 +1,68 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)digittoint.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd April 6, 2001 .Dt DIGITTOINT 3 .Os .Sh NAME .Nm digittoint .Nd convert a numeric character to its integer value .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn digittoint "int c" .Ft int .Fn digittoint_l "int c" "locale_t loc" .Sh DESCRIPTION The .Fn digittoint function converts a numeric character to its corresponding integer value. The character can be any decimal digit or hexadecimal digit. With hexadecimal characters, the case of the values does not matter. .Pp -The +The .Fn digittoint_l function takes an explicit locale argument, whereas the .Fn digittoint function use the current global or per-thread locale. .Sh RETURN VALUES The .Fn digittoint function always returns an integer from the range of 0 to 15. If the given character was not a digit as defined by .Xr isxdigit 3 , the function will return 0. .Sh SEE ALSO .Xr ctype 3 , .Xr isdigit 3 , .Xr isxdigit 3, .Xr xlocale 3 Index: stable/9/lib/libc/locale/isalnum.3 =================================================================== --- stable/9/lib/libc/locale/isalnum.3 (revision 237215) +++ stable/9/lib/libc/locale/isalnum.3 (revision 237216) @@ -1,115 +1,115 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)isalnum.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 17, 2005 .Dt ISALNUM 3 .Os .Sh NAME .Nm isalnum .Nd alphanumeric character test .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn isalnum "int c" .Ft int .Fn isalnum_l "int c" "locale_t loc" .Sh DESCRIPTION The .Fn isalnum function tests for any character for which .Xr isalpha 3 or .Xr isdigit 3 is true. The value of the argument must be representable as an .Vt "unsigned char" or the value of .Dv EOF . .Pp In the ASCII character set, this includes the following characters (with their numeric values shown in octal): .Bl -column \&000_``0''__ \&000_``0''__ \&000_``0''__ \&000_``0''__ \&000_``0''__ .It "\&060\ ``0'' \t061\ ``1'' \t062\ ``2'' \t063\ ``3'' \t064\ ``4''" .It "\&065\ ``5'' \t066\ ``6'' \t067\ ``7'' \t070\ ``8'' \t071\ ``9''" .It "\&101\ ``A'' \t102\ ``B'' \t103\ ``C'' \t104\ ``D'' \t105\ ``E''" .It "\&106\ ``F'' \t107\ ``G'' \t110\ ``H'' \t111\ ``I'' \t112\ ``J''" .It "\&113\ ``K'' \t114\ ``L'' \t115\ ``M'' \t116\ ``N'' \t117\ ``O''" .It "\&120\ ``P'' \t121\ ``Q'' \t122\ ``R'' \t123\ ``S'' \t124\ ``T''" .It "\&125\ ``U'' \t126\ ``V'' \t127\ ``W'' \t130\ ``X'' \t131\ ``Y''" .It "\&132\ ``Z'' \t141\ ``a'' \t142\ ``b'' \t143\ ``c'' \t144\ ``d''" .It "\&145\ ``e'' \t146\ ``f'' \t147\ ``g'' \t150\ ``h'' \t151\ ``i''" .It "\&152\ ``j'' \t153\ ``k'' \t154\ ``l'' \t155\ ``m'' \t156\ ``n''" .It "\&157\ ``o'' \t160\ ``p'' \t161\ ``q'' \t162\ ``r'' \t163\ ``s''" .It "\&164\ ``t'' \t165\ ``u'' \t166\ ``v'' \t167\ ``w'' \t170\ ``x''" .It "\&171\ ``y'' \t172\ ``z''" .El .Pp -The +The .Fn isalnum_l function takes an explicit locale argument, whereas the .Fn isalnum function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn isalnum function returns zero if the character tests false and returns non-zero if the character tests true. .Sh COMPATIBILITY The .Bx 4.4 extension of accepting arguments outside of the range of the .Vt "unsigned char" type in locales with large character sets is considered obsolete and may not be supported in future releases. The .Fn iswalnum function should be used instead. .Sh SEE ALSO .Xr ctype 3 , .Xr isalpha 3 , .Xr isdigit 3 , .Xr iswalnum 3 , .Xr xlocale 3 , .Xr ascii 7 .Sh STANDARDS The .Fn isalnum function conforms to .St -isoC . The .Fn isalnum_l function conforms to .St -p1003.1-2008 . Index: stable/9/lib/libc/locale/isalpha.3 =================================================================== --- stable/9/lib/libc/locale/isalpha.3 (revision 237215) +++ stable/9/lib/libc/locale/isalpha.3 (revision 237216) @@ -1,113 +1,113 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)isalpha.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 17, 2005 .Dt ISALPHA 3 .Os .Sh NAME .Nm isalpha .Nd alphabetic character test .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn isalpha "int c" .Ft int .Fn isalpha_l "int c" "locale_t loc" .Sh DESCRIPTION The .Fn isalpha function tests for any character for which .Xr isupper 3 or .Xr islower 3 is true. The value of the argument must be representable as an .Vt "unsigned char" or the value of .Dv EOF . .Pp In the ASCII character set, this includes the following characters (with their numeric values shown in octal): .Bl -column \&000_``0''__ \&000_``0''__ \&000_``0''__ \&000_``0''__ \&000_``0''__ .It "\&101\ ``A'' \t102\ ``B'' \t103\ ``C'' \t104\ ``D'' \t105\ ``E''" .It "\&106\ ``F'' \t107\ ``G'' \t110\ ``H'' \t111\ ``I'' \t112\ ``J''" .It "\&113\ ``K'' \t114\ ``L'' \t115\ ``M'' \t116\ ``N'' \t117\ ``O''" .It "\&120\ ``P'' \t121\ ``Q'' \t122\ ``R'' \t123\ ``S'' \t124\ ``T''" .It "\&125\ ``U'' \t126\ ``V'' \t127\ ``W'' \t130\ ``X'' \t131\ ``Y''" .It "\&132\ ``Z'' \t141\ ``a'' \t142\ ``b'' \t143\ ``c'' \t144\ ``d''" .It "\&145\ ``e'' \t146\ ``f'' \t147\ ``g'' \t150\ ``h'' \t151\ ``i''" .It "\&152\ ``j'' \t153\ ``k'' \t154\ ``l'' \t155\ ``m'' \t156\ ``n''" .It "\&157\ ``o'' \t160\ ``p'' \t161\ ``q'' \t162\ ``r'' \t163\ ``s''" .It "\&164\ ``t'' \t165\ ``u'' \t166\ ``v'' \t167\ ``w'' \t170\ ``x''" .It "\&171\ ``y'' \t172\ ``z''" .El -The +The .Fn isalpha_l function takes an explicit locale argument, whereas the .Fn isalpha function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn isalpha function returns zero if the character tests false and returns non-zero if the character tests true. .Sh COMPATIBILITY The .Bx 4.4 extension of accepting arguments outside of the range of the .Vt "unsigned char" type in locales with large character sets is considered obsolete and may not be supported in future releases. The .Fn iswalpha function should be used instead. .Sh SEE ALSO .Xr ctype 3 , .Xr islower 3 , .Xr isupper 3 , .Xr iswalpha 3 , .Xr xlocale 3 , .Xr ascii 7 .Sh STANDARDS The .Fn isalpha function conforms to .St -isoC . The .Fn isalpha_l function conforms to .St -p1003.1-2008 . Index: stable/9/lib/libc/locale/isblank.3 =================================================================== --- stable/9/lib/libc/locale/isblank.3 (revision 237215) +++ stable/9/lib/libc/locale/isblank.3 (revision 237216) @@ -1,96 +1,96 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)isblank.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 17, 2005 .Dt ISBLANK 3 .Os .Sh NAME .Nm isblank .Nd space or tab character test .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn isblank "int c" .Ft int .Fn isblank "int c" "locale_t loc" .Sh DESCRIPTION The .Fn isblank function tests for a space or tab character. For any locale, this includes the following standard characters: .Bl -column XXXX .It Do \et Dc Ta Dq " " .El .Pp In the "C" locale, a successful .Fn isblank test is limited to these characters only. The value of the argument must be representable as an .Vt "unsigned char" or the value of .Dv EOF . .Pp -The +The .Fn isblank_l function takes an explicit locale argument, whereas the .Fn isblank function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn isblank function returns zero if the character tests false and returns non-zero if the character tests true. .Sh COMPATIBILITY The .Bx 4.4 extension of accepting arguments outside of the range of the .Vt "unsigned char" type in locales with large character sets is considered obsolete and may not be supported in future releases. The .Fn iswblank function should be used instead. .Sh SEE ALSO .Xr ctype 3 , .Xr iswblank 3 , .Xr xlocale 3 , .Xr ascii 7 .Sh STANDARDS The .Fn isblank function conforms to .St -isoC-99 . The .Fn isblank_l function conforms to .St -p1003.1-2008 . Index: stable/9/lib/libc/locale/iscntrl.3 =================================================================== --- stable/9/lib/libc/locale/iscntrl.3 (revision 237215) +++ stable/9/lib/libc/locale/iscntrl.3 (revision 237216) @@ -1,104 +1,104 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)iscntrl.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 17, 2005 .Dt ISCNTRL 3 .Os .Sh NAME .Nm iscntrl .Nd control character test .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn iscntrl "int c" .Ft int .Fn iscntrl_l "int c" "locale_t loc" .Sh DESCRIPTION The .Fn iscntrl function tests for any control character. The value of the argument must be representable as an .Vt "unsigned char" or the value of .Dv EOF . .Pp In the ASCII character set, this includes the following characters (with their numeric values shown in octal): .Pp .Bl -column \&000_``0''__ \&000_``0''__ \&000_``0''__ \&000_``0''__ \&000_``0''__ .It "\&000\ NUL \t001\ SOH \t002\ STX \t003\ ETX \t004\ EOT" .It "\&005\ ENQ \t006\ ACK \t007\ BEL \t010\ BS \t011\ HT" .It "\&012\ NL \t013\ VT \t014\ NP \t015\ CR \t016\ SO" .It "\&017\ SI \t020\ DLE \t021\ DC1 \t022\ DC2 \t023\ DC3" .It "\&024\ DC4 \t025\ NAK \t026\ SYN \t027\ ETB \t030\ CAN" .It "\&031\ EM \t032\ SUB \t033\ ESC \t034\ FS \t035\ GS" .It "\&036\ RS \t037\ US \t177\ DEL" .El .Pp -The +The .Fn iscntrl_l function takes an explicit locale argument, whereas the .Fn iscntrl function uses the current global or per-thread locale. .Sh RETURN VALUES The .Fn iscntrl function returns zero if the character tests false and returns non-zero if the character tests true. .Sh COMPATIBILITY The .Bx 4.4 extension of accepting arguments outside of the range of the .Vt "unsigned char" type in locales with large character sets is considered obsolete and may not be supported in future releases. The .Fn iswcntrl function should be used instead. .Sh SEE ALSO .Xr ctype 3 , .Xr iswcntrl 3 , .Xr xlocale 3 , .Xr ascii 7 .Sh STANDARDS The .Fn iscntrl function conforms to .St -isoC . The .Fn iscntrl_l function conforms to .St -p1003.1-2008 . Index: stable/9/lib/libc/net/sctp_bindx.3 =================================================================== --- stable/9/lib/libc/net/sctp_bindx.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_bindx.3 (revision 237216) @@ -1,114 +1,114 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_BINDX 3 .Os .Sh NAME .Nm sctp_bindx .Nd bind or unbind an SCTP socket to a list of addresses. .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft int .Fn sctp_bindx "int s" "struct sockaddr *addrs" "int num" "int type" .Sh DESCRIPTION The .Fn sctp_bindx call binds or unbinds a address or a list of addresses to an SCTP endpoint. This allows a user to bind a subset of addresses. The .Fn sctp_bindx -call operates similarly to +call operates similarly to .Fn bind but allows a list of addresses and also allows a bind or an unbind. The argument .Fa s must be a valid SCTP socket descriptor. The argument .Fa addrs is a list of addresses (where the list may be only 1 in length) that the user wishes to bind or unbind to the socket. The argument .Fa type must be one of the following values. .Pp .Dv SCTP_BINDX_ADD_ADDR This value indicates that the listed address(es) need to be added to the endpoint. .Pp .Dv SCTP_BINDX_DEL_ADDR This value indicates that the listed address(es) need to be removed from the endpoint. .Pp Note that when a user adds or deletes an address to an association if the dynamic address flag .Va net.inet.sctp.auto_asconf is enabled any associations in the endpoint will attempt to have the address(es) added dynamically to the existing association. .Sh RETURN VALUES The call returns 0 on success and -1 upon failure. .Sh ERRORS The .Fn sctp_bindx function can return the following errors: .Bl -tag -width Er .It Bq Er EINVAL This value is returned if the .Fa type field is not one of the allowed values (see above). .It Bq Er ENOMEM This value is returned if the number of addresses -being added causes a memory allocation failure in +being added causes a memory allocation failure in the call. .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .El .Sh SEE ALSO .Xr bind 2 , .Xr sctp 4 Index: stable/9/lib/libc/net/sctp_connectx.3 =================================================================== --- stable/9/lib/libc/net/sctp_connectx.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_connectx.3 (revision 237216) @@ -1,106 +1,106 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd June 19, 2007 .Dt SCTP_CONNECTX 3 .Os .Sh NAME .Nm sctp_connectx .Nd connect an SCTP socket with multiple destination addresses .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft int .Fn sctp_connectx "int sd" "struct sockaddr *addrs" "int addrcnt" "sctp_assoc_t *id" .Sh DESCRIPTION The .Fn sctp_connectx call attempts to initiate an association to a peer SCTP endpoint. The call operates similarly to .Fn connect but it also provides the ability to specify multiple destination addresses for the peer. This allows a fault tolerant method of initiating an association. When one of the peers addresses is unreachable, the subsequent listed addresses will also be used -to set up the association with the peer. +to set up the association with the peer. .Pp -The user also needs to consider that any address listed in an +The user also needs to consider that any address listed in an .Fn sctp_connectx call is also considered "confirmed". A confirmed address is one in which the SCTP transport will trust is a part of the association and it will not send a confirmation heartbeat to it with -a random nonce. +a random nonce. .Pp If the peer SCTP stack does not list one or more of -the provided addresses in its response message then +the provided addresses in its response message then the extra addresses sent in the .Fn sctp_connectx call will be silently discarded from the association. On successful completion the provided .Fa id will be filled in with the association identification of the newly forming association. .Sh RETURN VALUES The call returns 0 on success and -1 upon failure. .Sh ERRORS The .Fn sctp_connectx function can return the following errors: .Bl -tag -width Er .It Bq Er EINVAL An address listed has an invalid family or no addresses were provided. .It Bq Er E2BIG The size of the address list exceeds the amount of data provided. .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .El .Sh SEE ALSO .Xr connect 2 , .Xr sctp 4 Index: stable/9/lib/libc/net/sctp_freepaddrs.3 =================================================================== --- stable/9/lib/libc/net/sctp_freepaddrs.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_freepaddrs.3 (revision 237216) @@ -1,68 +1,68 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_FREEPADDRS 3 .Os .Sh NAME .Nm sctp_freepaddrs , .Nm sctp_freeladdrs .Nd release the memory returned from a previous call .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft void -.Fn sctp_freepaddrs "struct sockaddr *" +.Fn sctp_freepaddrs "struct sockaddr *" .Ft void -.Fn sctp_freeladdrs "struct sockaddr *" +.Fn sctp_freeladdrs "struct sockaddr *" .Sh DESCRIPTION The .Fn sctp_freepaddrs and .Fn sctp_freeladdrs functions are used to release the memory allocated by previous calls to .Fn sctp_getpaddrs or .Fn sctp_getladdrs respectively. .Sh RETURN VALUES none. .Sh SEE ALSO .Xr sctp_getladdrs 3 , .Xr sctp_getpaddrs 3 , .Xr sctp 4 Index: stable/9/lib/libc/net/sctp_getaddrlen.3 =================================================================== --- stable/9/lib/libc/net/sctp_getaddrlen.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_getaddrlen.3 (revision 237216) @@ -1,87 +1,87 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_GETADDRLEN 3 .Os .Sh NAME .Nm sctp_getaddrlen .Nd return the address length of an address family .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft int .Fn sctp_getaddrlen "sa_family_t family" .Sh DESCRIPTION The .Fn sctp_getaddrlen function returns the size of a specific address family. This function is provided for application binary compatibility since it provides the application with the size the operating system thinks the specific address family is. Note that the function will actually create an SCTP socket and then gather the information via a .Fn getsockopt system calls. If for some reason a SCTP socket cannot be created or the .Fn getsockopt -call fails, an error will be returned +call fails, an error will be returned with .Va errno set as specified in the .Fn socket or .Fn getsockopt system call. .Sh RETURN VALUES The call returns the number of bytes that the operating system expects for the specific address family or -1. .Sh ERRORS The .Fn sctp_getaddrlen function can return the following errors: .Bl -tag -width Er .It Bq Er EINVAL The address family specified does NOT exist. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr socket 2 , .Xr sctp 4 Index: stable/9/lib/libc/net/sctp_getassocid.3 =================================================================== --- stable/9/lib/libc/net/sctp_getassocid.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_getassocid.3 (revision 237216) @@ -1,75 +1,75 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_GETASSOCID 3 .Os .Sh NAME .Nm sctp_getassocid .Nd return an association id for a specified socket address. .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft sctp_assoc_t .Fn sctp_getassocid "int s" "struct sockaddr *addr" .Sh DESCRIPTION The .Fn sctp_getassocid call attempts to look up the specified socket address .Fa addr -and find the respective association identification. +and find the respective association identification. .Pp .Sh RETURN VALUES The call returns the association id upon success and 0 is returned upon failure. .Sh ERRORS The .Fn sctp_getassocid function can return the following errors: .Bl -tag -width Er .It Bq Er ENOENT The address does not have an association setup to it. .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .El .Sh SEE ALSO .Xr sctp 4 Index: stable/9/lib/libc/net/sctp_getpaddrs.3 =================================================================== --- stable/9/lib/libc/net/sctp_getpaddrs.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_getpaddrs.3 (revision 237216) @@ -1,100 +1,100 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_GETPADDRS 3 .Os .Sh NAME .Nm sctp_getpaddrs , .Nm sctp_getladdrs .Nd return a list of addresses to the caller .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft int .Fn sctp_getpaddrs "int s" "sctp_assoc_t asocid" "struct sockaddr **addrs" .Ft int .Fn sctp_getladdrs "int s" "sctp_assoc_t asocid" "struct sockaddr **addrs" .Sh DESCRIPTION The .Fn sctp_getpaddrs function is used to get the list of the peers addresses. -The +The .Fn sctp_getladdrs function is used to get the list of the local addresses. The association of interest is identified by the .Fa asocid argument. The addresses are returned in a newly allocated array of socket addresses returned in the argument .Fa addrs upon success. .Pp After the caller is finished, the function .Fn sctp_freepaddrs or .Fn sctp_freeladdrs should be used to release the memory allocated by these calls. .Sh RETURN VALUES The call returns -1 upon failure and a count of the number of addresses returned in .Fa addrs upon success. .Sh ERRORS The functions can return the following errors: .Bl -tag -width Er .It Bq Er EINVAL An address listed has an invalid family or no addresses were provided. .It Bq Er ENOMEM The call cannot allocate memory to hold the socket addresses. .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr sctp_freeladdrs 3 , .Xr sctp_freepaddrs 3 , .Xr sctp 4 Index: stable/9/lib/libc/net/sctp_opt_info.3 =================================================================== --- stable/9/lib/libc/net/sctp_opt_info.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_opt_info.3 (revision 237216) @@ -1,144 +1,144 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 .\" $FreeBSD$ .\" .Dd June 18, 2011 .Dt SCTP_OPT_INFO 3 .Os .Sh NAME .Nm sctp_opt_info .Nd get SCTP socket information .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft int .Fn sctp_opt_info "int sd" "sctp_assoc_t id" "int opt" "void *arg" "socklen_t *size" .Sh DESCRIPTION The .Fn sctp_opt_info call provides a multi-os compatible method for getting -specific +specific .Fn getsockopt data where an association identification needs to be passed into the operating system. For .Fx a direct .Fn getsockopt may be used, since .Fx has the ability to pass information into the operating system on a .Fn getsockopt call. Other operating systems may not have this ability. For those who wish to write portable code amongst multiple operating systems this call should be used for the following SCTP socket options. .Pp -.Dv SCTP_RTOINFO +.Dv SCTP_RTOINFO .Pp .Dv SCTP_ASSOCINFO .Pp .Dv SCTP_PRIMARY_ADDR .Pp .Dv SCTP_PEER_ADDR_PARAMS .Pp .Dv SCTP_DEFAULT_SEND_PARAM .Pp .Dv SCTP_MAX_SEG .Pp .Dv SCTP_AUTH_ACTIVE_KEY .Pp .Dv SCTP_DELAYED_SACK .Pp .Dv SCTP_MAX_BURST .Pp .Dv SCTP_CONTEXT .Pp .Dv SCTP_EVENT .Pp .Dv SCTP_DEFAULT_SNDINFO .Pp .Dv SCTP_DEFAULT_PRINFO .Pp .Dv SCTP_STATUS .Pp .Dv SCTP_GET_PEER_ADDR_INFO .Pp .Dv SCTP_PEER_AUTH_CHUNKS .Pp .Dv SCTP_LOCAL_AUTH_CHUNKS .Sh RETURN VALUES The call returns 0 on success and -1 upon error. .Sh ERRORS The .Fn sctp_opt_info function can return the following errors: .Bl -tag -width Er .It Bq Er EINVAL The argument .Fa arg value was invalid. .It Bq Er EOPNOTSUPP The argument .Fa opt was not one of the above listed SCTP socket options. .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr sctp 4 .Sh BUGS Because the structure used for .Fa arg of the .Dv SCTP_MAX_BURST socket option has changed in FreeBSD 9.0 and higher, using .Dv SCTP_MAX_BURST as .Fa opt is only supported in FreeBSD 9.0 and higher. Index: stable/9/lib/libc/net/sctp_recvmsg.3 =================================================================== --- stable/9/lib/libc/net/sctp_recvmsg.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_recvmsg.3 (revision 237216) @@ -1,298 +1,298 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd August 13, 2007 .Dt SCTP_RECVMSG 3 .Os .Sh NAME .Nm sctp_recvmsg .Nd receive a message from an SCTP socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft ssize_t .Fo sctp_recvmsg .Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" .Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags" .Fc .Sh DESCRIPTION The .Fn sctp_recvmsg system call is used to receive a message from another SCTP endpoint. The .Fn sctp_recvmsg call is used by one-to-one (SOCK_STREAM) type sockets after a -successful +successful .Fn connect -call or after the application has performed a -.Fn listen -followed by a successful +call or after the application has performed a +.Fn listen +followed by a successful .Fn accept . For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call .Fn sctp_recvmsg after having implicitly started an association via one of the send calls including .Fn sctp_sendmsg , .Fn sendto and .Fn sendmsg . Or, an application may also receive a message after having called .Fn listen with a positive backlog to enable the reception of new associations. .Pp The address of the sender is held in the .Fa from -argument with +argument with .Fa fromlen specifying its size. At the completion of a successful .Fn sctp_recvmsg call .Fa from will hold the address of the peer and .Fa fromlen will hold the length of that address. Note that -the address is bounded by the initial value of +the address is bounded by the initial value of .Fa fromlen which is used as an in/out variable. .Pp -The length of the message +The length of the message .Fa msg to be received is bounded by .Fa len . If the message is too long to fit in the users -receive buffer, then the +receive buffer, then the .Fa flags argument will .Em not have the .Dv MSG_EOF flag applied. If the message is a complete message then -the +the .Fa flags argument will have .Dv MSG_EOF set. -Locally detected errors are +Locally detected errors are indicated by a return value of -1 with .Va errno set accordingly. -The +The .Fa flags argument may also hold the value .Dv MSG_NOTIFICATION . When this occurs it indicates that the message received is .Em not from the peer endpoint, but instead is a notification from the SCTP stack (see .Xr sctp 4 for more details). Note that no notifications are ever given unless the user subscribes to such notifications using the .Dv SCTP_EVENTS socket option. .Pp If no messages are available at the socket then .Fn sctp_recvmsg normally blocks on the reception of a message or NOTIFICATION, unless the socket has been placed in non-blocking I/O mode. The .Xr select 2 system call may be used to determine when it is possible to receive a message. .Pp -The +The .Fa sinfo argument is defined as follows. .Bd -literal struct sctp_sndrcvinfo { uint16_t sinfo_stream; /* Stream arriving on */ uint16_t sinfo_ssn; /* Stream Sequence Number */ uint16_t sinfo_flags; /* Flags on the incoming message */ uint32_t sinfo_ppid; /* The ppid field */ uint32_t sinfo_context; /* context field */ uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */ uint32_t sinfo_tsn; /* The transport sequence number */ uint32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ }; .Ed .Pp The .Fa sinfo->sinfo_ppid field is an opaque 32 bit value that is passed transparently -through the stack from the peer endpoint. +through the stack from the peer endpoint. Note that the stack passes this value without regard to byte order. .Pp The .Fa sinfo->sinfo_flags field may include the following: .Bd -literal #define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ .Ed .Pp The .Dv SCTP_UNORDERED flag is used to specify that the message arrived with no specific order and was delivered to the peer application as soon as possible. When this flag is absent the message was delivered in order within the stream it was received. .Pp The .Fa sinfo->sinfo_stream -field is the SCTP stream that the message was received on. +field is the SCTP stream that the message was received on. Streams in SCTP are reliable (or partially reliable) flows of ordered messages. .Pp The .Fa sinfo->sinfo_context field is used only if the local application set an association level context with the .Dv SCTP_CONTEXT socket option. Optionally a user process can use this value to index some application specific data structure for all data coming from a specific -association. +association. .Pp The .Fa sinfo->sinfo_ssn field will hold the stream sequence number assigned by the peer endpoint if the message is .Em not unordered. For unordered messages this field holds an undefined value. .Pp The .Fa sinfo->sinfo_tsn field holds a transport sequence number (TSN) that was assigned to this message by the peer endpoint. For messages that fit in or less than the path MTU this will be the only TSN assigned. Note that for messages that span multiple TSNs this value will be one of the TSNs that was used on the message. .Pp The .Fa sinfo->sinfo_cumtsn field holds the current cumulative acknowledgment point of the transport association. Note that this may be larger or smaller than the TSN assigned to the message itself. .Pp The .Fa sinfo->sinfo_assoc_id is the unique association identification that was assigned to the association. For one-to-many (SOCK_SEQPACKET) type sockets this value can be used to send data to the peer without the use of an address field. It is also quite useful in setting various socket options on the specific association -(see +(see .Xr sctp 4 ) . .Pp The .Fa sinfo->info_timetolive -field is not used by +field is not used by .Fn sctp_recvmsg . .Sh RETURN VALUES The call returns the number of bytes received, or -1 if an error occurred. .Sh ERRORS The .Fn sctp_recvmsg system call fails if: .Bl -tag -width Er .It Bq Er EBADF An invalid descriptor was specified. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .It Bq Er EFAULT An invalid user space address was specified for an argument. .It Bq Er EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. .It Bq Er EAGAIN The socket is marked non-blocking and the requested operation would block. .It Bq Er ENOBUFS The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. .It Bq Er ENOBUFS The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. .It Bq Er EHOSTUNREACH The remote host was unreachable. .It Bq Er ENOTCONN On a one-to-one style socket no association exists. .It Bq Er ECONNRESET An abort was received by the stack while the user was attempting to send data to the peer. .It Bq Er ENOENT On a one to many style socket no address is specified so that the association cannot be located or the SCTP_ABORT flag was specified on a non-existing association. .It Bq Er EPIPE The socket is unable to send anymore data .Dv ( SBS_CANTSENDMORE has been set on the socket). This typically means that the socket is not connected and is a one-to-one style socket. .El .Sh SEE ALSO .Xr recv 2 , .Xr select 2 , .Xr socket 2 , .Xr write 2 , .Xr getsockopt 2 , .Xr setsockopt 2 , .Xr sctp_send 3 , .Xr sctp_sendmsg 3 , .Xr sendmsg 3 , .Xr sctp 4 Index: stable/9/lib/libc/net/sctp_send.3 =================================================================== --- stable/9/lib/libc/net/sctp_send.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_send.3 (revision 237216) @@ -1,354 +1,354 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_SEND 3 .Os .Sh NAME .Nm sctp_send , .Nm sctp_sendx .Nd send a message from an SCTP socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft ssize_t .Fo sctp_send .Fa "int sd" "const void *msg" "size_t len" .Fa "const struct sctp_sndrcvinfo *sinfo" "int flags" .Fc .Ft ssize_t .Fo sctp_sendx .Fa "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs" .Fa "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags" .Fc .Sh DESCRIPTION The .Fn sctp_send system call is used to transmit a message to another SCTP endpoint. .Fn sctp_send may be used to send data to an existing association for both one-to-many (SOCK_SEQPACKET) and one-to-one (SOCK_STREAM) socket types. -The length of the message +The length of the message .Fa msg is given by .Fa len . If the message is too long to pass atomically through the underlying protocol, .Va errno -is set to +is set to .Er EMSGSIZE , -1 is returned, and the message is not transmitted. .Pp No indication of failure to deliver is implicit in a .Fn sctp_send . Locally detected errors are indicated by a return value of -1. .Pp If no space is available at the socket to hold the message to be transmitted, then .Fn sctp_send normally blocks, unless the socket has been placed in non-blocking I/O mode. The .Xr select 2 system call may be used to determine when it is possible to send more data on one-to-one type (SOCK_STREAM) sockets. .Pp -The +The .Fa sinfo structure is used to control various SCTP features and has the following format: .Bd -literal struct sctp_sndrcvinfo { uint16_t sinfo_stream; /* Stream sending to */ uint16_t sinfo_ssn; /* valid for recv only */ uint16_t sinfo_flags; /* flags to control sending */ uint32_t sinfo_ppid; /* ppid field */ uint32_t sinfo_context; /* context field */ uint32_t sinfo_timetolive; /* timetolive for PR-SCTP */ uint32_t sinfo_tsn; /* valid for recv only */ uint32_t sinfo_cumtsn; /* valid for recv only */ sctp_assoc_t sinfo_assoc_id; /* The association id */ }; .Ed .Pp -The +The .Fa sinfo->sinfo_ppid argument is an opaque 32 bit value that is passed transparently through the stack to the peer endpoint. It will be available on reception of a message (see .Xr sctp_recvmsg 3 ) . Note that the stack passes this value without regard to byte order. .Pp The .Fa sinfo->sinfo_flags argument may include one or more of the following: .Bd -literal #define SCTP_EOF 0x0100 /* Start a shutdown procedures */ #define SCTP_ABORT 0x0200 /* Send an ABORT to peer */ #define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ #define SCTP_ADDR_OVER 0x0800 /* Override the primary-address */ #define SCTP_SENDALL 0x1000 /* Send this on all associations */ /* for the endpoint */ /* The lower byte is an enumeration of PR-SCTP policies */ #define SCTP_PR_SCTP_TTL 0x0001 /* Time based PR-SCTP */ #define SCTP_PR_SCTP_BUF 0x0002 /* Buffer based PR-SCTP */ #define SCTP_PR_SCTP_RTX 0x0003 /* Number of retransmissions based PR-SCTP */ .Ed .Pp -The flag +The flag .Dv SCTP_EOF is used to instruct the SCTP stack to queue this message and then start a graceful shutdown of the association. All remaining data in queue will be sent after which the association will be shut down. .Pp .Dv SCTP_ABORT is used to immediately terminate an association. An abort is sent to the peer and the local TCB is destroyed. .Pp .Dv SCTP_UNORDERED is used to specify that the message being sent has no specific order and should be delivered to the peer application as soon as possible. When this flag is absent messages are delivered in order within the stream they are sent, but without respect to order to peer streams. .Pp The flag .Dv SCTP_ADDR_OVER is used to specify that a specific address should be used. Normally SCTP will use only one of a multi-homed peers addresses as the primary address to send to. -By default, no matter what the +By default, no matter what the .Fa to argument is, this primary address is used to send data. By specifying this flag, the user is asking the stack to ignore the primary address and instead use the specified address not only as a lookup mechanism to find the association but also as the actual address to send to. .Pp For a one-to-many type (SOCK_SEQPACKET) socket the flag .Dv SCTP_SENDALL can be used as a convenient way to make one send call and have all associations that are under the socket get a copy of the message. Note that this mechanism is quite efficient and makes only one actual copy of the data which is shared by all the associations for sending. .Pp The remaining flags are used for the partial reliability extension (RFC3758) and will only be effective if the peer endpoint supports this extension. This option specifies what local policy the local endpoint should use in skipping data. If none of these options are set, then data is never skipped over. .Pp .Dv SCTP_PR_SCTP_TTL is used to indicate that a time based lifetime is being applied to the data. The .Fa sinfo->sinfo_timetolive argument is then a number of milliseconds for which the data is attempted to be transmitted. If that many milliseconds elapse and the peer has not acknowledged the data, the data will be skipped and no longer transmitted. Note that this policy does not even assure that the data will ever be sent. In times of a congestion -with large amounts of data being queued, the +with large amounts of data being queued, the .Fa sinfo->sinfo_timetolive may expire before the first transmission is ever made. .Pp The .Dv SCTP_PR_SCTP_BUF based policy transforms the -.Fa sinfo->sinfo_timetolive +.Fa sinfo->sinfo_timetolive field into a total number of bytes allowed on the outbound send queue. If that number or more bytes are in queue, then other buffer-based sends are looked to be removed and skipped. Note that this policy may also result in the data never being sent if no buffer based sends are in queue and -the maximum specified by -.Fa timetolive +the maximum specified by +.Fa timetolive bytes is in queue. .Pp The .Dv SCTP_PR_SCTP_RTX policy transforms the -.Fa sinfo->sinfo_timetolive +.Fa sinfo->sinfo_timetolive into a number of retransmissions to allow. This policy always assures that at a minimum one send attempt is made of the data. -After which no more than +After which no more than .Fa sinfo->sinfo_timetolive retransmissions will be made before the data is skipped. .Pp .Fa sinfo->sinfo_stream is the SCTP stream that you wish to send the message on. Streams in SCTP are reliable (or partially reliable) flows of ordered -messages. +messages. .Pp The .Fa sinfo->sinfo_assoc_id -field is used to +field is used to select the association to send to on a one-to-many socket. For a one-to-one socket, this field is ignored. .Pp The .Fa sinfo->sinfo_context field is used only in the event the message cannot be sent. This is an opaque value that the stack retains and will give to the user when a failed send is given if that notification is enabled (see .Xr sctp 4 ) . Normally a user process can use this value to index some application specific data structure when a send cannot be fulfilled. .Pp The .Fa flags argument holds the same meaning and values as those found in .Xr sendmsg 2 but is generally ignored by SCTP. .Pp The fields .Fa sinfo->sinfo_ssn , .Fa sinfo->sinfo_tsn , and -.Fa sinfo->sinfo_cumtsn +.Fa sinfo->sinfo_cumtsn are used only when receiving messages and are thus ignored by .Fn sctp_send . The function -.Fn sctp_sendx -has the same properties as +.Fn sctp_sendx +has the same properties as .Fn sctp_send with the additional arguments of an array of sockaddr structures passed in. -With the +With the .Fa addrs argument being given as an array of addresses to be sent to and the .Fa addrcnt argument indicating how many socket addresses are in the passed in array. Note that all of the addresses will only be used when an implicit association is being set up. This allows the user the equivalent behavior as doing a .Fn sctp_connectx -followed by a +followed by a .Fn sctp_send to the association. Note that if the .Fa sinfo->sinfo_assoc_id field is 0, then the first address will be used to look up the association in place of the association id. If both an address and an association id are specified, the association id has priority. .Sh RETURN VALUES The call returns the number of characters sent, or -1 if an error occurred. .Sh ERRORS The .Fn sctp_send system call fails if: .Bl -tag -width Er .It Bq Er EBADF An invalid descriptor was specified. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .It Bq Er EFAULT An invalid user space address was specified for an argument. .It Bq Er EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. .It Bq Er EAGAIN The socket is marked non-blocking and the requested operation would block. .It Bq Er ENOBUFS The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. .It Bq Er ENOBUFS The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. .It Bq Er EHOSTUNREACH The remote host was unreachable. .It Bq Er ENOTCONN On a one-to-one style socket no association exists. .It Bq Er ECONNRESET An abort was received by the stack while the user was attempting to send data to the peer. .It Bq Er ENOENT On a one-to-many style socket no address is specified so that the association cannot be located or the SCTP_ABORT flag was specified on a non-existing association. .It Bq Er EPIPE The socket is unable to send anymore data .Dv ( SBS_CANTSENDMORE has been set on the socket). This typically means that the socket is not connected and is a one-to-one style socket. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr select 2 , .Xr sendmsg 2 , .Xr socket 2 , .Xr write 2 .Xr sctp_connectx 3 , .Xr sctp_recvmsg 3 , .Xr sctp_sendmsg 3 , .Xr sctp 4 .Sh BUGS Because .Fn sctp_send may have multiple associations under one endpoint, a select on write will only work for a one-to-one style socket. Index: stable/9/lib/libc/net/sctp_sendmsg.3 =================================================================== --- stable/9/lib/libc/net/sctp_sendmsg.3 (revision 237215) +++ stable/9/lib/libc/net/sctp_sendmsg.3 (revision 237216) @@ -1,333 +1,333 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_SENDMSG 3 .Os .Sh NAME .Nm sctp_sendmsg , .Nm sctp_sendmsgx .Nd send a message from an SCTP socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft ssize_t .Fo sctp_sendmsg .Fa "int s" "const void *msg" "size_t len" "const struct sockaddr *to" .Fa "socklen_t tolen" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no" .Fa "uint32_t timetolive" "uint32_t context" .Fc .Ft ssize_t .Fo sctp_sendmsgx .Fa "int s" "const void *msg" "size_t len" "const struct sockaddr *to" .Fa "int addrcnt" "uint32_t ppid" "uint32_t flags" "uint16_t stream_no" .Fa "uint32_t timetolive" "uint32_t context" .Fc .Sh DESCRIPTION The .Fn sctp_sendmsg system call is used to transmit a message to another SCTP endpoint. The .Fn sctp_sendmsg may be used at any time. If the socket is a one-to-many type (SOCK_SEQPACKET) socket then an attempt to send to an address that no association exists to will implicitly create a new association. Data sent in such an instance will result in the data being sent on the third leg of the SCTP four-way handshake. Note that if the socket is a one-to-one type (SOCK_STREAM) socket then an association must -be in existence (by use of the +be in existence (by use of the .Xr connect 2 system call). -Calling +Calling .Fn sctp_sendmsg or .Fn sctp_sendmsgx on a non-connected one-to-one socket will result in .Va errno being set to .Er ENOTCONN , -1 being returned, and the message not being transmitted. .Pp The address of the target is given by .Fa to with .Fa tolen specifying its size. -The length of the message +The length of the message .Fa msg is given by .Fa len . If the message is too long to pass atomically through the underlying protocol, .Va errno -is set to +is set to .Er EMSGSIZE , -1 is returned, and the message is not transmitted. .Pp No indication of failure to deliver is implicit in a .Xr sctp_sendmsg 3 call. Locally detected errors are indicated by a return value of -1. .Pp If no space is available at the socket to hold the message to be transmitted, then .Xr sctp_sendmsg 3 normally blocks, unless the socket has been placed in non-blocking I/O mode. The .Xr select 2 system call may be used to determine when it is possible to send more data on one-to-one type (SOCK_STREAM) sockets. .Pp -The +The .Fa ppid argument is an opaque 32 bit value that is passed transparently through the stack to the peer endpoint. It will be available on reception of a message (see .Xr sctp_recvmsg 3 ) . Note that the stack passes this value without regard to byte order. .Pp The .Fa flags argument may include one or more of the following: .Bd -literal #define SCTP_EOF 0x0100 /* Start a shutdown procedures */ #define SCTP_ABORT 0x0200 /* Send an ABORT to peer */ #define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ #define SCTP_ADDR_OVER 0x0800 /* Override the primary-address */ #define SCTP_SENDALL 0x1000 /* Send this on all associations */ /* for the endpoint */ /* The lower byte is an enumeration of PR-SCTP policies */ #define SCTP_PR_SCTP_TTL 0x0001 /* Time based PR-SCTP */ #define SCTP_PR_SCTP_BUF 0x0002 /* Buffer based PR-SCTP */ #define SCTP_PR_SCTP_RTX 0x0003 /* Number of retransmissions based PR-SCTP */ .Ed .Pp -The flag +The flag .Dv SCTP_EOF is used to instruct the SCTP stack to queue this message and then start a graceful shutdown of the association. All remaining data in queue will be sent after which the association will be shut down. .Pp .Dv SCTP_ABORT is used to immediately terminate an association. An abort is sent to the peer and the local TCB is destroyed. .Pp .Dv SCTP_UNORDERED is used to specify that the message being sent has no specific order and should be delivered to the peer application as soon as possible. When this flag is absent messages are delivered in order within the stream they are sent, but without respect to order to peer streams. .Pp The flag .Dv SCTP_ADDR_OVER is used to specify that an specific address should be used. Normally SCTP will use only one of a multi-homed peers addresses as the primary address to send to. -By default, no matter what the +By default, no matter what the .Fa to argument is, this primary address is used to send data. By specifying this flag, the user is asking the stack to ignore the primary address and instead use the specified address not only as a lookup mechanism to find the association but also as the actual address to send to. .Pp For a one-to-many type (SOCK_SEQPACKET) socket the flag .Dv SCTP_SENDALL can be used as a convenient way to make one send call and have all associations that are under the socket get a copy of the message. Note that this mechanism is quite efficient and makes only one actual copy of the data which is shared by all the associations for sending. .Pp The remaining flags are used for the partial reliability extension (RFC3758) and will only be effective if the peer endpoint supports this extension. This option specifies what local policy the local endpoint should use in skipping data. If none of these options are set, then data is never skipped over. .Pp .Dv SCTP_PR_SCTP_TTL is used to indicate that a time based lifetime is being applied to the data. The .Fa timetolive argument is then a number of milliseconds for which the data is attempted to be transmitted. If that many milliseconds elapse and the peer has not acknowledged the data, the data will be skipped and no longer transmitted. Note that this policy does not even assure that the data will ever be sent. In times of a congestion -with large amounts of data being queued, the +with large amounts of data being queued, the .Fa timetolive may expire before the first transmission is ever made. .Pp The .Dv SCTP_PR_SCTP_BUF based policy transforms the -.Fa timetolive +.Fa timetolive field into a total number of bytes allowed on the outbound send queue. If that number or more bytes are in queue, then other buffer based sends are looked to be removed and skipped. Note that this policy may also result in the data never being sent if no buffer based sends are in queue and -the maximum specified by -.Fa timetolive +the maximum specified by +.Fa timetolive bytes is in queue. .Pp The .Dv SCTP_PR_SCTP_RTX policy transforms the -.Fa timetolive +.Fa timetolive into a number of retransmissions to allow. This policy always assures that at a minimum one send attempt is made of the data. -After which no more than +After which no more than .Fa timetolive retransmissions will be made before the data is skipped. .Pp .Fa stream_no is the SCTP stream that you wish to send the message on. Streams in SCTP are reliable (or partially reliable) flows of ordered messages. -The +The .Fa context field is used only in the event the message cannot be sent. This is an opaque value that the stack retains and will give to the user when a failed send is given if that notification is enabled (see .Xr sctp 4 ) . Normally a user process can use this value to index some application specific data structure when a send cannot be fulfilled. .Fn sctp_sendmsgx -is identical to +is identical to .Fn sctp_sendmsg with the exception that it takes an array of sockaddr structures in the argument .Fa to and adds the additional argument .Fa addrcnt which specifies how many addresses are in the array. This allows a caller to implicitly set up an association passing multiple addresses as if -.Fn sctp_connectx +.Fn sctp_connectx had been called to set up the association. .Sh RETURN VALUES The call returns the number of characters sent, or -1 if an error occurred. .Sh ERRORS The .Fn sctp_sendmsg system call fails if: .Bl -tag -width Er .It Bq Er EBADF An invalid descriptor was specified. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .It Bq Er EFAULT An invalid user space address was specified for an argument. .It Bq Er EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. .It Bq Er EAGAIN The socket is marked non-blocking and the requested operation would block. .It Bq Er ENOBUFS The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. .It Bq Er ENOBUFS The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. .It Bq Er EHOSTUNREACH The remote host was unreachable. .It Bq Er ENOTCONN On a one-to-one style socket no association exists. .It Bq Er ECONNRESET An abort was received by the stack while the user was attempting to send data to the peer. .It Bq Er ENOENT On a one-to-many style socket no address is specified so that the association cannot be located or the .Dv SCTP_ABORT flag was specified on a non-existing association. .It Bq Er EPIPE The socket is unable to send anymore data .Dv ( SBS_CANTSENDMORE has been set on the socket). This typically means that the socket is not connected and is a one-to-one style socket. .El .Sh SEE ALSO .Xr connect 2 , .Xr getsockopt 2 , .Xr recv 2 , .Xr select 2 , .Xr socket 2 , .Xr write 2 , .Xr sctp_connectx 3 , .Xr sendmsg 3 , .Xr sctp 4 .Sh BUGS Because in the one-to-many style socket -.Fn sctp_sendmsg +.Fn sctp_sendmsg or .Fn sctp_sendmsgx may have multiple associations under one endpoint, a select on write will only work for a one-to-one style socket. Index: stable/9/lib/libc/net/sourcefilter.3 =================================================================== --- stable/9/lib/libc/net/sourcefilter.3 (revision 237215) +++ stable/9/lib/libc/net/sourcefilter.3 (revision 237216) @@ -1,240 +1,240 @@ .\" Copyright (c) 2007-2009 Bruce Simpson. .\" 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. .\" .\" $FreeBSD$ .\" .Dd February 13, 2009 .Dt SOURCEFILTER 3 .Os .Sh NAME .Nm sourcefilter .Nd advanced multicast group membership API .Sh SYNOPSIS .In sys/socket.h .In netinet/in.h .Ft int .Fo getipv4sourcefilter .Fa "int s" .Fa "struct in_addr interface" .Fa "struct in_addr group" .Fa "uint32_t *fmode" .Fa "uint32_t *numsrc" .Fa "struct in_addr *slist" .Fc .Ft int .Fo getsourcefilter .Fa "int s" .Fa "uint32_t interface" .Fa "struct sockaddr *group" .Fa "socklen_t grouplen" .Fa "uint32_t *fmode" .Fa "uint32_t *numsrc" .Fa "struct sockaddr_storage *slist" .Fc .Ft int .Fo setipv4sourcefilter .Fa "int s" .Fa "struct in_addr interface" .Fa "struct in_addr group" .Fa "uint32_t fmode" .Fa "uint32_t numsrc" .Fa "struct in_addr *slist" .Fc .Ft int .Fo setsourcefilter .Fa "int s" .Fa "uint32_t interface" .Fa "struct sockaddr *group" .Fa "socklen_t grouplen" .Fa "uint32_t fmode" .Fa "uint32_t numsrc" .Fa "struct sockaddr_storage *slist" .Fc .Sh DESCRIPTION The .Nm functions implement the advanced, full-state multicast API defined in RFC 3678. An application may use these functions to atomically set and retrieve the multicast source address filters associated with a socket .Fa s and a multicast .Fa group . .Pp The functions .Fn getipv4sourcefilter and .Fn getsourcefilter allow an application to discover the filter mode, and source filter entries, for an existing group membership. .Pp The kernel will always return the number of source filter entries on the socket for that group in .Fa *numsrc . If the .Fa *numsrc argument is non-zero, the kernel will attempt to return up to .Fa *numsrc filter entries in the array pointed to by .Fa slist . The .Fa *numsrc argument may be set to 0, in which case the .Fa slist argument will be ignored. .Pp For the .Fn setipv4sourcefilter and .Fn setsourcefilter functions, the .Fa fmode argument may be used to place the socket into inclusive or exclusive group membership modes, by using the .Dv MCAST_INCLUDE or .Dv MCAST_EXCLUDE constants respectively. The .Fa numsrc argument specifies the number of source entries in the .Fa slist array. If the .Fa numsrc argument has a value of 0, all source filters will be removed from the socket. Removing all source filters from a membership which is in the .Dv MCAST_INCLUDE filter mode will cause the group to be left on that socket. .Pp The protocol-independent function .Fn setsourcefilter allows an application to join a multicast group on an interface which may not have an assigned protocol address, by passing its index for the .Fa interface argument. .Pp Any changes made by these functions will be communicated to IGMPv3 and/or MLDv2 routers on the local network as appropriate. If no IGMPv3 or MLDv2 routers are present, changes in the source filter lists made by these functions will not cause state changes to be transmitted, with the exception of any change which causes a group to be joined or left. The kernel will continue to maintain the source filter state regardless of the IGMP or MLD version in use on the link. .Sh IMPLEMENTATION NOTES The IPv4 specific versions of these functions are implemented in terms of the protocol-independent functions. Application writers are encouraged to use the protocol-independent functions for efficiency, and forwards compatibility with IPv6 networks. .Pp For the protocol-independent functions .Fn getsourcefilter and .Fn setsourcefilter , -the +the argument .Fa grouplen argument specifies the size of the structure pointed to by .Fa group . This is required in order to differentiate between different address families. .Pp Currently .Fx does not support source address selection for the IPv4 protocol family, therefore the use of multicast APIs with an unnumbered IPv4 interface is .Em not recommended. In all cases, the first assigned IPv4 address on the interface will be used as the source address of IGMP control traffic. If this address is removed or changed, the results are undefined. .Sh RETURN VALUES .Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter .Sh ERRORS The .Nm functions may fail because of: .Bl -tag -width Er .It Bq Er EADDRNOTAVAIL The network interface which the .Dv interface argument refers to was not configured in the system, or the system is not a member of the .Dv group . .It Bq Er EAFNOSUPPORT The .Dv group and/or one or more of the .Dv slist arguments were of an address family unsupported by the system, or the address family of the .Dv group and .Dv slist arguments were not identical. .It Bq Er EINVAL The .Dv group argument does not contain a multicast address. The .Dv fmode argument is invalid; it must be set to either .Dv MCAST_INCLUDE or .Dv MCAST_EXCLUDE . The .Dv numsrc or .Dv slist arguments do not specify a source list. .It Bq Er ENOMEM Insufficient memory was available to carry out the requested operation. .El .Sh SEE ALSO .Xr ip 4 , .Xr ip6 4 , -.Xr multicast 4 , +.Xr multicast 4, .Xr ifmcstat 8 .Rs .%A D. Thaler .%A B. Fenner .%A B. Quinn .%T "Socket Interface Extensions for Multicast Source Filters" .%N RFC 3678 .%D Jan 2004 .Re .Sh HISTORY The .Nm functions first appeared in .Fx 7.0 . .Sh AUTHORS Bruce M. Simpson .Aq bms@FreeBSD.org Index: stable/9/lib/libc/posix1e/acl_add_flag_np.3 =================================================================== --- stable/9/lib/libc/posix1e/acl_add_flag_np.3 (revision 237215) +++ stable/9/lib/libc/posix1e/acl_add_flag_np.3 (revision 237216) @@ -1,97 +1,97 @@ .\"- .\" Copyright (c) 2008, 2009 Edward Tomasz Napierala .\" 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. .\" .\" $FreeBSD$ .\" .Dd June 25, 2009 .Dt ACL_ADD_FLAG_NP 3 .Os .Sh NAME .Nm acl_add_flag_np -.Nd add flags to a flagset +.Nd add flags to a flagset .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/acl.h .Ft int .Fn acl_add_flag_np "acl_flagset_t flagset_d" "acl_flag_t flag" .Sh DESCRIPTION The .Fn acl_add_flag_np function is a non-portable call that adds the flags contained in .Fa flags to the flagset .Fa flagset_d . .Pp Note: it is not considered an error to attempt to add flags that already exist in the flagset. .Pp Valid values are: .Bl -column -offset 3n "ACL_ENTRY_NO_PROPAGATE_INHERIT" .It ACL_ENTRY_FILE_INHERIT Will be inherited by files. .It ACL_ENTRY_DIRECTORY_INHERIT Will be inherited by directories. .It ACL_ENTRY_NO_PROPAGATE_INHERIT Will not propagate. .It ACL_ENTRY_INHERIT_ONLY Inherit-only. .El .Sh RETURN VALUES .Rv -std acl_add_flag_np .Sh ERRORS The .Fn acl_add_flag_np function fails if: .Bl -tag -width Er .It Bq Er EINVAL Argument .Fa flagset_d is not a valid descriptor for a flagset within an ACL entry. Argument .Fa flag does not contain a valid .Vt acl_flag_t value. .El .Sh SEE ALSO .Xr acl 3 , .Xr acl_clear_flags_np 3 , .Xr acl_delete_flag_np 3 , .Xr acl_get_flagset_np 3 , .Xr acl_set_flagset_np 3 , .Xr posix1e 3 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. .Sh HISTORY POSIX.1e support was introduced in .Fx 4.0 . The .Fn acl_add_flag_np function was added in .Fx 8.0 . .Sh AUTHORS The .Fn acl_add_flag_np function was written by .An Edward Tomasz Napierala Aq trasz@FreeBSD.org . Index: stable/9/lib/libc/posix1e/acl_create_entry.3 =================================================================== --- stable/9/lib/libc/posix1e/acl_create_entry.3 (revision 237215) +++ stable/9/lib/libc/posix1e/acl_create_entry.3 (revision 237216) @@ -1,98 +1,98 @@ .\"- .\" Copyright (c) 2001 Chris D. Faulhaber .\" 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 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 June 25, 2009 .Dt ACL_CREATE_ENTRY 3 .Os .Sh NAME .Nm acl_create_entry .Nm acl_create_entry_np .Nd create a new ACL entry .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/acl.h .Ft int .Fn acl_create_entry "acl_t *acl_p" "acl_entry_t *entry_p" -.Ft int +.Ft int .Fn acl_create_entry_np "acl_t *acl_p" "acl_entry_t *entry_p" "int index" .Sh DESCRIPTION The .Fn acl_create_entry function is a POSIX.1e call that creates a new ACL entry in the ACL pointed to by .Fa acl_p . The .Fn acl_create_entry_np function is a non-portable version that creates the ACL entry at position .Fa index . Positions are numbered starting from zero, i.e. calling .Fn acl_create_entry_np with .Fa index argument equal to zero will prepend the entry to the ACL. .Sh RETURN VALUES .Rv -std acl_create_entry .Sh ERRORS The .Fn acl_create_entry function fails if: .Bl -tag -width Er .It Bq Er EINVAL Argument .Fa acl_p does not point to a pointer to a valid ACL. Argument .Fa index is out of bounds. .It Bq Er ENOMEM The ACL working storage requires more memory than is allowed by the hardware or system-imposed memory management constraints. .El .Sh SEE ALSO .Xr acl 3 , .Xr acl_delete_entry 3 , .Xr acl_get_entry 3 , .Xr posix1e 3 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. .Sh HISTORY POSIX.1e support was introduced in .Fx 4.0 . The .Fn acl_create_entry function was added in .Fx 5.0 . .Sh AUTHORS The .Fn acl_create_entry function was written by .An Chris D. Faulhaber Aq jedgar@fxp.org . Index: stable/9/lib/libc/stdio/getline.3 =================================================================== --- stable/9/lib/libc/stdio/getline.3 (revision 237215) +++ stable/9/lib/libc/stdio/getline.3 (revision 237216) @@ -1,165 +1,165 @@ .\" Copyright (c) 2009 David Schultz .\" 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. .\" .\" $FreeBSD$ .\" .Dd November 30, 2010 .Dt GETLINE 3 .Os .Sh NAME .Nm getdelim , .Nm getline .Nd get a line from a stream .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd "#define _WITH_GETLINE" .In stdio.h .Ft ssize_t .Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream" .Ft ssize_t .Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream" .Sh DESCRIPTION The .Fn getdelim function reads a line from .Fa stream , delimited by the character .Fa delimiter . The .Fn getline function is equivalent to .Fn getdelim with the newline character as the delimiter. The delimiter character is included as part of the line, unless the end of the file is reached. .Pp The caller may provide a pointer to a malloced buffer for the line in .Fa *linep , and the capacity of that buffer in .Fa *linecapp . These functions expand the buffer as needed, as if via .Fn realloc . If .Fa linep points to a .Dv NULL pointer, a new buffer will be allocated. In either case, .Fa *linep and .Fa *linecapp will be updated accordingly. .Sh RETURN VALUES The .Fn getdelim and .Fn getline functions return the number of characters written, excluding the terminating -.Dv NUL +.Dv NUL character. The value \-1 is returned if an error occurs, or if end-of-file is reached. .Sh EXAMPLES The following code fragment reads lines from a file and writes them to standard output. The .Fn fwrite function is used in case the line contains embedded .Dv NUL characters. .Bd -literal -offset indent char *line = NULL; size_t linecap = 0; ssize_t linelen; while ((linelen = getline(&line, &linecap, fp)) > 0) fwrite(line, linelen, 1, stdout); .Ed .Sh COMPATIBILITY Many application writers used the name .Va getline before the .Fn getline function was introduced in .St -p1003.1 , so a prototype is not provided by default in order to avoid compatibility problems. Applications that wish to use the .Fn getline function described herein should either request a strict .St -p1003.1-2008 environment by defining the macro .Dv _POSIX_C_SOURCE to the value 200809 or greater, or by defining the macro .Dv _WITH_GETLINE , prior to the inclusion of .In stdio.h . For compatibility with GNU libc, defining either .Dv _BSD_SOURCE or .Dv _GNU_SOURCE prior to the inclusion of .In stdio.h will also make .Fn getline available. .Sh ERRORS These functions may fail if: .Bl -tag -width Er .It Bq Er EINVAL Either .Fa linep or .Fa linecapp is .Dv NULL . .It Bq Er EOVERFLOW No delimiter was found in the first .Dv SSIZE_MAX characters. .El .Pp These functions may also fail due to any of the errors specified for .Fn fgets and .Fn malloc . .Sh SEE ALSO .Xr fgetln 3 , .Xr fgets 3 , .Xr malloc 3 .Sh STANDARDS The .Fn getdelim and .Fn getline functions conform to .St -p1003.1-2008 . .Sh HISTORY These routines first appeared in .Fx 8.0 . .Sh BUGS There are no wide character versions of .Fn getdelim or .Fn getline . Index: stable/9/lib/libc/stdlib/at_quick_exit.3 =================================================================== --- stable/9/lib/libc/stdlib/at_quick_exit.3 (revision 237215) +++ stable/9/lib/libc/stdlib/at_quick_exit.3 (revision 237216) @@ -1,61 +1,61 @@ .\" Copyright (c) 2011 David Chisnall .\" 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. -.\" +.\" .\" $FreeBSD$ .\" .Dd December 7, 2011 .Dt AT_QUICK_EXIT 3 .Os .Sh NAME .Nm at_quick_exit .Nd registers a cleanup function to run on quick exit .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .Ft int .Fn at_quick_exit "void (*func)(void)" .Sh DESCRIPTION The .Fn at_quick_exit function registers a cleanup function to be called when the program exits as a -result of calling +result of calling .Xr quick_exit 3 . The cleanup functions are called in the reverse order and will not be called if -the program exits by calling +the program exits by calling .Xr exit 3 , .Xr _Exit 3 , or .Xr abort 3 . .Sh RETURN VALUES -The +The .Fn at_quick_exit function returns the value 0 if successful and a non-zero value on failure. .Sh SEE ALSO .Xr exit 3 , .Xr quick_exit 3 .Sh STANDARDS The .Fn at_quick_exit function conforms to the C1x draft specification. Index: stable/9/lib/libc/stdlib/getenv.3 =================================================================== --- stable/9/lib/libc/stdlib/getenv.3 (revision 237215) +++ stable/9/lib/libc/stdlib/getenv.3 (revision 237216) @@ -1,230 +1,230 @@ .\" Copyright (c) 1988, 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. .\" 4. 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. .\" .\" @(#)getenv.3 8.2 (Berkeley) 12/11/93 .\" $FreeBSD$ .\" .Dd June 20, 2007 .Dt GETENV 3 .Os .Sh NAME .Nm getenv , .Nm putenv , .Nm setenv , .Nm unsetenv .Nd environment variable functions .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .Ft char * .Fn getenv "const char *name" .Ft int .Fn setenv "const char *name" "const char *value" "int overwrite" .Ft int .Fn putenv "char *string" .Ft int .Fn unsetenv "const char *name" .Sh DESCRIPTION These functions set, unset and fetch environment variables from the host .Em environment list . .Pp The .Fn getenv function obtains the current value of the environment variable, .Fa name . The application should not modify the string pointed to by the .Fn getenv function. .Pp The .Fn setenv function inserts or resets the environment variable .Fa name in the current environment list. If the variable .Fa name does not exist in the list, it is inserted with the given .Fa value . If the variable does exist, the argument .Fa overwrite is tested; if .Fa overwrite is zero, the variable is not reset, otherwise it is reset to the given .Fa value . .Pp The .Fn putenv function takes an argument of the form ``name=value'' and puts it directly into the current environment, so altering the argument shall change the environment. If the variable .Fa name does not exist in the list, it is inserted with the given .Fa value . If the variable .Fa name does exist, it is reset to the given .Fa value . .Pp The .Fn unsetenv function deletes all instances of the variable name pointed to by .Fa name from the list. .Pp If corruption (e.g., a name without a value) is detected while making a copy of environ for internal usage, then .Fn setenv , .Fn unsetenv and .Fn putenv will output a warning to stderr about the issue, drop the corrupt entry and complete the task without error. .Sh RETURN VALUES The .Fn getenv function returns the value of the environment variable as a .Dv NUL Ns -terminated string. If the variable .Fa name is not in the current environment, .Dv NULL is returned. .Pp .Rv -std setenv putenv unsetenv .Sh ERRORS .Bl -tag -width Er .It Bq Er EINVAL The function .Fn getenv , .Fn setenv or .Fn unsetenv failed because the .Fa name is a .Dv NULL pointer, points to an empty string, or points to a string containing an .Dq Li \&= character. .Pp The function .Fn putenv failed because .Fa string is a .Dv NULL pointer, .Fa string is without an .Dq Li \&= character or .Dq Li \&= is the first character in .Fa string . This does not follow the .Tn POSIX specification. .It Bq Er ENOMEM The function .Fn setenv , .Fn unsetenv or .Fn putenv failed because they were unable to allocate memory for the environment. .El .Sh SEE ALSO .Xr csh 1 , .Xr sh 1 , .Xr execve 2 , .Xr environ 7 .Sh STANDARDS The .Fn getenv function conforms to .St -isoC . The .Fn setenv , .Fn putenv and .Fn unsetenv functions conforms to .St -p1003.1-2001 . .Sh HISTORY The functions .Fn setenv and .Fn unsetenv appeared in .At v7 . The .Fn putenv function appeared in .Bx 4.3 Reno . .Pp Until .Fx 7.0 , .Fn putenv -would make a copy of +would make a copy of .Fa string and insert it into the environment using .Fn setenv . This was changed to use .Fa string as the memory location of the ``name=value'' pair to follow the .Tn POSIX specification. .Sh BUGS Successive calls to .Fn setenv that assign a larger-sized .Fa value than any previous value to the same .Fa name will result in a memory leak. The .Fx semantics for this function (namely, that the contents of .Fa value are copied and that old values remain accessible indefinitely) make this bug unavoidable. Future versions may eliminate one or both of these semantic guarantees in order to fix the bug. Index: stable/9/lib/libc/string/memchr.3 =================================================================== --- stable/9/lib/libc/string/memchr.3 (revision 237215) +++ stable/9/lib/libc/string/memchr.3 (revision 237216) @@ -1,106 +1,106 @@ .\" 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. .\" 4. 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. .\" .\" @(#)memchr.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd April 9, 2008 .Dt MEMCHR 3 .Os .Sh NAME .Nm memchr .Nd locate byte in byte string .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In string.h .Ft void * .Fn memchr "const void *b" "int c" "size_t len" .Ft void * .Fn memrchr "const void *b" "int c" "size_t len" .Sh DESCRIPTION The .Fn memchr function locates the first occurrence of .Fa c (converted to an .Vt "unsigned char" ) in string .Fa b . .Pp The .Fn memrchr function behaves like .Fn memchr , except that it locates the last occurrence of .Fa c in string .Fa b . .Sh RETURN VALUES The .Fn memchr and .Fn memrchr functions return a pointer to the byte located, or NULL if no such byte exists within .Fa len bytes. .Sh SEE ALSO .Xr memmem 3 , .Xr strchr 3 , .Xr strcspn 3 , .Xr strpbrk 3 , .Xr strrchr 3 , .Xr strsep 3 , .Xr strspn 3 , .Xr strstr 3 , .Xr strtok 3 , .Xr wmemchr 3 .Sh STANDARDS The .Fn memchr function conforms to .St -isoC . .Pp The -.Fn memrchr +.Fn memrchr function is a GNU extension and conforms to no standard. .Sh HISTORY The .Fn memrchr function first appeared in GNU libc 2.1.91, this implementation first appeared in .Fx 6.4 , coming from .Ox 4.3 . Index: stable/9/lib/libc/sys/cap_new.2 =================================================================== --- stable/9/lib/libc/sys/cap_new.2 (revision 237215) +++ stable/9/lib/libc/sys/cap_new.2 (revision 237216) @@ -1,475 +1,475 @@ .\" .\" Copyright (c) 2008-2010 Robert N. M. Watson .\" All rights reserved. .\" .\" This software was developed at the University of Cambridge Computer .\" Laboratory with support from a grant from Google, 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. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd July 20, 2011 .Dt CAP_NEW 2 .Os .Sh NAME .Nm cap_new , .Nm cap_getrights .Nd System calls to manipulate capabilities .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capability.h .Ft int .Fn cap_new "int fd" "cap_rights_t rights" .Ft int .Fn cap_getrights "int fd" "cap_rights_t *rightsp" .Sh DESCRIPTION Capabilities are special file descriptors derived from an existing file descriptor, such as one returned by .Xr fhopen 2 , .Xr kqueue 2 , .Xr mq_open 2 , .Xr open 2 , .Xr pipe 2 , .Xr shm_open 2 , .Xr socket 2 , or .Xr socketpair 2 , but with a restricted set of permitted operations determined by a rights mask set when the capability is created. These restricted rights cannot be changed after the capability is created, although further capabilities with yet more restricted rights may be created from an existing capability. In every other sense, a capability behaves in the same way as the file descriptor it was created from. .Pp .Fn cap_new creates a new capability for the existing file descriptor .Fa fd , and returns a file descriptor for it. Operations on the capability will be limited to those permitted by .Fa rights , which is static for the lifetime of the capability. If .Fa fd refers to an existing capability, then .Fa rights must be equal to or a subset of the rights on that capability. As with .Xr dup 2 and .Xr dup2 2 , many properties are shared between the new capability and the existing file descriptor, including open file flags, blocking disposition, and file offset. Many applications will prefer to use the .Xr cap_limitfd 3 library call, part of .Xr libcapsicum 3 , as it offers a more convenient interface. .Pp .Fn cap_getrights queries the rights associated with the capability referred to by file descriptor .Fa fd . .Pp These system calls, when combined with .Xr cap_enter 2 , may be used to construct process sandboxes with highly granular rights assignment. .Sh RIGHTS The following rights may be specified in a new capability rights mask: .Bl -tag -width CAP_EXTATTR_DELETE .It Dv CAP_ACCEPT Permit .Xr accept 2 . .It Dv CAP_ACL_CHECK Permit checking of an ACL on a file descriptor; there is no cross-reference for this system call. .It Dv CAP_ACL_DELETE Permit .Xr acl_delete_fd_np 3 . .It Dv CAP_ACL_GET Permit .Xr acl_get_fd 3 and .Xr acl_get_fd_np 3 . .It Dv CAP_ACL_SET Permit .Xr acl_set_fd 3 and .Xr acl_set_fd_np 3 . .It Dv CAP_BIND Permit .Xr bind 2 . Note that sockets can also become bound implicitly as a result of .Xr connect 2 or .Xr send 2 , and that socket options set with .Xr setsockopt 2 may also affect binding behavior. .It Dv CAP_CONNECT Permit .Xr connect 2 ; also required for .Xr sendto 2 with a non-NULL destination address. .It Dv CAP_EVENT Permit .Xr select 2 , .Xr poll 2 , and .Xr kevent 2 to be used in monitoring the file descriptor for events. .It Dv CAP_FEXECVE Permit .Xr fexecve 2 ; .Dv CAP_READ will also be required. .It Dv CAP_EXTATTR_DELETE Permit .Xr extattr_delete_fd 2 . .It Dv CAP_EXTATTR_GET Permit .Xr extattr_get_fd 2 . .It Dv CAP_EXTATTR_LIST Permit .Xr extattr_list_fd 2 . .It Dv CAP_EXTATTR_SET Permit .Xr extattr_set_fd 2 . .It Dv CAP_FCHDIR Permit .Xr fchdir 2 . .It Dv CAP_FCHFLAGS Permit .Xr fchflags 2 . .It Dv CAP_FCHMOD Permit .Xr fchmod 2 . .It Dv CAP_FCHOWN Permit .Xr fchown 2 . .It Dv CAP_FCNTL Permit .Xr fcntl 2 ; be aware that this call provides indirect access to other operations, such as .Xr flock 2 . .It Dv CAP_FLOCK Permit .Xr flock 2 and related calls. .It Dv CAP_FPATHCONF Permit .Xr fpathconf 2 . .It Dv CAP_FSCK Permit UFS background-fsck operations on the descriptor. .It Dv CAP_FSTAT Permit .Xr fstat 2 . .It Dv CAP_FSTATFS Permit .Xr fstatfs 2 . .It Dv CAP_FSYNC Permit .Xr aio_fsync 2 and .Xr fsync 2 . .Pp .It Dv CAP_FTRUNCATE Permit .Xr ftruncate 2 . .It Dv CAP_FUTIMES Permit .Xr futimes 2 . .It Dv CAP_GETPEERNAME Permit .Xr getpeername 2 . .It Dv CAP_GETSOCKNAME Permit .Xr getsockname 2 . .It Dv CAP_GETSOCKOPT Permit .Xr getsockopt 2 . .It Dv CAP_IOCTL Permit .Xr ioctl 2 . Be aware that this system call has enormous scope, including potentially global scope for some objects. .It Dv CAP_KEVENT Permit .Xr kevent 2 ; .Dv CAP_EVENT is also required on file descriptors that will be monitored using .Xr kevent 2 . .It Dv CAP_LISTEN Permit .Xr listen 2 ; not much use (generally) without .Dv CAP_BIND . .It Dv CAP_LOOKUP Permit the file descriptor to be used as a starting directory for calls such as .Xr linkat 2 , .Xr openat 2 , and .Xr unlinkat 2 . Note that these calls are not available in capability mode as they manipulate a global name space; see .Xr cap_enter 2 for details. .It Dv CAP_MAC_GET Permit .Xr mac_get_fd 3 . .It Dv CAP_MAC_SET Permit .Xr mac_set_fd 3 . .It Dv CAP_MMAP Permit .Xr mmap 2 ; specific invocations may also require .Dv CAP_READ or .Dv CAP_WRITE . .Pp .It Dv CAP_PDGETPID Permit .Xr pdgetpid 2 . .It Dv CAP_PDKILL Permit .Xr pdkill 2 . .It Dv CAP_PDWAIT Permit .Xr pdwait4 2 . .It Dv CAP_PEELOFF Permit .Xr sctp_peeloff 2 . .It Dv CAP_READ Allow .Xr aio_read 2 , .Xr pread 2 , .Xr read 2 , .Xr recv 2 , .Xr recvfrom 2 , .Xr recvmsg 2 , and related system calls. .Pp For files and other seekable objects, .Dv CAP_SEEK may also be required. .It Dv CAP_REVOKE Permit .Xr frevoke 2 in certain ABI compatibility modes that support this system call. .It Dv CAP_SEEK Permit operations that seek on the file descriptor, such as .Xr lseek 2 , but also required for I/O system calls that modify the file offset, such as .Xr read 2 and .Xr write 2 . .It Dv CAP_SEM_GETVALUE Permit .Xr sem_getvalue 3 . .It Dv CAP_SEM_POST Permit .Xr sem_post 3 . .It Dv CAP_SEM_WAIT Permit .Xr sem_wait 3 and .Xr sem_trywait 3 . .It Dv CAP_SETSOCKOPT Permit .Xr setsockopt 2 ; this controls various aspects of socket behavior and may affect binding, connecting, and other behaviors with global scope. .It Dv CAP_SHUTDOWN Permit explicit .Xr shutdown 2 ; closing the socket will also generally shut down any connections on it. .It Dv CAP_TTYHOOK Allow configuration of TTY hooks, such as .Xr snp 4 , on the file descriptor. .It Dv CAP_WRITE Allow .Xr aio_write 2 , .Xr pwrite 2 , .Xr send 2 , .Xr sendmsg 2 , .Xr sendto 2 , .Xr write 2 , and related system calls. .Pp For files and other seekable objects, .Dv CAP_SEEK may also be required. .Pp For .Xr sendto 2 with a non-NULL connection address, .Dv CAP_CONNECT is also required. .El .Sh CAVEAT The .Fn cap_new system call and the capabilities it creates may be used to assign fine-grained rights to sandboxed processes running in capability mode. However, the semantics of objects accessed via file descriptors are complex, so caution should be exercised in passing object capabilities into sandboxes. .Sh RETURN VALUES If successful, .Fn cap_new returns a non-negative integer, termed a file descriptor. It returns -1 on failure, and sets .Va errno to indicate the error. .Pp .Rv -std cap_getrights .Sh ERRORS .Fn cap_new may return the following errors: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid active descriptor. .It Bq Er EINVAL An invalid right has been requested in .Fa rights . .It Bq Er EMFILE The process has already reached its limit for open file descriptors. .It Bq Er ENFILE The system file table is full. .It Bq Er EPERM .Fa rights contains requested rights not present in the current rights mask associated with the capability referenced by .Fa fd , if any. .El .Pp .Fn cap_getrights may return the following errors: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid active descriptor. .It Bq Er EINVAL The .Fa fd argument is not a capability. .El .Sh SEE ALSO .Xr accept 2 , .Xr aio_fsync 2 , .Xr aio_read 2 , .Xr aio_write 2 , .Xr bind 2 , .Xr cap_enter 2 , .Xr connect 2 , .Xr dup 2 , .Xr dup2 2 , .Xr extattr_delete_fd 2 , .Xr extattr_get_fd 2 , .Xr extattr_list_fd 2 , .Xr extattr_set_fd 2 , .Xr fchflags 2 , .Xr fchown 2 , .Xr fcntl 2 , .Xr fexecve 2 , .Xr fhopen 2 , .Xr flock 2 , .Xr fpathconf 2 , .Xr fstat 2 , .Xr fstatfs 2 , .Xr fsync 2 , .Xr ftruncate 2 , .Xr futimes 2 , .Xr getpeername 2 , .Xr getsockname 2 , .Xr getsockopt 2 , .Xr ioctl 2 , .Xr kevent 2 , .Xr kqueue 2 , .Xr linkat 2 , .Xr listen 2 , .Xr mmap 2 , .Xr mq_open 2 , .Xr open 2 , .Xr openat 2 , .Xr pdgetpid 2 , .Xr pdkill 2 , .Xr pdwait4 2 , .Xr pipe 2 , .Xr poll 2 , .Xr pread 2 , .Xr pwrite 2 , .Xr read 2 , .Xr recv 2 , .Xr recvfrom 2 , .Xr recvmsg 2 , .Xr sctp_peeloff 2 , .Xr select 2 , .Xr send 2 , .Xr sendmsg 2 , .Xr sendto 2 , .Xr setsockopt 2 , .Xr shm_open 2 , .Xr shutdown 2 , .Xr socket 2 , .Xr socketpair 2 , .Xr unlinkat 2 , .Xr write 2 , .Xr acl_delete_fd_np 3 , .Xr acl_get_fd 3 , .Xr acl_get_fd_np 3 , .Xr acl_set_fd_np 3 , .Xr cap_limitfd 3 , .Xr libcapsicum 3 , .Xr mac_get_fd 3 , .Xr mac_set_fd 3 , .Xr sem_getvalue 3 , .Xr sem_post 3 , .Xr sem_trywait 3 , .Xr sem_wait 3 , .Xr capsicum 4 , .Xr snp 4 .Sh HISTORY Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. +.Sh AUTHORS +These functions and the capability facility were created by +.An "Robert N. M. Watson" +at the University of Cambridge Computer Laboratory with support from a grant +from Google, Inc. .Sh BUGS This man page should list the set of permitted system calls more specifically for each capability right. .Pp Capability rights sometimes have unclear indirect impacts, which should be documented, or at least hinted at. -.Sh AUTHORS -These functions and the capability facility were created by -.An "Robert N. M. Watson" -at the University of Cambridge Computer Laboratory with support from a grant -from Google, Inc. Index: stable/9/lib/libc/sys/cpuset.2 =================================================================== --- stable/9/lib/libc/sys/cpuset.2 (revision 237215) +++ stable/9/lib/libc/sys/cpuset.2 (revision 237216) @@ -1,228 +1,228 @@ .\" Copyright (c) 2008 Christian Brueffer .\" Copyright (c) 2008 Jeffrey Roberson .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 8, 2010 .Dt CPUSET 2 .Os .Sh NAME .Nm cpuset , .Nm cpuset_getid , .Nm cpuset_setid .Nd manage CPU affinity sets .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/cpuset.h .Ft int .Fn cpuset "cpusetid_t *setid" .Ft int .Fn cpuset_setid "cpuwhich_t which" "id_t id" "cpusetid_t setid" .Ft int .Fn cpuset_getid "cpulevel_t level" "cpuwhich_t which" "id_t id" "cpusetid_t *setid" .Sh DESCRIPTION The .Nm family of system calls allow applications to control sets of processors and assign processes and threads to these sets. Processor sets contain lists of CPUs that members may run on and exist only as long as some process is a member of the set. All processes in the system have an assigned set. The default set for all processes in the system is the set numbered 1. Threads belong to the same set as the process which contains them, however, they may further restrict their set with the anonymous per-thread mask. .Pp Sets are referenced by a number of type .Ft cpuset_id_t . Each thread has a root set, an assigned set, and an anonymous mask. Only the root and assigned sets are numbered. The root set is the set of all CPUs available in the system or in the system partition the thread is running in. The assigned set is a subset of the root set and is administratively assignable on a per-process basis. Many processes and threads may be members of a numbered set. .Pp The anonymous set is a further thread-specific refinement on the assigned set. It is intended that administrators will manipulate numbered sets using .Xr cpuset 1 while application developers will manipulate anonymous sets using .Xr cpuset_setaffinity 2 . .Pp To select the correct set a value of type .Ft cpulevel_t is used. -The following values for +The following values for .Fa level are supported: .Bl -column CPU_LEVEL_CPUSET -offset indent .It Dv CPU_LEVEL_ROOT Ta "Root set" .It Dv CPU_LEVEL_CPUSET Ta "Assigned set" .It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument" .El .Pp The .Fa which argument determines how the value of .Fa id is interpreted and is of type .Ft cpuwhich_t . The .Fa which argument may have the following values: .Bl -column CPU_WHICH_CPUSET -offset indent .It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)" .It Dv CPU_WHICH_PID Ta "id is pid_t (process id)" .It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)" .It Dv CPU_WHICH_IRQ Ta "id is an irq number" .El .Pp An .Fa id of '-1' may be used with a .Fa which of .Dv CPU_WHICH_TID , .Dv CPU_WHICH_PID , or .Dv CPU_WHICH_CPUSET to mean the current thread, process, or current thread's cpuset. All cpuset syscalls allow this usage. .Pp A .Fa level argument of .Dv CPU_LEVEL_WHICH combined with a .Fa which argument other than .Dv CPU_WHICH_CPUSET refers to the anonymous mask of the object. This mask does not have an id and may only be manipulated with .Xr cpuset_setaffinity 2 . .Pp .Fn cpuset creates a new set containing the same CPUs as the root set of the current process and stores its id in the space provided by .Fa setid . On successful completion the calling process joins the set and is the only member. Children inherit this set after a call to .Xr fork 2 . .Pp .Fn cpuset_setid -attempts to set the id of the object specified by the +attempts to set the id of the object specified by the .Fa which argument. Currently .Dv CPU_WHICH_PID is the only acceptable value for which as threads do not have an id distinct from their process and the API does not permit changing the id of an existing set. Upon successful completion all of the threads in the target process will be running on CPUs permitted by the set. .Pp .Fn cpuset_getid -retrieves a set id from the object indicated by +retrieves a set id from the object indicated by .Fa which and stores it in the space pointed to by .Fa setid . The retrieved id may be that of either the root or assigned set -depending on the value of +depending on the value of .Fa level . .Fa level should be .Dv CPU_LEVEL_CPUSET or .Dv CPU_LEVEL_ROOT to get the set id from the process or thread specified by the .Fa id argument. Specifying .Dv CPU_LEVEL_WHICH with a process or thread is unsupported since this references the unnumbered anonymous mask. .Pp The actual contents of the sets may be retrieved or manipulated using .Xr cpuset_getaffinity 2 and .Xr cpuset_setaffinity 2 . See those manual pages for more detail. .Sh RETURN VALUES .Rv -std .Sh ERRORS The following error codes may be set in .Va errno : .Bl -tag -width Er .It Bq Er EINVAL The .Fa which or .Fa level argument was not a valid value. .It Bq Er EDEADLK The .Fn cpuset_setid call would leave a thread without a valid CPU to run on because the set does not overlap with the thread's anonymous mask. .It Bq Er EFAULT The setid pointer passed to .Fn cpuset_getid or .Fn cpuset was invalid. .It Bq Er ESRCH The object specified by the .Fa id and .Fa which arguments could not be found. .It Bq Er EPERM The calling process did not have the credentials required to complete the operation. .It Bq Er ENFILE There was no free .Ft cpusetid_t for allocation. .El .Sh SEE ALSO .Xr cpuset 1 , .Xr cpuset_getaffinity 2 , .Xr cpuset_setaffinity 2 , .Xr CPU_SET 3 , .Xr pthread_affinity_np 3 , .Xr pthread_attr_affinity_np 3 .Sh HISTORY The .Nm family of system calls first appeared in .Fx 7.1 . .Sh AUTHOR .An Jeffrey Roberson Aq jeff@FreeBSD.org Index: stable/9/lib/libc/sys/cpuset_getaffinity.2 =================================================================== --- stable/9/lib/libc/sys/cpuset_getaffinity.2 (revision 237215) +++ stable/9/lib/libc/sys/cpuset_getaffinity.2 (revision 237216) @@ -1,165 +1,165 @@ .\" Copyright (c) 2008 Christian Brueffer .\" Copyright (c) 2008 Jeffrey Roberson .\" 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. .\" .\" $FreeBSD$ .\" .Dd September 10, 2010 .Dt CPUSET 2 .Os .Sh NAME .Nm cpuset_getaffinity , .Nm cpuset_setaffinity .Nd manage CPU affinity .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/param.h .In sys/cpuset.h .Ft int .Fn cpuset_getaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "cpuset_t *mask" .Ft int .Fn cpuset_setaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const cpuset_t *mask" .Sh DESCRIPTION .Fn cpuset_getaffinity and .Fn cpuset_setaffinity -allow the manipulation of sets of CPUs available to processes, threads, +allow the manipulation of sets of CPUs available to processes, threads, interrupts, jails and other resources. These functions may manipulate sets of CPUs that contain many processes or per-object anonymous masks that effect only a single object. .Pp The valid values for the .Fa level and .Fa which arguments are documented in .Xr cpuset 2 . These arguments specify which object and which set of the object we are referring to. Not all possible combinations are valid. For example, only processes may belong to a numbered set accessed by a .Fa level argument of .Dv CPU_LEVEL_CPUSET . All resources, however, have a mask which may be manipulated with .Dv CPU_LEVEL_WHICH . .Pp Masks of type .Ft cpuset_t are composed using the .Xr CPU_SET 2 macros. The kernel tolerates large sets as long as all CPUs specified in the set exist. Sets smaller than the kernel uses generate an error on calls to .Fn cpuset_getaffinity even if the result set would fit within the user supplied set. Calls to .Fn cpuset_setaffinity tolerate small sets with no restrictions. .Pp The supplied mask should have a size of .Fa setsize bytes. This size is usually provided by calling .Li sizeof(mask) which is ultimately determined by the value of .Dv CPU_SETSIZE as defined in .In sys/cpuset.h . .Pp .Fn cpuset_getaffinity retrieves the mask from the object specified by .Fa level , .Fa which and .Fa id and stores it in the space provided by .Fa mask . .Pp .Fn cpuset_setaffinity attempts to set the mask for the object specified by .Fa level , .Fa which and .Fa id to the value in .Fa mask . .Pp .Sh RETURN VALUES .Rv -std .Sh ERRORS The following error codes may be set in .Va errno : .Bl -tag -width Er .It Bq Er EINVAL The .Fa level or .Fa which argument was not a valid value. .It Bq Er EINVAL The .Fa mask argument specified when calling .Fn cpuset_setaffinity was not a valid value. .It Bq Er EDEADLK The .Fn cpuset_setaffinity call would leave a thread without a valid CPU to run on because the set does not overlap with the thread's anonymous mask. .It Bq Er EFAULT The mask pointer passed was invalid. .It Bq Er ESRCH The object specified by the .Fa id and .Fa which arguments could not be found. .It Bq Er ERANGE The .Fa cpusetsize was either preposterously large or smaller than the kernel set size. .It Bq Er EPERM The calling process did not have the credentials required to complete the operation. .El .Sh SEE ALSO .Xr cpuset 1 , .Xr cpuset 2 , .Xr cpuset_getid 2 , .Xr cpuset_setid 2 , .Xr CPU_SET 3 , .Xr pthread_affinity_np 3 , .Xr pthread_attr_affinity_np 3 .Sh HISTORY The .Nm family of system calls first appeared in .Fx 7.1 . .Sh AUTHOR .An Jeffrey Roberson Aq jeff@FreeBSD.org Index: stable/9/lib/libc/sys/kqueue.2 =================================================================== --- stable/9/lib/libc/sys/kqueue.2 (revision 237215) +++ stable/9/lib/libc/sys/kqueue.2 (revision 237216) @@ -1,589 +1,589 @@ .\" 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 February 15, 2012 .Dt KQUEUE 2 .Os .Sh NAME .Nm kqueue , .Nm kevent .Nd kernel event notification mechanism .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/event.h .In sys/time.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 */ intptr_t data; /* filter data value */ void *udata; /* opaque user data identifier */ }; .Ed .Pp The fields of .Fa struct kevent are: .Bl -tag -width XXXfilter .It ident Value used to identify this event. The exact interpretation is determined by the attached filter, but often is a file descriptor. .It filter Identifies the kernel filter used to process this event. The pre-defined system filters are described below. .It flags Actions to perform on the event. .It fflags Filter-specific flags. .It data Filter-specific data value. .It udata Opaque user-defined value passed through the kernel unchanged. .El .Pp The .Va flags field can contain the following values: .Bl -tag -width XXXEV_ONESHOT .It 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 EV_ENABLE Permit .Fn kevent to return the event if it is triggered. .It EV_DISABLE Disable the event so .Fn kevent will not return it. The filter itself is not disabled. .It EV_DISPATCH Disable the event source immediately after delivery of an event. -See +See .Dv EV_DISABLE above. .It 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 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 +When a filter is successfully added the .Va data field will be zero. .It 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 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 EV_EOF Filters may set this flag to indicate filter-specific EOF condition. .It 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 EVFILT_SIGNAL .It 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 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 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. .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 EV_EOF in .Va flags . This may be cleared by passing in EV_CLEAR, 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 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 EV_EOF when the reader disconnects, and for the fifo case, this may be cleared by use of EV_CLEAR. 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 EVFILT_READ case. .It EVFILT_AIO The sigevent portion of the AIO request is filled in, with .Va sigev_notify_kqueue containing the descriptor of the kqueue that the event should be attached to, .Va sigev_notify_kevent_flags containing the kevent flags which should be EV_ONESHOT, EV_CLEAR or EV_DISPATCH, .Va sigev_value containing the udata value, and .Va sigev_notify set to SIGEV_KEVENT. When the .Fn aio_* system call is made, the event will be registered with the specified kqueue, and the .Va ident argument set to the .Fa struct aiocb returned by the .Fn aio_* system call. The filter returns under the same conditions as aio_error. .It 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 XXNOTE_RENAME .It NOTE_DELETE The .Fn unlink system call was called on the file referenced by the descriptor. .It NOTE_WRITE A write occurred on the file referenced by the descriptor. .It NOTE_EXTEND The file referenced by the descriptor was extended. .It NOTE_ATTRIB The file referenced by the descriptor had its attributes changed. .It NOTE_LINK The link count on the file changed. .It NOTE_RENAME The file referenced by the descriptor was renamed. .It NOTE_REVOKE Access to the file was revoked via .Xr revoke 2 or the underlying file system was unmounted. .El .Pp On return, .Va fflags contains the events which triggered the filter. .It 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 XXNOTE_TRACKERR .It NOTE_EXIT The process has exited. The exit status will be stored in .Va data . .It NOTE_FORK The process has called .Fn fork . .It NOTE_EXEC The process has executed a new process via .Xr execve 2 or similar call. .It NOTE_TRACK Follow a process across .Fn fork calls. The parent process will return with NOTE_TRACK set in the .Va fflags field, while the child process will return with NOTE_CHILD set in .Va fflags and the parent PID in .Va data . .It NOTE_TRACKERR This flag is returned if the system was unable to attach an event to the child process, usually due to resource limitations. .El .Pp On return, .Va fflags contains the events which triggered the filter. .It 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 SIG_IGN. 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 EV_CLEAR flag internally. .It EVFILT_TIMER Establishes an arbitrary timer identified by .Va ident . When adding a timer, .Va data specifies the timeout period in milliseconds. The timer will be periodic unless EV_ONESHOT is specified. On return, .Va data contains the number of times the timeout has expired since the last call to .Fn kevent . This filter automatically sets the EV_CLEAR flag internally. There is a system wide limit on the number of timers which is controlled by the .Va kern.kq_calloutmax sysctl. .Pp On return, .Va fflags contains the events which triggered the filter. .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 +The lower 24 bits of the .Va fflags may be used for user defined flags and manipulated using the following: -.Bl -tag -width XXNOTE_FFLAGSMASK +.Bl -tag -width XXNOTE_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_COPY 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 XXNOTE_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 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 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 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 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 .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 signal 3 .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 jlemon@FreeBSD.org . .Sh BUGS The .Fa timeout value is limited to 24 hours; longer timeouts will be silently reinterpreted as 24 hours. Index: stable/9/lib/libc/sys/pathconf.2 =================================================================== --- stable/9/lib/libc/sys/pathconf.2 (revision 237215) +++ stable/9/lib/libc/sys/pathconf.2 (revision 237216) @@ -1,262 +1,262 @@ .\" Copyright (c) 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. .\" 4. 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. .\" .\" @(#)pathconf.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 7, 2009 .Dt PATHCONF 2 .Os .Sh NAME .Nm pathconf , .Nm lpathconf , .Nm fpathconf .Nd get configurable pathname variables .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft long .Fn pathconf "const char *path" "int name" .Ft long .Fn lpathconf "const char *path" "int name" .Ft long .Fn fpathconf "int fd" "int name" .Sh DESCRIPTION The .Fn pathconf , .Fn lpathconf and .Fn fpathconf system calls provide a method for applications to determine the current value of a configurable system limit or option variable associated with a pathname or file descriptor. .Pp For .Fn pathconf and .Fn lpathconf , the .Fa path argument is the name of a file or directory. For .Fn fpathconf , the .Fa fd argument is an open file descriptor. The .Fa name argument specifies the system variable to be queried. Symbolic constants for each name value are found in the include file .Li . .Pp The .Fn lpathconf system call is like .Fn pathconf except in the case where the named file is a symbolic link, in which case .Fn lpathconf returns information about the link, while .Fn pathconf returns information about the file the link references. .Pp The available values are as follows: .Pp .Bl -tag -width 6n .It Li _PC_LINK_MAX The maximum file link count. .It Li _PC_MAX_CANON The maximum number of bytes in terminal canonical input line. .It Li _PC_MAX_INPUT The minimum maximum number of bytes for which space is available in a terminal input queue. .It Li _PC_NAME_MAX The maximum number of bytes in a file name. .It Li _PC_PATH_MAX The maximum number of bytes in a pathname. .It Li _PC_PIPE_BUF The maximum number of bytes which will be written atomically to a pipe. .It Li _PC_CHOWN_RESTRICTED Return 1 if appropriate privilege is required for the .Xr chown 2 system call, otherwise 0. .St -p1003.1-2001 requires appropriate privilege in all cases, but this behavior was optional in prior editions of the standard. .It Li _PC_NO_TRUNC Return greater than zero if attempts to use pathname components longer than .Brq Dv NAME_MAX will result in an .Bq Er ENAMETOOLONG error; otherwise, such components will be truncated to .Brq Dv NAME_MAX . .St -p1003.1-2001 requires the error in all cases, but this behavior was optional in prior editions of the standard, and some .No non- Ns Tn POSIX Ns -compliant file systems do not support this behavior. .It Li _PC_VDISABLE Returns the terminal character disabling value. .It Li _PC_ASYNC_IO Return 1 if asynchronous I/O is supported, otherwise 0. .It Li _PC_PRIO_IO Returns 1 if prioritised I/O is supported for this file, otherwise 0. .It Li _PC_SYNC_IO Returns 1 if synchronised I/O is supported for this file, otherwise 0. .It Li _PC_ALLOC_SIZE_MIN Minimum number of bytes of storage allocated for any portion of a file. .It Li _PC_FILESIZEBITS Number of bits needed to represent the maximum file size. .It Li _PC_REC_INCR_XFER_SIZE Recommended increment for file transfer sizes between .Dv _PC_REC_MIN_XFER_SIZE and .Dv _PC_REC_MAX_XFER_SIZE . .It Li _PC_REC_MAX_XFER_SIZE Maximum recommended file transfer size. .It Li _PC_REC_MIN_XFER_SIZE Minimum recommended file transfer size. .It Li _PC_REC_XFER_ALIGN Recommended file transfer buffer alignment. .It Li _PC_SYMLINK_MAX Maximum number of bytes in a symbolic link. .It Li _PC_ACL_EXTENDED Returns 1 if an Access Control List (ACL) can be set on the specified file, otherwise 0. .It Li _PC_ACL_NFS4 Returns 1 if an NFSv4 ACLs can be set on the specified file, otherwise 0. .It Li _PC_ACL_PATH_MAX Maximum number of ACL entries per file. .It Li _PC_CAP_PRESENT Returns 1 if a capability state can be set on the specified file, otherwise 0. .It Li _PC_INF_PRESENT Returns 1 if an information label can be set on the specified file, otherwise 0. .It Li _PC_MAC_PRESENT Returns 1 if a Mandatory Access Control (MAC) label can be set on the specified file, otherwise 0. .It Li _PC_MIN_HOLE_SIZE If a file system supports the reporting of holes (see .Xr lseek 2 ) , .Fn pathconf and .Fn fpathconf return a positive number that represents the minimum hole size returned in bytes. The offsets of holes returned will be aligned to this same value. A special value of 1 is returned if the file system does not specify the minimum -hole size but still reports holes. +hole size but still reports holes. .El .Sh RETURN VALUES If the call to .Fn pathconf or .Fn fpathconf is not successful, \-1 is returned and .Va errno is set appropriately. Otherwise, if the variable is associated with functionality that does not have a limit in the system, \-1 is returned and .Va errno is not modified. Otherwise, the current variable value is returned. .Sh ERRORS If any of the following conditions occur, the .Fn pathconf and .Fn fpathconf system calls shall return -1 and set .Va errno to the corresponding value. .Bl -tag -width Er .It Bq Er EINVAL The value of the .Fa name argument is invalid. .It Bq Er EINVAL The implementation does not support an association of the variable name with the associated file. .El .Pp The .Fn pathconf system call will fail if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded .Brq Dv NAME_MAX characters (but see .Dv _PC_NO_TRUNC above), or an entire path name exceeded .Brq Dv PATH_MAX characters. .It Bq Er ENOENT The named file does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El .Pp The .Fn fpathconf system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid open file descriptor. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El .Sh SEE ALSO .Xr lseek 2 , .Xr sysctl 3 .Sh HISTORY The .Fn pathconf and .Fn fpathconf system calls first appeared in .Bx 4.4 . The .Fn lpathconf system call first appeared in .Fx 8.0 . Index: stable/9/lib/libc/sys/ptrace.2 =================================================================== --- stable/9/lib/libc/sys/ptrace.2 (revision 237215) +++ stable/9/lib/libc/sys/ptrace.2 (revision 237216) @@ -1,606 +1,606 @@ .\" $FreeBSD$ .\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ .\" .\" This file is in the public domain. .Dd February 19, 2012 .Dt PTRACE 2 .Os .Sh NAME .Nm ptrace .Nd process tracing and debugging .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/ptrace.h .Ft int .Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" .Sh DESCRIPTION The .Fn ptrace system call provides tracing and debugging facilities. It allows one process (the .Em tracing process) to control another (the .Em traced process). The tracing process must first attach to the traced process, and then issue a series of .Fn ptrace system calls to control the execution of the process, as well as access process memory and register state. For the duration of the tracing session, the traced process will be .Dq re-parented , with its parent process ID (and resulting behavior) changed to the tracing process. It is permissible for a tracing process to attach to more than one other process at a time. When the tracing process has completed its work, it must detach the traced process; if a tracing process exits without first detaching all processes it has attached, those processes will be killed. .Pp Most of the time, the traced process runs normally, but when it receives a signal (see .Xr sigaction 2 ) , it stops. The tracing process is expected to notice this via .Xr wait 2 or the delivery of a .Dv SIGCHLD signal, examine the state of the stopped process, and cause it to terminate or continue as appropriate. The signal may be a normal process signal, generated as a result of traced process behavior, or use of the .Xr kill 2 system call; alternatively, it may be generated by the tracing facility as a result of attaching, system calls, or stepping by the tracing process. The tracing process may choose to intercept the signal, using it to observe process behavior (such as .Dv SIGTRAP ) , or forward the signal to the process if appropriate. The .Fn ptrace system call is the mechanism by which all this happens. .Pp The .Fa request argument specifies what operation is being performed; the meaning of the rest of the arguments depends on the operation, but except for one special case noted below, all .Fn ptrace calls are made by the tracing process, and the .Fa pid argument specifies the process ID of the traced process or a corresponding thread ID. The .Fa request argument can be: .Bl -tag -width 12n .It Dv PT_TRACE_ME This request is the only one used by the traced process; it declares that the process expects to be traced by its parent. All the other arguments are ignored. (If the parent process does not expect to trace the child, it will probably be rather confused by the results; once the traced process stops, it cannot be made to continue except via .Fn ptrace . ) When a process has used this request and calls .Xr execve 2 or any of the routines built on it (such as .Xr execv 3 ) , it will stop before executing the first instruction of the new image. Also, any setuid or setgid bits on the executable being executed will be ignored. .It Dv PT_READ_I , Dv PT_READ_D These requests read a single .Vt int of data from the traced process's address space. Traditionally, .Fn ptrace has allowed for machines with distinct address spaces for instruction and data, which is why there are two requests: conceptually, .Dv PT_READ_I reads from the instruction space and .Dv PT_READ_D reads from the data space. In the current .Fx implementation, these two requests are completely identical. The .Fa addr argument specifies the address (in the traced process's virtual address space) at which the read is to be done. This address does not have to meet any alignment constraints. The value read is returned as the return value from .Fn ptrace . .It Dv PT_WRITE_I , Dv PT_WRITE_D These requests parallel .Dv PT_READ_I and .Dv PT_READ_D , except that they write rather than read. The .Fa data argument supplies the value to be written. .It Dv PT_IO This request allows reading and writing arbitrary amounts of data in the traced process's address space. The .Fa addr argument specifies a pointer to a .Vt "struct ptrace_io_desc" , which is defined as follows: .Bd -literal struct ptrace_io_desc { int piod_op; /* I/O operation */ void *piod_offs; /* child offset */ void *piod_addr; /* parent offset */ size_t piod_len; /* request length */ }; /* * Operations in piod_op. */ #define PIOD_READ_D 1 /* Read from D space */ #define PIOD_WRITE_D 2 /* Write to D space */ #define PIOD_READ_I 3 /* Read from I space */ #define PIOD_WRITE_I 4 /* Write to I space */ .Ed .Pp The .Fa data argument is ignored. The actual number of bytes read or written is stored in .Va piod_len upon return. .It Dv PT_CONTINUE The traced process continues execution. The .Fa addr argument is an address specifying the place where execution is to be resumed (a new value for the program counter), or .Po Vt caddr_t Pc Ns 1 to indicate that execution is to pick up where it left off. The .Fa data argument provides a signal number to be delivered to the traced process as it resumes execution, or 0 if no signal is to be sent. .It Dv PT_STEP The traced process is single stepped one instruction. The .Fa addr argument should be passed .Po Vt caddr_t Pc Ns 1 . The .Fa data argument provides a signal number to be delivered to the traced process as it resumes execution, or 0 if no signal is to be sent. .It Dv PT_KILL The traced process terminates, as if .Dv PT_CONTINUE had been used with .Dv SIGKILL given as the signal to be delivered. .It Dv PT_ATTACH This request allows a process to gain control of an otherwise unrelated process and begin tracing it. It does not need any cooperation from the to-be-traced process. In this case, .Fa pid specifies the process ID of the to-be-traced process, and the other two arguments are ignored. This request requires that the target process must have the same real UID as the tracing process, and that it must not be executing a setuid or setgid executable. (If the tracing process is running as root, these restrictions do not apply.) The tracing process will see the newly-traced process stop and may then control it as if it had been traced all along. .It Dv PT_DETACH This request is like PT_CONTINUE, except that it does not allow specifying an alternate place to continue execution, and after it succeeds, the traced process is no longer traced and continues execution normally. .It Dv PT_GETREGS This request reads the traced process's machine registers into the .Do .Vt "struct reg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_SETREGS This request is the converse of .Dv PT_GETREGS ; it loads the traced process's machine registers from the .Do .Vt "struct reg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_GETFPREGS This request reads the traced process's floating-point registers into the .Do .Vt "struct fpreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_SETFPREGS This request is the converse of .Dv PT_GETFPREGS ; it loads the traced process's floating-point registers from the .Do .Vt "struct fpreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_GETDBREGS This request reads the traced process's debug registers into the .Do .Vt "struct dbreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_SETDBREGS This request is the converse of .Dv PT_GETDBREGS ; it loads the traced process's debug registers from the .Do .Vt "struct dbreg" .Dc (defined in .In machine/reg.h ) pointed to by .Fa addr . .It Dv PT_LWPINFO This request can be used to obtain information about the kernel thread, also known as light-weight process, that caused the traced process to stop. The .Fa addr argument specifies a pointer to a .Vt "struct ptrace_lwpinfo" , which is defined as follows: .Bd -literal struct ptrace_lwpinfo { lwpid_t pl_lwpid; int pl_event; int pl_flags; sigset_t pl_sigmask; sigset_t pl_siglist; siginfo_t pl_siginfo; char pl_tdname[MAXCOMLEN + 1]; int pl_child_pid; }; .Ed .Pp The .Fa data argument is to be set to the size of the structure known to the caller. This allows the structure to grow without affecting older programs. .Pp The fields in the .Vt "struct ptrace_lwpinfo" have the following meaning: .Bl -tag -width indent -compact .It pl_lwpid LWP id of the thread .It pl_event Event that caused the stop. Currently defined events are .Bl -tag -width indent -compact .It PL_EVENT_NONE No reason given .It PL_EVENT_SIGNAL Thread stopped due to the pending signal .El .It pl_flags Flags that specify additional details about observed stop. Currently defined flags are: .Bl -tag -width indent -compact .It PL_FLAG_SCE The thread stopped due to system call entry, right after the kernel is entered. The debugger may examine syscall arguments that are stored in memory and registers according to the ABI of the current process, and modify them, if needed. .It PL_FLAG_SCX The thread is stopped immediately before syscall is returning to the usermode. The debugger may examine system call return values in the ABI-defined registers and/or memory. .It PL_FLAG_EXEC When .Dv PL_FLAG_SCX is set, this flag may be additionally specified to inform that the program being executed by debuggee process has been changed by successful execution of a system call from the .Fn execve 2 family. .It PL_FLAG_SI Indicates that .Va pl_siginfo member of .Vt "struct ptrace_lwpinfo" contains valid information. .It PL_FLAG_FORKED Indicates that the process is returning from a call to .Fn fork 2 that created a new child process. The process identifier of the new process is available in the .Va pl_child_pid member of .Vt "struct ptrace_lwpinfo" . .It PL_FLAG_CHILD The flag is set for first event reported from a new child, which is automatically attached due to .Dv PT_FOLLOW_FORK enabled. .El .It pl_sigmask The current signal mask of the LWP .It pl_siglist The current pending set of signals for the LWP. Note that signals that are delivered to the process would not appear on an LWP siglist until the thread is selected for delivery. .It pl_siginfo The siginfo that accompanies the signal pending. Only valid for .Dv PL_EVENT_SIGNAL stop when .Dv PL_FLAG_SI is set in .Va pl_flags . .It pl_tdname The name of the thread. .It pl_child_pid The process identifier of the new child process. Only valid for a .Dv PL_EVENT_SIGNAL stop when .Dv PL_FLAG_FORKED is set in .Va pl_flags . .El .It PT_GETNUMLWPS This request returns the number of kernel threads associated with the traced process. .It PT_GETLWPLIST This request can be used to get the current thread list. A pointer to an array of type .Vt lwpid_t should be passed in .Fa addr , with the array size specified by .Fa data . The return value from .Fn ptrace is the count of array entries filled in. .It PT_SETSTEP This request will turn on single stepping of the specified process. .It PT_CLEARSTEP This request will turn off single stepping of the specified process. .It PT_SUSPEND This request will suspend the specified thread. .It PT_RESUME This request will resume the specified thread. .It PT_TO_SCE This request will trace the specified process on each system call entry. .It PT_TO_SCX This request will trace the specified process on each system call exit. .It PT_SYSCALL This request will trace the specified process on each system call entry and exit. .It PT_FOLLOW_FORK This request controls tracing for new child processes of a traced process. If .Fa data is non-zero, then new child processes will enable tracing and stop before executing their first instruction. If .Fa data is zero, then new child processes will execute without tracing enabled. By default, tracing is not enabled for new child processes. Child processes do not inherit this property. The traced process will set the .Dv PL_FLAG_FORKED flag upon exit from a system call that creates a new process. .It PT_VM_TIMESTAMP This request returns the generation number or timestamp of the memory map of the traced process as the return value from .Fn ptrace . This provides a low-cost way for the tracing process to determine if the VM map changed since the last time this request was made. .It PT_VM_ENTRY This request is used to iterate over the entries of the VM map of the traced process. The .Fa addr -argument specifies a pointer to a +argument specifies a pointer to a .Vt "struct ptrace_vm_entry" , which is defined as follows: .Bd -literal struct ptrace_vm_entry { int pve_entry; int pve_timestamp; u_long pve_start; u_long pve_end; u_long pve_offset; u_int pve_prot; u_int pve_pathlen; long pve_fileid; uint32_t pve_fsid; char *pve_path; }; .Ed .Pp The first entry is returned by setting .Va pve_entry to zero. Subsequent entries are returned by leaving .Va pve_entry unmodified from the value returned by previous requests. The .Va pve_timestamp field can be used to detect changes to the VM map while iterating over the entries. The tracing process can then take appropriate action, such as restarting. By setting .Va pve_pathlen to a non-zero value on entry, the pathname of the backing object is returned in the buffer pointed to by .Va pve_path , provided the entry is backed by a vnode. The .Va pve_pathlen field is updated with the actual length of the pathname (including the terminating null character). The .Va pve_offset field is the offset within the backing object at which the range starts. The range is located in the VM space at .Va pve_start and extends up to .Va pve_end (inclusive). .Pp The .Fa data argument is ignored. .El .Pp Additionally, machine-specific requests can exist. .Sh RETURN VALUES Some requests can cause .Fn ptrace to return \-1 as a non-error value; to disambiguate, .Va errno can be set to 0 before the call and checked afterwards. .Sh ERRORS The .Fn ptrace system call may fail if: .Bl -tag -width Er .It Bq Er ESRCH .Bl -bullet -compact .It No process having the specified process ID exists. .El .It Bq Er EINVAL .Bl -bullet -compact .It A process attempted to use .Dv PT_ATTACH on itself. .It The .Fa request argument was not one of the legal requests. .It The signal number (in .Fa data ) to .Dv PT_CONTINUE was neither 0 nor a legal signal number. .It .Dv PT_GETREGS , .Dv PT_SETREGS , .Dv PT_GETFPREGS , .Dv PT_SETFPREGS , .Dv PT_GETDBREGS , or .Dv PT_SETDBREGS was attempted on a process with no valid register set. (This is normally true only of system processes.) .It .Dv PT_VM_ENTRY was given an invalid value for .Fa pve_entry . This can also be caused by changes to the VM map of the process. .El .It Bq Er EBUSY .Bl -bullet -compact .It .Dv PT_ATTACH was attempted on a process that was already being traced. .It A request attempted to manipulate a process that was being traced by some process other than the one making the request. .It A request (other than .Dv PT_ATTACH ) specified a process that was not stopped. .El .It Bq Er EPERM .Bl -bullet -compact .It A request (other than .Dv PT_ATTACH ) attempted to manipulate a process that was not being traced at all. .It An attempt was made to use .Dv PT_ATTACH on a process in violation of the requirements listed under .Dv PT_ATTACH above. .El .It Bq Er ENOENT .Bl -bullet -compact .It .Dv PT_VM_ENTRY previously returned the last entry of the memory map. No more entries exist. .El .It Bq Er ENAMETOOLONG .Bl -bullet -compact .It .Dv PT_VM_ENTRY cannot return the pathname of the backing object because the buffer is not big enough. .Fa pve_pathlen holds the minimum buffer size required on return. .El .El .Sh SEE ALSO .Xr execve 2 , .Xr sigaction 2 , .Xr wait 2 , .Xr execv 3 , .Xr i386_clr_watch 3 , .Xr i386_set_watch 3 .Sh HISTORY The .Fn ptrace function appeared in .At v7 . Index: stable/9/lib/libc/sys/quotactl.2 =================================================================== --- stable/9/lib/libc/sys/quotactl.2 (revision 237215) +++ stable/9/lib/libc/sys/quotactl.2 (revision 237216) @@ -1,261 +1,261 @@ .\" Copyright (c) 1983, 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Robert Elz at The University of Melbourne. .\" .\" 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. .\" 4. 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. .\" .\" @(#)quotactl.2 8.2 (Berkeley) 3/10/95 .\" $FreeBSD$ .\" .Dd March 5, 1999 .Dt QUOTACTL 2 .Os .Sh NAME .Nm quotactl .Nd manipulate file system quotas .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In ufs/ufs/quota.h .Ft int .Fn quotactl "const char *path" "int cmd" "int id" "void *addr" .Sh DESCRIPTION The .Fn quotactl system call enables, disables and manipulates file system quotas. A quota control command given by .Fa cmd operates on the given filename .Fa path for the given user or group .Fa id . (NOTE: One should use the QCMD macro defined in .In ufs/ufs/quota.h to formulate the value for .Fa cmd . ) The address of an optional command specific data structure, .Fa addr , may be given; its interpretation is discussed below with each command. .Pp For commands that use the .Fa id identifier, it must be either -1 or any positive value. The value of -1 indicates that the current UID or GID should be used. Any other negative value will return an error. .Pp Currently quotas are supported only for the .Dq ufs file system. For .Dq ufs , a command is composed of a primary command (see below) and a command type used to interpret the .Fa id . Types are supported for interpretation of user identifiers (USRQUOTA) and group identifiers (GRPQUOTA). The .Dq ufs specific commands are: .Bl -tag -width Q_GETQUOTASIZEx .It Dv Q_QUOTAON Enable disk quotas for the file system specified by .Fa path . The command type specifies the type of the quotas being enabled. The .Fa addr argument specifies a file from which to take the quotas. The quota file must exist; it is normally created with the .Xr quotacheck 8 program. The .Fa id argument is unused. Only the super-user may turn quotas on. .It Dv Q_QUOTAOFF Disable disk quotas for the file system specified by .Fa path . The command type specifies the type of the quotas being disabled. The .Fa addr and .Fa id arguments are unused. Only the super-user may turn quotas off. .It Dv Q_GETQUOTASIZE Get the wordsize used to represent the quotas for the user or group (as determined by the command type). -Possible values are 32 for the old-style quota file +Possible values are 32 for the old-style quota file and 64 for the new-style quota file. The .Fa addr argument is a pointer to an integer into which the size is stored. The identifier .Fa id is not used. .It Dv Q_GETQUOTA Get disk quota limits and current usage for the user or group (as determined by the command type) with identifier .Fa id . The .Fa addr argument is a pointer to a .Fa struct dqblk structure (defined in .In ufs/ufs/quota.h ) . .It Dv Q_SETQUOTA Set disk quota limits for the user or group (as determined by the command type) with identifier .Fa id . The .Fa addr argument is a pointer to a .Fa struct dqblk structure (defined in .In ufs/ufs/quota.h ) . The usage fields of the .Fa dqblk structure are ignored. This system call is restricted to the super-user. .It Dv Q_SETUSE Set disk usage limits for the user or group (as determined by the command type) with identifier .Fa id . The .Fa addr argument is a pointer to a .Fa struct dqblk structure (defined in .In ufs/ufs/quota.h ) . Only the usage fields are used. This system call is restricted to the super-user. .It Dv Q_SYNC Update the on-disk copy of quota usages. The command type specifies which type of quotas are to be updated. The .Fa id and .Fa addr arguments are ignored. .El .Sh RETURN VALUES .Rv -std quotactl .Sh ERRORS The .Fn quotactl system call will fail if: .Bl -tag -width Er .It Bq Er EOPNOTSUPP The kernel has not been compiled with the .Dv QUOTA option. .It Bq Er EUSERS The quota table cannot be expanded. .It Bq Er EINVAL The .Fa cmd argument or the command type is invalid. In .Dv Q_GETQUOTASIZE , .Dv Q_GETQUOTA , .Dv Q_SETQUOTA , and .Dv Q_SETUSE , quotas are not currently enabled for this file system. .Pp The .Fa id argument to .Dv Q_GETQUOTA , -.Dv Q_SETQUOTA +.Dv Q_SETQUOTA or .Dv Q_SETUSE is a negative value. .It Bq Er EACCES In .Dv Q_QUOTAON , the quota file is not a plain file. .It Bq Er EACCES Search permission is denied for a component of a path prefix. .It Bq Er ENOTDIR A component of a path prefix was not a directory. .It Bq Er ENAMETOOLONG A component of either pathname exceeded 255 characters, or the entire length of either path name exceeded 1023 characters. .It Bq Er ENOENT A filename does not exist. .It Bq Er ELOOP Too many symbolic links were encountered in translating a pathname. .It Bq Er EROFS In .Dv Q_QUOTAON , either the file system on which quotas are to be enabled is mounted read-only or the quota file resides on a read-only file system. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to a file containing quotas. .It Bq Er EFAULT An invalid .Fa addr was supplied; the associated structure could not be copied in or out of the kernel. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er EPERM The call was privileged and the caller was not the super-user. .El .Sh SEE ALSO .Xr quota 1 , .Xr fstab 5 , .Xr edquota 8 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr repquota 8 .Sh HISTORY The .Fn quotactl system call appeared in .Bx 4.3 Reno . .Sh BUGS There should be some way to integrate this call with the resource limit interface provided by .Xr setrlimit 2 and .Xr getrlimit 2 . Index: stable/9/lib/libc/sys/sctp_generic_sendmsg.2 =================================================================== --- stable/9/lib/libc/sys/sctp_generic_sendmsg.2 (revision 237215) +++ stable/9/lib/libc/sys/sctp_generic_sendmsg.2 (revision 237216) @@ -1,90 +1,90 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd October 30, 2007 .Dt SCTP_GENERIC_SENDMSG 2 .Os .Sh NAME .Nm sctp_generic_sendmsg .Nm sctp_generic_sendmsg_iov .Nd send data to a peer .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft int .Fn sctp_generic_sendmsg "int s" "void *msg" "int msglen" "struct sockaddr *to" "socklen_t len" "struct sctp_sndrcvinfo *sinfo" "int flags" .Ft int .Fn sctp_generic_sendmsg_iov "int s" "struct iovec *iov" "int iovlen" "struct sockaddr *to" "struct sctp_sndrcvinfo *sinfo" "int flags" .Sh DESCRIPTION .Fn sctp_generic_sendmsg and .Fn sctp_generic_sendmsg_iov are the true system calls used by the .Xr sctp_sendmsg 3 -and +and .Xr sctp_send 3 function calls. These are more efficient since they are true system calls but they are specific to .Fx and can be expected .Em not to be present on any other operating system. For detailed usage please see either the .Xr sctp_send 3 or .Xr sctp_sendmsg 3 -function calls. +function calls. .Sh RETURN VALUES The call returns the number of bytes written on success and -1 upon failure. .Sh ERRORS .Bl -tag -width Er .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .El .Sh SEE ALSO .Xr sctp_send 3 , .Xr sctp_sendmsg 3 , .Xr sctp_sendmsgx 3 , .Xr sctp_sendx 3 , .Xr sctp 4 Index: stable/9/lib/libc/sys/sctp_peeloff.2 =================================================================== --- stable/9/lib/libc/sys/sctp_peeloff.2 (revision 237215) +++ stable/9/lib/libc/sys/sctp_peeloff.2 (revision 237216) @@ -1,81 +1,81 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd October 30, 2007 .Dt SCTP_PEELOFF 2 .Os .Sh NAME .Nm sctp_peeloff .Nd detach an association from a one-to-many socket to its own fd .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft int .Fn sctp_peeloff "int s" "sctp_assoc_t id" .Sh DESCRIPTION The .Fn sctp_peeloff system call attempts detach the association specified by .Fa id into its own separate socket. .Pp .Sh RETURN VALUES The call returns -1 on failure and the new socket descriptor upon success. .Sh ERRORS The .Fn sctp_peeloff system call can return the following errors: .Bl -tag -width Er .It Bq Er ENOTCONN -The +The .Fa id given to the call does not map to a valid association. .It Bq Er E2BIG The size of the address list exceeds the amount of data provided. .It Bq Er EBADF The argument .Fa s is not a valid descriptor. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .El .Sh SEE ALSO .Xr sctp 4 Index: stable/9/lib/libc/sys/select.2 =================================================================== --- stable/9/lib/libc/sys/select.2 (revision 237215) +++ stable/9/lib/libc/sys/select.2 (revision 237216) @@ -1,227 +1,227 @@ .\" 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. .\" 4. 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. .\" .\" @(#)select.2 8.2 (Berkeley) 3/25/94 .\" $FreeBSD$ .\" .Dd November 17, 2002 .Dt SELECT 2 .Os .Sh NAME .Nm select .Nd synchronous I/O multiplexing .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/select.h .Ft int .Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout" .Fn FD_SET fd &fdset .Fn FD_CLR fd &fdset .Fn FD_ISSET fd &fdset .Fn FD_ZERO &fdset .Sh DESCRIPTION The .Fn select system call examines the I/O descriptor sets whose addresses are passed in .Fa readfds , .Fa writefds , and .Fa exceptfds to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. The only exceptional condition detectable is out-of-band data received on a socket. The first .Fa nfds descriptors are checked in each set; i.e., the descriptors from 0 through .Fa nfds Ns No -1 in the descriptor sets are examined. On return, .Fn select replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. The .Fn select system call returns the total number of ready descriptors in all the sets. .Pp The descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such descriptor sets: .Fn FD_ZERO &fdset initializes a descriptor set .Fa fdset to the null set. .Fn FD_SET fd &fdset includes a particular descriptor .Fa fd in .Fa fdset . .Fn FD_CLR fd &fdset removes .Fa fd from .Fa fdset . .Fn FD_ISSET fd &fdset is non-zero if .Fa fd is a member of .Fa fdset , zero otherwise. The behavior of these macros is undefined if a descriptor value is less than zero or greater than or equal to .Dv FD_SETSIZE , which is normally at least equal to the maximum number of descriptors supported by the system. .Pp If .Fa timeout is not a null pointer, it specifies the maximum interval to wait for the selection to complete. System activity can lengthen the interval by an indeterminate amount. .Pp If .Fa timeout is a null pointer, the select blocks indefinitely. .Pp To effect a poll, the .Fa timeout argument should not be a null pointer, but it should point to a zero-valued timeval structure. .Pp Any of .Fa readfds , .Fa writefds , and .Fa exceptfds may be given as null pointers if no descriptors are of interest. .Sh RETURN VALUES The .Fn select system call returns the number of ready descriptors that are contained in the descriptor sets, or -1 if an error occurred. If the time limit expires, .Fn select returns 0. If .Fn select returns with an error, including one due to an interrupted system call, the descriptor sets will be unmodified. .Sh ERRORS An error return from .Fn select indicates: .Bl -tag -width Er .It Bq Er EBADF One of the descriptor sets specified an invalid descriptor. .It Bq Er EFAULT One of the arguments .Fa readfds , writefds , exceptfds , or .Fa timeout points to an invalid address. .It Bq Er EINTR A signal was delivered before the time limit expired and before any of the selected events occurred. .It Bq Er EINVAL The specified time limit is invalid. One of its components is negative or too large. .It Bq Er EINVAL The .Fa nfds argument was invalid. .El .Sh SEE ALSO .Xr accept 2 , .Xr connect 2 , .Xr getdtablesize 2 , .Xr gettimeofday 2 , .Xr kqueue 2 , .Xr poll 2 , .Xr read 2 , .Xr recv 2 , .Xr send 2 , .Xr write 2 , .Xr clocks 7 .Sh NOTES The default size of .Dv FD_SETSIZE is currently 1024. In order to accommodate programs which might potentially use a larger number of open files with .Fn select , it is possible to increase this size by having the program define .Dv FD_SETSIZE before the inclusion of any header which includes .In sys/types.h . .Pp If .Fa nfds is greater than the number of open files, .Fn select is not guaranteed to examine the unused file descriptors. For historical reasons, .Fn select will always examine the first 256 descriptors. .Sh STANDARDS The .Fn select system call and .Fn FD_CLR , .Fn FD_ISSET , .Fn FD_SET , and .Fn FD_ZERO macros conform with .St -p1003.1-2001 . .Sh HISTORY The .Fn select system call appeared in .Bx 4.2 . .Sh BUGS .St -susv2 allows systems to modify the original timeout in place. Thus, it is unwise to assume that the timeout value will be unmodified by the .Fn select system call. -.Fx +.Fx does not modify the return value, which can cause problems for applications ported from other systems. Index: stable/9/lib/libc/sys/sendfile.2 =================================================================== --- stable/9/lib/libc/sys/sendfile.2 (revision 237215) +++ stable/9/lib/libc/sys/sendfile.2 (revision 237216) @@ -1,316 +1,316 @@ .\" Copyright (c) 2003, David G. Lawrence .\" 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 unmodified, 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. .\" .\" $FreeBSD$ .\" .Dd January 7, 2010 .Dt SENDFILE 2 .Os .Sh NAME .Nm sendfile .Nd send a file to a socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In sys/uio.h .Ft int .Fo sendfile .Fa "int fd" "int s" "off_t offset" "size_t nbytes" .Fa "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags" .Fc .Sh DESCRIPTION The .Fn sendfile system call sends a regular file specified by descriptor .Fa fd out a stream socket specified by descriptor .Fa s . .Pp The .Fa offset argument specifies where to begin in the file. Should .Fa offset fall beyond the end of file, the system will return success and report 0 bytes sent as described below. The .Fa nbytes argument specifies how many bytes of the file should be sent, with 0 having the special meaning of send until the end of file has been reached. .Pp An optional header and/or trailer can be sent before and after the file data by specifying a pointer to a .Vt "struct sf_hdtr" , which has the following structure: .Pp .Bd -literal -offset indent -compact struct sf_hdtr { struct iovec *headers; /* pointer to header iovecs */ int hdr_cnt; /* number of header iovecs */ struct iovec *trailers; /* pointer to trailer iovecs */ int trl_cnt; /* number of trailer iovecs */ }; .Ed .Pp The .Fa headers and .Fa trailers pointers, if .Pf non- Dv NULL , point to arrays of .Vt "struct iovec" structures. See the .Fn writev system call for information on the iovec structure. The number of iovecs in these arrays is specified by .Fa hdr_cnt and .Fa trl_cnt . .Pp If .Pf non- Dv NULL , the system will write the total number of bytes sent on the socket to the variable pointed to by .Fa sbytes . .Pp The .Fa flags argument is a bitmap of these values: -.Bl -item -offset indent +.Bl -item -offset indent .It .Dv SF_NODISKIO . This flag causes any .Fn sendfile call which would block on disk I/O to instead return .Er EBUSY . Busy servers may benefit by transferring requests that would block to a separate I/O worker thread. .It .Dv SF_MNOWAIT . Do not wait for some kernel resource to become available, in particular, .Vt mbuf and .Vt sf_buf . The flag does not make the .Fn sendfile syscall truly non-blocking, since other resources are still allocated in a blocking fashion. .It .Dv SF_SYNC . .Nm sleeps until the network stack no longer references the VM pages of the file, making subsequent modifications to it safe. Please note that this is not a guarantee that the data has actually been sent. .El .Pp When using a socket marked for non-blocking I/O, .Fn sendfile may send fewer bytes than requested. In this case, the number of bytes successfully written is returned in .Fa *sbytes (if specified), and the error .Er EAGAIN is returned. .Sh IMPLEMENTATION NOTES The .Fx implementation of .Fn sendfile is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. .Sh TUNING On some architectures, this system call internally uses a special .Fn sendfile buffer .Pq Vt "struct sf_buf" to handle sending file data to the client. If the sending socket is blocking, and there are not enough .Fn sendfile buffers available, .Fn sendfile will block and report a state of .Dq Li sfbufa . If the sending socket is non-blocking and there are not enough .Fn sendfile buffers available, the call will block and wait for the necessary buffers to become available before finishing the call. .Pp The number of .Vt sf_buf Ns 's allocated should be proportional to the number of nmbclusters used to send data to a client via .Fn sendfile . Tune accordingly to avoid blocking! Busy installations that make extensive use of .Fn sendfile may want to increase these values to be inline with their .Va kern.ipc.nmbclusters (see .Xr tuning 7 for details). .Pp The number of .Fn sendfile buffers available is determined at boot time by either the .Va kern.ipc.nsfbufs .Xr loader.conf 5 variable or the .Dv NSFBUFS kernel configuration tunable. The number of .Fn sendfile buffers scales with .Va kern.maxusers . The .Va kern.ipc.nsfbufsused and .Va kern.ipc.nsfbufspeak read-only .Xr sysctl 8 variables show current and peak .Fn sendfile buffers usage respectively. These values may also be viewed through .Nm netstat Fl m . .Pp If a value of zero is reported for .Va kern.ipc.nsfbufs , your architecture does not need to use .Fn sendfile buffers because their task can be efficiently performed by the generic virtual memory structures. .Sh RETURN VALUES .Rv -std sendfile .Sh ERRORS .Bl -tag -width Er .It Bq Er EAGAIN The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being filled. If specified, the number of bytes successfully sent will be returned in .Fa *sbytes . .It Bq Er EBADF The .Fa fd argument is not a valid file descriptor. .It Bq Er EBADF The .Fa s argument is not a valid socket descriptor. .It Bq Er EBUSY Completing the entire transfer would have required disk I/O, so it was aborted. Partial data may have been sent. (This error can only occur when .Dv SF_NODISKIO is specified.) .It Bq Er EFAULT An invalid address was specified for an argument. .It Bq Er EINTR A signal interrupted .Fn sendfile before it could be completed. If specified, the number of bytes successfully sent will be returned in .Fa *sbytes . .It Bq Er EINVAL The .Fa fd argument is not a regular file. .It Bq Er EINVAL The .Fa s argument is not a SOCK_STREAM type socket. .It Bq Er EINVAL The .Fa offset argument is negative. .It Bq Er EIO An error occurred while reading from .Fa fd . .It Bq Er ENOTCONN The .Fa s argument points to an unconnected socket. .It Bq Er ENOTSOCK The .Fa s argument is not a socket. .It Bq Er EOPNOTSUPP The file system for descriptor .Fa fd does not support .Fn sendfile . .It Bq Er EPIPE The socket peer has closed the connection. .El .Sh SEE ALSO .Xr netstat 1 , .Xr open 2 , .Xr send 2 , .Xr socket 2 , .Xr writev 2 , .Xr tuning 7 .Rs .%A K. Elmeleegy .%A A. Chanda .%A A. L. Cox .%A W. Zwaenepoel .%T A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management .%J The Proceedings of the 2005 USENIX Annual Technical Conference .%P pp 223-236 .%D 2005 .Re .Sh HISTORY The .Fn sendfile system call first appeared in .Fx 3.0 . This manual page first appeared in .Fx 3.1 . .Sh AUTHORS The .Fn sendfile system call and this manual page were written by .An David G. Lawrence Aq dg@dglawrence.com . Index: stable/9/lib/libc/sys =================================================================== --- stable/9/lib/libc/sys (revision 237215) +++ stable/9/lib/libc/sys (revision 237216) Property changes on: stable/9/lib/libc/sys ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libc/sys:r233648 Index: stable/9/lib/libc =================================================================== --- stable/9/lib/libc (revision 237215) +++ stable/9/lib/libc (revision 237216) Property changes on: stable/9/lib/libc ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libc:r233648 Index: stable/9/lib/libelf/elf.3 =================================================================== --- stable/9/lib/libelf/elf.3 (revision 237215) +++ stable/9/lib/libelf/elf.3 (revision 237216) @@ -1,580 +1,580 @@ .\" Copyright (c) 2006,2007 Joseph Koshy. 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 Joseph Koshy ``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 Joseph Koshy 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 October 21, 2007 .Dt ELF 3 .Os .Sh NAME .Nm elf .Nd API for manipulating ELF objects .Sh LIBRARY .Lb libelf .Sh SYNOPSIS .In libelf.h .Sh DESCRIPTION The .Lb libelf provides functions that allow an application to read and manipulate ELF object files, and to read .Xr ar 1 archives. The library allows the manipulation of ELF objects in a byte ordering and word-size independent way, allowing an application to read and create ELF objects for 32 and 64 bit architectures and for little- and big-endian machines. The library is capable of processing ELF objects that use extended section numbering. .Pp This manual page serves to provide an overview of the functionality in the ELF library. Further information may found in the manual pages for individual .Xr ELF 3 functions that comprise the library. .Ss ELF Concepts As described in .Xr elf 5 , ELF files contain several data structures that are laid out in a specific way. ELF files begin with an .Dq Executable Header , and may contain an optional .Dq Program Header Table , and optional data in the form of ELF .Dq sections . A .Dq Section Header Table describes the content of the data in these sections. .Pp ELF objects have an associated .Dq "ELF class" which denotes the natural machine word size for the architecture the object is associated with. Objects for 32 bit architectures have an ELF class of .Dv ELFCLASS32 . Objects for 64 bit architectures have an ELF class of .Dv ELFCLASS64 . .Pp ELF objects also have an associated .Dq endianness which denotes the endianness of the machine architecture associated with the object. This may be .Dv ELFDATA2LSB for little-endian architectures and .Dv ELFDATA2MSB for big-endian architectures. .Pp ELF objects are also associated with an API version number. This version number determines the layout of the individual components of an ELF file and the semantics associated with these. .Ss Data Representation And Translation The .Xr ELF 3 library distinguishes between .Dq native representations of ELF data structures and their .Dq file representations. .Pp An application would work with ELF data in its .Dq native representation, i.e., using the native byteorder and alignment mandated by the processor the application is running on. The .Dq file representation of the same data could use a different byte ordering and follow different constraints on object alignment than these native constraints. .Pp Accordingly, the .Xr ELF 3 library offers translation facilities .Po .Xr elf32_xlatetof 3 , .Xr elf32_xlatetom 3 , .Xr elf64_xlatetof 3 and .Xr elf64_xlatetom 3 .Pc to and from these representations and also provides higher-level APIs that retrieve and store data from the ELF object in a transparent manner. .Ss Library Working Version Conceptually, there are three version numbers associated with an application using the ELF library to manipulate ELF objects: .Bl -bullet -compact -offset indent .It The ELF version that the application was compiled against. This version determines the ABI expected by the application. .It The ELF version of the ELF object being manipulated by the application through the ELF library. .It The ELF version (or set of versions) supported by the ELF library itself. .El .Pp In order to facilitate working with ELF objects of differing versions, the ELF library requires the application to call the .Fn elf_version function before invoking many of its operations, in order to inform the library of the application's desired working version. .Pp In the current implementation, all three versions have to be .Dv EV_CURRENT . .Ss Namespace use The ELF library uses the following prefixes: .Bl -tag -width "ELF_F_*" .It elf_* Used for class-independent functions. .It elf32_* Used for functions working with 32 bit ELF objects. .It elf64_* Used for functions working with 64 bit ELF objects. .It Elf_* Used for class-independent data types. .It ELF_C_* Used for command values used in a few functions. These symbols are defined as members of the .Vt Elf_Cmd enumeration. .It ELF_E_* Used for error numbers. .It ELF_F_* Used for flags. .It ELF_K_* These constants define the kind of file associated with an ELF descriptor. See .Xr elf_kind 3 . The symbols are defined by the .Vt Elf_Kind enumeration. .It ELF_T_* These values are defined by the .Vt Elf_Type enumeration, and denote the types of ELF data structures that can be present in an ELF object. .El .Ss Descriptors Applications communicate with the library using descriptors. These are: .Bl -tag -width ".Vt Elf_Data" .It Vt Elf An .Vt Elf descriptor represents an ELF object or an .Xr ar 1 archive. It is allocated using one of the .Fn elf_begin or .Fn elf_memory functions. An .Vt Elf descriptor can be used to read and write data to an ELF file. An .Vt Elf descriptor can be associated with zero or more .Vt Elf_Scn section descriptors. .Pp Given an ELF descriptor, the application may retrieve the ELF object's class-dependent .Dq "Executable Header" structures using the .Fn elf32_getehdr or .Fn elf64_getehdr functions. A new Ehdr structure may be allocated using the .Fn elf64_newehdr or .Fn elf64_newehdr functions. .Pp The .Dq "Program Header Table" associated with an ELF descriptor may be allocated using the .Fn elf32_getphdr or .Fn elf64_getphdr functions. A new program header table may be allocated or an existing table resized using the .Fn elf32_newphdr or .Fn elf64_newphdr functions. .Pp The .Vt Elf structure is opaque and has no members visible to the application. .\" TODO describe the Elf_Arhdr and Elf_Arsym structures. .It Vt Elf_Data An .Vt Elf_Data data structure describes an individual chunk of a ELF file as represented in memory. It has the following application visible members: .Bl -tag -width ".Vt unsigned int d_version" -compact .It Vt "uint64_t d_align" The in-file alignment of the data buffer within its containing ELF section. This value must be a power of two. .It Vt "uint64_t d_off" The offset with the containing section where this descriptors data would be placed. This field will be computed by the library unless the application requests full control of the ELF object's layout. .It Vt "uint64_t d_size" The number of bytes of data in this descriptor. .It Vt "void *d_buf" A pointer to data in memory. .It Vt "Elf_Type d_type" The ELF type (see below) of the data in this descriptor. .It Vt "unsigned int d_version" The operating version for the data in this buffer. .El .Pp .Vt Elf_Data descriptors are usually associated with .Vt Elf_Scn descriptors. Existing data descriptors associated with an ELF section may be structures are retrieved using the .Fn elf_getdata function. The .Fn elf_newdata function may be used to attach new data descriptors to an ELF section. .It Vt Elf_Scn .Vt Elf_Scn descriptors represent a section in an ELF object. .Pp They are retrieved using the .Fn elf_getscn function. An application may iterate through the existing sections of an ELF object using the .Fn elf_nextscn function. New sections may be allocated using the .Fn elf_newscn function. .Pp The .Vt Elf_Scn descriptor is opaque and contains no application modifiable fields. .El .Ss Supported Elf Types The following ELF datatypes are supported by the library. .Pp .Bl -tag -width ".Dv ELF_T_SYMINFO" -compact .It Dv ELF_T_ADDR Machine addresses. .It Dv ELF_T_BYTE Byte data. The library will not attempt to translate byte data. .It Dv ELF_T_CAP Software and hardware capability records. .It Dv ELF_T_DYN Records used in a section of type .Dv SHT_DYNAMIC . .It Dv ELF_T_EHDR ELF executable header. .It Dv ELF_T_HALF 16-bit unsigned words. .It Dv ELF_T_LWORD 64 bit unsigned words. .It Dv ELF_T_MOVE ELF Move records. .\".It Dv ELF_T_MOVEP .\" As yet unsupported. .It Dv ELF_T_NOTE ELF Note structures. .It Dv ELF_T_OFF File offsets. .It Dv ELF_T_PHDR ELF program header table entries. .It Dv ELF_T_REL ELF relocation entries. .It Dv ELF_T_RELA ELF relocation entries with addends. .It Dv ELF_T_SHDR ELF section header entries. .It Dv ELF_T_SWORD Signed 32-bit words. .It Dv ELF_T_SXWORD Signed 64-bit words. .It Dv ELF_T_SYMINFO ELF symbol information. .It Dv ELF_T_SYM ELF symbol table entries. .It Dv ELF_T_VDEF Symbol version definition records. .It Dv ELF_T_VNEED Symbol version requirement records. .It Dv ELF_T_WORD Unsigned 32-bit words. .It Dv ELF_T_XWORD Unsigned 64-bit words. .El .Pp The symbol .Dv ELF_T_NUM denotes the number of Elf types known to the library. .Pp The following table shows the mapping between ELF section types defined in .Xr elf 5 and the types supported by the library. .Bl -column ".Dv SHT_PREINIT_ARRAY" ".Dv ELF_T_SYMINFO" .It Em Section Type Ta Em "Library Type" Ta Em Description .It Dv SHT_DYNAMIC Ta Dv ELF_T_DYN Ta Xo .Sq .dynamic section entries. .Xc .It Dv SHT_DYNSYM Ta Dv ELF_T_SYM Ta Symbols for dynamic linking. .It Dv SHT_FINI_ARRAY Ta Dv ELF_T_ADDR Ta Termination function pointers. .It Dv SHT_GROUP Ta Dv ELF_T_WORD Ta Section group marker. .It Dv SHT_HASH Ta Dv ELF_T_HASH Ta Symbol hashes. .It Dv SHT_INIT_ARRAY Ta Dv ELF_T_ADDR Ta Initialization function pointers. .It Dv SHT_NOBITS Ta Dv ELF_T_BYTE Ta Xo Empty sections. See .Xr elf 5 . .Xc .It Dv SHT_NOTE Ta Dv ELF_T_NOTE Ta ELF note records. .It Dv SHT_PREINIT_ARRAY Ta Dv ELF_T_ADDR Ta Pre-initialization function pointers. .It Dv SHT_PROGBITS Ta Dv ELF_T_BYTE Ta Machine code. .It Dv SHT_REL Ta Dv ELF_T_REL Ta ELF relocation records. .It Dv SHT_RELA Ta Dv ELF_T_RELA Ta Relocation records with addends. .It Dv SHT_STRTAB Ta Dv ELF_T_BYTE Ta String tables. .It Dv SHT_SYMTAB Ta Dv ELF_T_SYM Ta Symbol tables. .It Dv SHT_SYMTAB_SHNDX Ta Dv ELF_T_WORD Ta Used with extended section numbering. .It Dv SHT_GNU_verdef Ta Dv ELF_T_VDEF Ta Symbol version definitions. .It Dv SHT_GNU_verneed Ta Dv ELF_T_VNEED Ta Symbol versioning requirements. .It Dv SHT_GNU_versym Ta Dv ELF_T_HALF Ta Version symbols. .It Dv SHT_SUNW_move Ta Dv ELF_T_MOVE Ta ELF move records. .It Dv SHT_SUNW_syminfo Ta Dv ELF_T_SYMINFO Ta Additional symbol flags. .El .Ss Functional Grouping This section contains a brief overview of the available functionality in the ELF library. Each function listed here is described further in its own manual page. .Bl -tag -width indent .It "Archive Access" .Bl -tag -compact .It Fn elf_getarsym Retrieve the archive symbol table. .It Fn elf_getarhdr Retrieve the archive header for an object. .It Fn elf_getbase Retrieve the offset of a member inside an archive. .It Fn elf_next Iterate through an .Xr ar 1 archive. .It Fn elf_rand Random access inside an .Xr ar 1 archive. .El .It "Data Structures" .Bl -tag -compact .It Fn elf_getdata Retrieve translated data for an ELF section. .It Fn elf_getscn Retrieve the section descriptor for a named section. .It Fn elf_ndxscn Retrieve the index for a section. .It Fn elf_newdata Add a new .Vt Elf_Data descriptor to an ELF section. .It Fn elf_newscn Add a new section descriptor to an ELF descriptor. .It Fn elf_nextscn Iterate through the sections in an ELF object. .It Fn elf_rawdata Retrieve untranslated data for an ELF sectino. .It Fn elf_rawfile Return a pointer to the untranslated file contents for an ELF object. .It Fn elf32_getehdr , Fn elf64_getehdr Retrieve the Executable Header in an ELF object. .It Fn elf32_getphdr , Fn elf64_getphdr Retrieve the Program Header Table in an ELF object. .It Fn elf32_getshdr , Fn elf64_getshdr Retrieve the ELF section header associated with an .Vt Elf_Scn descriptor. .It Fn elf32_newehdr , Fn elf64_newehdr Allocate an Executable Header in an ELF object. .It Fn elf32_newphdr , Fn elf64_newphdr Allocate or resize the Program Header Table in an ELF object. .El .It "Data Translation" .Bl -tag -compact .It Fn elf32_xlatetof , Fn elf64_xlatetof Translate an ELF data structure from its native representation to its file representation. .It Fn elf32_xlatetom , Fn elf64_xlatetom Translate an ELF data structure from its file representation to a native representation. .El .It "Error Reporting" .Bl -tag -compact .It Fn elf_errno Retrieve the current error. .It Fn elf_errmsg Retrieve a human readable description of the current error. .El .It "Initialization" .Bl -tag -compact .It Fn elf_begin Opens an .Xr ar 1 archive or ELF object given a file descriptor. .It Fn elf_end Close an ELF descriptor and release all its resources. .It Fn elf_memory Opens an .Xr ar 1 archive or ELF object present in a memory area. .It Fn elf_version Sets the operating version. .El .It "IO Control" .Bl -tag -width ".Fn elf_setshstrndx" -compact .It Fn elf_cntl Manage the association between and ELF descriptor and its underlying file. .It Fn elf_flagdata Mark an .Vt Elf_Data descriptor as dirty. .It Fn elf_flagehdr Mark the ELF Executable Header in an ELF descriptor as dirty. .It Fn elf_flagphdr Mark the ELF Program Header Table in an ELF descriptor as dirty. .It Fn elf_flagscn Mark an .Vt Elf_Scn descriptor as dirty. .It Fn elf_flagshdr Mark an ELF Section Header as dirty. .It Fn elf_setshstrndx Set the index of the section name string table for the ELF object. .It Fn elf_update Recompute ELF object layout and optionally write the modified object back to the underlying file. .El .It "Queries" .Bl -tag -width ".Fn elf_getshstrndx" -compact .It Fn elf32_checksum , Fn elf64_checkum Compute checksum of an ELF object. .It Fn elf_getident Retrieve the identification bytes for an ELF object. .It Fn elf_getshnum Retrieve the number of sections in an ELF object. .It Fn elf_getshstrndx Retrieve the section index of the section name string table in an ELF object. .It Fn elf_hash Compute the ELF hash value of a string. .It Fn elf_kind Query the kind of object associated with an ELF descriptor. .It Fn elf32_fsize , Fn elf64_fsize Return the size of the file representation of an ELF type. .El .El .Ss Controlling ELF Object Layout In the usual mode of operation, library will compute section offsets and alignments based on the contents of an ELF descriptor's sections without need for further intervention by the application. .Pp However, if the application wishes to take complete charge of the layout of the ELF file, it may set the .Dv ELF_F_LAYOUT flag on an ELF descriptor using .Xr elf_flagelf 3 , following which the library will use the data offsets and alignments specified by the application when laying out the file. -Application control of file layout is described further in the +Application control of file layout is described further in the .Xr elf_update 3 manual page. .Pp Gaps in between sections will be filled with the fill character set by function .Fn elf_fill . .Ss Error Handling In case an error is encountered, these library functions set an internal error number and signal the presence of the error by returning an special return value. The application can check the current error number by calling .Xr elf_errno 3 . A human readable description of the recorded error is available by calling .Xr elf_errmsg 3 . .Ss Memory Management Rules The library keeps track of all .Vt Elf_Scn and .Vt Elf_Data descriptors associated with an ELF descriptor and recovers them when the descriptor is closed using .Xr elf_end 3 . Thus the application must not call .Xr free 3 on data structures allocated by the ELF library. .Pp Conversely the library will not free data that it has not allocated. As an example, an application may call .Xr elf_newdata 3 to allocate a new .Vt Elf_Data descriptor and can set the .Va d_off member of the descriptor to point to a region of memory allocated using .Xr malloc 3 . It is the applications responsibility to free this area, though the library will reclaim the space used by the .Vt Elf_Data descriptor itself. .Sh SEE ALSO .Xr gelf 3 , .Xr elf 5 .Sh HISTORY The original ELF(3) API was developed for Unix System V. The current implementation of the ELF(3) API appeared in .Fx 7.0 . .Sh AUTHORS The ELF library was written by .An "Joseph Koshy" .Aq jkoshy@FreeBSD.org . Index: stable/9/lib/libelf/elf_getdata.3 =================================================================== --- stable/9/lib/libelf/elf_getdata.3 (revision 237215) +++ stable/9/lib/libelf/elf_getdata.3 (revision 237216) @@ -1,200 +1,200 @@ .\" Copyright (c) 2006,2008,2010-2011 Joseph Koshy. 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 Joseph Koshy ``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 Joseph Koshy 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 January 26, 2011 .Dt ELF_GETDATA 3 .Os .Sh NAME .Nm elf_getdata , .Nm elf_newdata , .Nm elf_rawdata .Nd iterate through or allocate section data .Sh LIBRARY .Lb libelf .Sh SYNOPSIS .In libelf.h .Ft "Elf_Data *" .Fn elf_getdata "Elf_Scn *scn" "Elf_Data *data" .Ft "Elf_Data *" .Fn elf_newdata "Elf_Scn *scn" .Ft "Elf_Data *" .Fn elf_rawdata "Elf_Scn *scn" "Elf_Data *data" .Sh DESCRIPTION These functions are used to access and manipulate data descriptors associated with section descriptors. Data descriptors used by the ELF library are described in .Xr elf 3 . .Pp Function .Fn elf_getdata will return the next data descriptor associated with section descriptor .Ar scn . The returned data descriptor will be setup to contain translated data. Argument .Ar data may be NULL, in which case the function returns the first data descriptor associated with section .Ar scn . If argument .Ar data is not NULL, it must be a pointer to a data descriptor associated with section descriptor .Ar scn , and function .Fn elf_getdata will return a pointer to the next data descriptor for the section, or NULL when the end of the section's descriptor list is reached. .Pp Function .Fn elf_newdata will allocate a new data descriptor and append it to the list of data descriptors associated with section descriptor .Ar scn . The new data descriptor will be initialized as follows: .Bl -tag -width "d_version" -compact -offset indent .It Va d_align Set to 1. .It Va d_buf Initialized to NULL. .It Va d_off Set to (off_t) -1. This field is under application control if the .Dv ELF_F_LAYOUT flag was set on the ELF descriptor. .It Va d_size Set to zero. .It Va d_type Initialized to .Dv ELF_T_BYTE . .It Va d_version Set to the current working version of the library, as set by .Xr elf_version 3 . .El The application must set these values as appropriate before calling .Xr elf_update 3 . Section .Ar scn must be associated with an ELF file opened for writing. If the application has not requested full control of layout by setting the .Dv ELF_F_LAYOUT flag on descriptor .Ar elf , then the data referenced by the returned descriptor will be positioned after the existing content of the section, honoring the file alignment specified in member .Va d_align . On successful completion of a call to .Fn elf_newdata , the ELF library will mark the section .Ar scn as .Dq dirty . .Pp Function .Fn elf_rawdata is used to step through the data descriptors associated with section .Ar scn . In contrast to function .Fn elf_getdata , this function returns untranslated data. If argument .Ar data is NULL, the first data descriptor associated with section .Ar scn is returned. If argument .Ar data is not NULL, is must be a data descriptor associated with section .Ar scn , and function .Fn elf_rawdata will return the next data descriptor in the list, or NULL if no further descriptors are present. Function .Fn elf_rawdata always returns .Vt Elf_Data structures of type .Dv ELF_T_BYTE . .Ss Special handling of zero-sized and SHT_NOBITS sections For sections of type .Dv SHT_NOBITS , and for zero-sized sections, the functions .Fn elf_getdata and .Fn elf_rawdata return a pointer to a valid .Vt Elf_Data structure that has its .Va d_buf member set to NULL and its .Va d_size member set to the size of the section. .Pp If an application wishes to create a section of type .Dv SHT_NOBITS , it should add a data buffer to the section using function .Fn elf_newdata . It should then set the .Va d_buf and .Va d_size members of the returned .Vt Elf_Data structure to NULL and the desired size of the section respectively. .Sh RETURN VALUES These functions return a valid pointer to a data descriptor if successful, or NULL if an error occurs. .Sh ERRORS These functions may fail with the following errors: -.Bl -tag -width "[ELF_E_RESOURCE]" +.Bl -tag -width "[ELF_E_RESOURCE]" .It Bq Er ELF_E_ARGUMENT Arguments .Ar scn was NULL. .It Bq Er ELF_E_ARGUMENT Data descriptor .Ar data was not associated with section descriptor .Ar scn . .It Bq Er ELF_E_RESOURCE An out of memory condition was detected. .El .Sh SEE ALSO .Xr elf 3 , .Xr elf_flagdata 3 , .Xr elf_flagscn 3 , .Xr elf_getscn 3 , .Xr elf_getshdr 3 , .Xr elf_newscn 3 , .Xr elf_rawfile 3 , .Xr elf_update 3 , .Xr elf_version 3 , .Xr gelf 3 Index: stable/9/lib/libelf =================================================================== --- stable/9/lib/libelf (revision 237215) +++ stable/9/lib/libelf (revision 237216) Property changes on: stable/9/lib/libelf ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libelf:r233648 Index: stable/9/lib/libgssapi/gss_release_buffer.3 =================================================================== --- stable/9/lib/libgssapi/gss_release_buffer.3 (revision 237215) +++ stable/9/lib/libgssapi/gss_release_buffer.3 (revision 237216) @@ -1,110 +1,110 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2005 Doug Rabson .\" 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. .\" .\" $FreeBSD$ .\" .\" The following commands are required for all man pages. .Dd January 26, 2010 .Dt GSS_RELEASE_BUFFER 3 PRM .Os .Sh NAME .Nm gss_release_buffer .Nd Discard a buffer .\" This next command is for sections 2 and 3 only. .\" .Sh LIBRARY .Sh SYNOPSIS .In "gssapi/gssapi.h" .Ft OM_uint32 .Fo gss_release_buffer .Fa "OM_uint32 *minor_status" .Fa "gss_buffer_t buffer" .Fc .Sh DESCRIPTION Free storage associated with a buffer. The storage must have been allocated by a GSS-API routine. In addition to freeing the associated storage, the routine will zero the length field in the descriptor to which the buffer parameter refers, and implementations are encouraged to additionally set the pointer field in the descriptor to .Dv NULL . Any buffer object returned by a GSS-API routine may be passed to .Fn gss_release_buffer -(even if there is no storage associated with the buffer). +(even if there is no storage associated with the buffer). .Sh PARAMETERS .Bl -tag .It minor_status Mechanism specific status code. .It buffer The storage associated with the buffer will be deleted. The gss_buffer_desc object will not be freed, but its length field will be zeroed. .El .Sh RETURN VALUES .Bl -tag .It GSS_S_COMPLETE Successful completion .El .Sh STANDARDS .Bl -tag .It RFC 2743 Generic Security Service Application Program Interface Version 2, Update 1 .It RFC 2744 Generic Security Service API Version 2 : C-bindings .El .Sh HISTORY The .Nm function first appeared in .Fx 7.0 . .Sh AUTHORS John Wray, Iris Associates .Sh COPYRIGHT Copyright (C) The Internet Society (2000). All Rights Reserved. .Pp This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. .Pp The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. .Pp This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Index: stable/9/lib/libgssapi/gss_release_oid_set.3 =================================================================== --- stable/9/lib/libgssapi/gss_release_oid_set.3 (revision 237215) +++ stable/9/lib/libgssapi/gss_release_oid_set.3 (revision 237216) @@ -1,108 +1,108 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2005 Doug Rabson .\" 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. .\" .\" $FreeBSD$ .\" .\" The following commands are required for all man pages. .Dd January 26, 2010 .Dt GSS_RELEASE_OID_SET 3 PRM .Os .Sh NAME .Nm gss_release_oid_set .Nd Discard a set of object identifiers .\" This next command is for sections 2 and 3 only. .\" .Sh LIBRARY .Sh SYNOPSIS .In "gssapi/gssapi.h" .Ft OM_uint32 .Fo gss_release_oid_set .Fa "OM_uint32 *minor_status" .Fa "gss_OID_set *set" .Fc .Sh DESCRIPTION Free storage associated with a GSS-API generated gss_OID_set object. The set parameter must refer to an OID-set that was returned from a GSS-API routine. .Fn gss_release_oid_set will free the storage associated with each individual member OID, the OID set's elements array, and the gss_OID_set_desc itself. .Pp Implementations are encouraged to set the gss_OID_set parameter to .Dv GSS_C_NO_OID_SET -on successful completion of this routine. +on successful completion of this routine. .Sh PARAMETERS .Bl -tag .It minor_status Mechanism specific status code. .It set The storage associated with the gss_OID_set will be deleted. .El .Sh RETURN VALUES .Bl -tag .It GSS_S_COMPLETE Successful completion .El .Sh STANDARDS .Bl -tag .It RFC 2743 Generic Security Service Application Program Interface Version 2, Update 1 .It RFC 2744 Generic Security Service API Version 2 : C-bindings .El .Sh HISTORY The .Nm function first appeared in .Fx 7.0 . .Sh AUTHORS John Wray, Iris Associates .Sh COPYRIGHT Copyright (C) The Internet Society (2000). All Rights Reserved. .Pp This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. .Pp The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. .Pp This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Index: stable/9/lib/libgssapi/mech.5 =================================================================== --- stable/9/lib/libgssapi/mech.5 (revision 237215) +++ stable/9/lib/libgssapi/mech.5 (revision 237216) @@ -1,101 +1,101 @@ .\" Copyright (c) 2005 Doug Rabson .\" 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. .\" .\" $FreeBSD$ .Dd January 26, 2010 .Dt MECH 5 .Os .Sh NAME .Nm mech , .Nm qop .Nd "GSS-API Mechanism and QOP files" .Sh SYNOPSIS .Pa "/etc/gss/mech" .Pa "/etc/gss/qop" .Sh DESCRIPTION The .Pa "/etc/gss/mech" file contains a list of installed GSS-API security mechanisms. Each line of the file either contains a comment if the first character is '#' or it contains five fields with the following meanings: .Bl -tag .It Name The name of this GSS-API mechanism. .It Object identifier The OID for this mechanism. .It Library A shared library containing the implementation of this mechanism. .It Kernel module (optional) A kernel module containing the implementation of this mechanism (not yet supported in FreeBSD). .It Library options (optional) Optional parameters interpreted by the mechanism. Library options must be enclosed in brackets ([ ]) to differentiate them from the optional kernel module entry. .El .Pp The first mechanism listed in .Pa "/etc/gss/mech" is the default mechanism. This mechanism will be used by .Xr gss_init_sec_context 3 if the user doesn't specify a specific mechanism. .Pp -The +The .Pa "/etc/gss/qop" file contains a list of Quality of Protection values for use with -GSS-API. +GSS-API. Each line of the file either contains a comment if the first character is '#' or it contains three fields with the following meanings: .Bl -tag .It QOP string The name of this Quality of Protection algorithm. .It QOP value The numeric value used to select this algorithm for use with GSS-API functions such as .Xr gss_get_mic 3 . .It Mechanism name The GSS-API mechanism name that corresponds to this algorithm. .El .Sh EXAMPLES This is a typical entry from .Pa "/etc/gss/mech" : .Bd -literal kerberosv5 1.2.840.113554.1.2.2 /usr/lib/libgssapi_krb5.so.8 - .Ed .Pp This is a typical entry from .Pa "/etc/gss/qop" : .Bd -literal GSS_KRB5_CONF_C_QOP_DES 0x0100 kerberosv5 .Ed .Sh HISTORY The .Nm manual page first appeared in .Fx 7.0 . .Sh AUTHORS This manual page was written by .An Doug Rabson Aq dfr@FreeBSD.org . Index: stable/9/lib/libgssapi =================================================================== --- stable/9/lib/libgssapi (revision 237215) +++ stable/9/lib/libgssapi (revision 237216) Property changes on: stable/9/lib/libgssapi ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /vendor/resolver/dist/lib/libgssapi:r1540-186085 Merged /projects/quota64/lib/libgssapi:r184125-207707 Merged /head/lib/libgssapi:r226702,226785,227006,227755,227983,227987,228531,228630,228761,229067,230127,233648,234715-234716,234772 Merged /projects/largeSMP/lib/libgssapi:r221273-222812,222815-223757 Index: stable/9/lib/libpam/modules/pam_nologin/pam_nologin.8 =================================================================== --- stable/9/lib/libpam/modules/pam_nologin/pam_nologin.8 (revision 237215) +++ stable/9/lib/libpam/modules/pam_nologin/pam_nologin.8 (revision 237216) @@ -1,90 +1,90 @@ .\" Copyright (c) 2001 Mark R V Murray .\" 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. .\" .\" $FreeBSD$ .\" .Dd June 10, 2007 .Dt PAM_NOLOGIN 8 .Os .Sh NAME .Nm pam_nologin .Nd NoLogin PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_nologin .Op Ar options .Sh DESCRIPTION The NoLogin service module for PAM, .Nm provides functionality for only one PAM category: account management. In terms of the .Ar module-type parameter, this is the .Dq Li account feature. .Ss NoLogin Account Management Module The NoLogin account management component, -.Fn pam_sm_acct_mgmt , +.Fn pam_sm_acct_mgmt , verifies whether logins are administratively disabled via .Xr nologin 5 . It returns success if the user's login class has an "ignorenologin" capability specified in .Xr login.conf 5 or the .Xr nologin 5 file does not exist. If neither condition is met, then the contents of .Xr nologin 5 are echoed before failure is returned. The location of .Xr nologin 5 is specified by a "nologin" capability in .Xr login.conf 5 , which defaults to .Pa /var/run/nologin . .Pp The following options may be passed to the module: .Bl -tag -width ".Cm no_warn" .It Cm debug .Xr syslog 3 debugging information at .Dv LOG_DEBUG level. .It Cm no_warn suppress warning messages to the user. These messages include reasons why the user's login attempt was declined. .El .Sh SEE ALSO .Xr syslog 3 , .Xr login.conf 5 , .Xr nologin 5 , .Xr pam.conf 5 , .Xr pam 8 Index: stable/9/lib/libpam =================================================================== --- stable/9/lib/libpam (revision 237215) +++ stable/9/lib/libpam (revision 237216) Property changes on: stable/9/lib/libpam ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libpam:r233648 Index: stable/9/lib/librpcsec_gss/rpc_gss_seccreate.3 =================================================================== --- stable/9/lib/librpcsec_gss/rpc_gss_seccreate.3 (revision 237215) +++ stable/9/lib/librpcsec_gss/rpc_gss_seccreate.3 (revision 237216) @@ -1,112 +1,112 @@ .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/ .\" Authors: Doug Rabson .\" Developed with Red Inc: Alfred Perlstein .\" .\" 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. .\" .\" $FreeBSD$ .Dd January 26, 2010 .Dt RPC_GSS_SECCREATE 3 .Os .Sh NAME .Nm rpc_gss_seccreate .Nd "create a security context using the RPCSEC_GSS protocol" .Sh LIBRARY .Lb librpcsec_gss .Sh SYNOPSIS .In rpc/rpcsec_gss.h .Ft AUTH * .Fo rpc_gss_seccreate .Fa "CLIENT *clnt" .Fa "const char *principal" .Fa "const char *mechanism" .Fa "rpc_gss_service_t service" .Fa "const char *qop" .Fa "rpc_gss_options_req_t *options_req" .Fa "rpc_gss_options_ret_t *options_ret" .Fc .Sh DESCRIPTION This function is used to establish a security context between an application and a remote peer using the RPSEC_GSS protocol. .Sh PARAMETERS .Bl -tag .It clnt An RPC handle which is connected to the remote peer .It principal The name of the service principal on the remote peer. For instance, a principal such as .Qq nfs@server.example.com might be used by an application which needs to contact an NFS server .It mechanism The desired mechanism for this security context. The value of mechanism should be the name of one of the security mechanisms listed in /etc/gss/mech. .It service Type of service requested. .Bl -tag .It rpc_gss_svc_default The default - typically the same as .Dv rpc_gss_svc_none . .It rpc_gss_svc_none RPC headers only are integrity protected by a checksum. .It rpc_gss_svc_integrity RPC headers and data are integrity protected by a checksum. -.It rpc_gss_svc_privacy +.It rpc_gss_svc_privacy RPC headers are integrity protected by a checksum and data is encrypted. .El .It qop Desired quality of protection or NULL for the default. Available values are listed in /etc/gss/qop .It options_req Extra security context options to be passed to the underlying GSS-API mechanism. Pass .Dv NULL to supply default values. .It options_ret Various values returned by the underlying GSS-API mechanism. Pass .Dv NULL if these values are not required. .El .Sh RETURN VALUES If the security context was created successfully, a pointer to an .Vt AUTH structure that represents the context is returned. To use this security context for subsequent RPC calls, set .Va clnt->cl_auth to this value. .Sh SEE ALSO .Xr rpc 3 , .Xr gssapi 3 , .Xr mech 5 , .Xr qop 5 , .Xr rpcset_gss 3 .Sh HISTORY The .Nm function first appeared in .Fx 8.0 . .Sh AUTHORS This manual page was written by .An Doug Rabson Aq dfr@FreeBSD.org . Index: stable/9/lib/librpcsec_gss =================================================================== --- stable/9/lib/librpcsec_gss (revision 237215) +++ stable/9/lib/librpcsec_gss (revision 237216) Property changes on: stable/9/lib/librpcsec_gss ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /projects/largeSMP/lib/librpcsec_gss:r221273-222812,222815-223757 Merged /vendor/resolver/dist/lib/librpcsec_gss:r1540-186085 Merged /projects/quota64/lib/librpcsec_gss:r184125-207707 Merged /head/lib/librpcsec_gss:r226702,226785,227006,227755,227983,227987,228531,228630,228761,229067,230127,233648,234715-234716,234772 Index: stable/9/lib/libtacplus/libtacplus.3 =================================================================== --- stable/9/lib/libtacplus/libtacplus.3 (revision 237215) +++ stable/9/lib/libtacplus/libtacplus.3 (revision 237216) @@ -1,534 +1,533 @@ .\" Copyright (c) 1998, 2001, 2002, Juniper Networks, Inc. .\" 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. .\" .\" $FreeBSD$ .\" .Dd December 11, 2009 .Dt LIBTACPLUS 3 .Os .Sh NAME .Nm libtacplus .Nd TACACS+ client library .Sh SYNOPSIS .In taclib.h .Ft int .Fn tac_add_server "struct tac_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int flags" .Ft void .Fn tac_clear_avs "struct tac_handle *h" .Ft void .Fn tac_close "struct tac_handle *h" .Ft int .Fn tac_config "struct tac_handle *h" "const char *path" .Ft int .Fn tac_create_authen "struct tac_handle *h" "int action" "int type" "int service" .Ft int .Fn tac_create_author "struct tac_handle *h" "int method" "int type" "int service" .Ft int .Fn tac_create_acct "struct tac_handle *h" "int acct" "int action" "int type" "int service" .Ft char * .Fn tac_get_av "struct tac_handle *h" "u_int index" .Ft char * .Fn tac_get_av_value "struct tac_handle *h" "const char *attribute" .Ft void * .Fn tac_get_data "struct tac_handle *h" "size_t *len" .Ft char * .Fn tac_get_msg "struct tac_handle *h" .Ft struct tac_handle * .Fn tac_open "void" .Ft int .Fn tac_send_authen "struct tac_handle *h" .Ft int .Fn tac_send_author "struct tac_handle *h" .Ft int .Fn tac_send_acct "struct tac_handle *h" .Ft int .Fn tac_set_av "struct tac_handle *h" "u_int index" "const char *av_pair" .Ft int .Fn tac_set_data "struct tac_handle *h" "const void *data" "size_t data_len" .Ft int .Fn tac_set_msg "struct tac_handle *h" "const char *msg" .Ft int .Fn tac_set_port "struct tac_handle *h" "const char *port" .Ft int .Fn tac_set_priv "struct tac_handle *h" "int priv" .Ft int .Fn tac_set_rem_addr "struct tac_handle *h" "const char *addr" .Ft int .Fn tac_set_user "struct tac_handle *h" "const char *user" .Ft const char * .Fn tac_strerror "struct tac_handle *h" .Sh DESCRIPTION The .Nm library implements the client side of the TACACS+ network access control protocol. TACACS+ allows clients to perform authentication, authorization, and accounting by means of network requests to remote servers. This library currently supports only the authentication and authorization portion of the protocol. .Sh INITIALIZATION To use the library, an application must first call .Fn tac_open to obtain a .Va struct tac_handle * , which provides context for subsequent operations. Calls to .Fn tac_open always succeed unless insufficient virtual memory is available. If the necessary memory cannot be allocated, .Fn tac_open returns .Dv NULL . .Pp Before issuing any TACACS+ requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to call .Fn tac_config . .Fn tac_config causes the library to read a configuration file whose format is described in .Xr tacplus.conf 5 . The pathname of the configuration file is passed as the .Va file argument to .Fn tac_config . This argument may also be given as .Dv NULL , in which case the standard configuration file .Pa /etc/tacplus.conf is used. .Fn tac_config returns 0 on success, or \-1 if an error occurs. .Pp The library can also be configured programmatically by calls to .Fn tac_add_server . The .Va host parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form. The .Va port parameter specifies the TCP port to contact on the server. If .Va port is given as 0, the library uses port 49, the standard TACACS+ port. The shared secret for the server host is passed to the .Va secret parameter. It may be any null-terminated string of bytes. The timeout for receiving replies from the server is passed to the .Va timeout parameter, in units of seconds. The .Va flags parameter is a bit mask of flags to specify various characteristics of the server. It may contain: .Bl -tag -width Fl .It Dv TAC_SRVR_SINGLE_CONNECT Causes the library to attempt to negotiate single connection mode when communicating with the server. In single connection mode, the original TCP connection is held open for multiple TACACS+ sessions. Older servers do not support this mode, and some of them become confused if the client attempts to negotiate it. .El .Pp .Fn tac_add_server returns 0 on success, or \-1 if an error occurs. .Pp .Fn tac_add_server may be called multiple times, and it may be used together with .Fn tac_config . At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a working, accessible server is found. Once the library finds such a server, it continues to use it as long as it works. .Sh CREATING A TACACS+ AUTHENTICATION REQUEST To begin constructing a new authentication request, call .Fn tac_create_authen . The .Va action , .Va type , and .Va service arguments must be set to appropriate values as defined in the TACACS+ protocol specification. The .In taclib.h header file contains symbolic constants for these values. .Sh CREATING A TACACS+ AUTHORIZATION REQUEST To begin constructing a new authorization request, call .Fn tac_create_author . The .Va method , .Va type , and .Va service arguments must be set to appropriate values as defined in the TACACS+ protocol specification. The .In taclib.h header file contains symbolic constants for these values. .Sh CREATING A TACACS+ ACCOUNTING REQUEST To begin constructing a new accounting request, call .Fn tac_create_acct . The .Va acct , .Va action , .Va type , and .Va service arguments must be set to appropriate values as defined in the TACACS+ protocol specification. The .In taclib.h header file contains symbolic constants for these values. .Sh SETTING OPTIONAL PARAMETERS ON A REQUEST After creating a request, various optional parameters may be attached to it through calls to .Fn tac_set_av , .Fn tac_set_data , .Fn tac_set_port , .Fn tac_set_priv , .Fn tac_set_rem_addr , and .Fn tac_set_user . The library creates its own copies of any strings provided to these functions, so that it is not necessary for the caller to preserve them. By default, each of these parameters is empty except for the privilege level, which defaults to .Ql USER privilege. .Pp .Fn tac_set_av only applies to the context of an authorization request. The format for an attribute value pair is defined in the TACACS+ protocol specification. The index specified can be any value between 0 and 255 inclusive and indicates the position in the list to place the attribute value pair. Calling .Fn tac_set_av with same index twice effectively replaces the value at that position. Use .Fn tac_clear_avs to clear all attribute value pairs that may have been set. .Sh SENDING THE AUTHENTICATION REQUEST AND RECEIVING THE RESPONSE After the TACACS+ authentication request has been constructed, it is sent by means of .Fn tac_send_authen . This function connects to a server if not already connected, sends the request, and waits for a reply. On failure, .Fn tac_send_authen returns \-1. Otherwise, it returns the TACACS+ status code and flags, packed into an integer value. The status can be extracted using the macro .Fn TAC_AUTHEN_STATUS . Possible status codes, defined in .In taclib.h , include: .Pp .Bl -item -compact -offset indent .It .Dv TAC_AUTHEN_STATUS_PASS .It .Dv TAC_AUTHEN_STATUS_FAIL .It .Dv TAC_AUTHEN_STATUS_GETDATA .It .Dv TAC_AUTHEN_STATUS_GETUSER .It .Dv TAC_AUTHEN_STATUS_GETPASS .It .Dv TAC_AUTHEN_STATUS_RESTART .It .Dv TAC_AUTHEN_STATUS_ERROR .It .Dv TAC_AUTHEN_STATUS_FOLLOW .El .Pp The only flag is the no-echo flag, which can be tested using the macro .Fn TAC_AUTHEN_NOECHO . .Sh EXTRACTING INFORMATION FROM THE SERVER'S AUTHENTICATION RESPONSE An authentication response packet from the server may contain a server message, a data string, or both. After a successful call to .Fn tac_send_authen , this information may be retrieved from the response by calling .Fn tac_get_msg and .Fn tac_get_data . These functions return dynamically-allocated copies of the information from the packet. The caller is responsible for freeing the copies when it no longer needs them. The data returned from these functions is guaranteed to be terminated by a null byte. .Pp In the case of .Fn tac_get_data , the .Va len argument points to a location into which the library will store the actual length of the received data, not including the null terminator. This argument may be given as .Dv NULL if the caller is not interested in the length. .Sh SENDING AUTHENTICATION CONTINUE PACKETS If .Fn tac_send_authen returns a value containing one of the status codes .Dv TAC_AUTHEN_STATUS_GETDATA , .Dv TAC_AUTHEN_STATUS_GETUSER , or .Dv TAC_AUTHEN_STATUS_GETPASS , then the client must provide additional information to the server by means of a TACACS+ CONTINUE packet. To do so, the application must first set the packet's user message and/or data fields using .Fn tac_set_msg and .Fn tac_set_data . The client then sends the CONTINUE packet with .Fn tac_send_authen . N.B., .Fn tac_create_authen should .Em not be called to construct a CONTINUE packet; it is used only for the initial authentication request. .Pp When it receives the CONTINUE packet, the server may again request more information by returning .Dv TAC_AUTHEN_STATUS_GETDATA , .Dv TAC_AUTHEN_STATUS_GETUSER , or .Dv TAC_AUTHEN_STATUS_GETPASS . The application should send further CONTINUEs until some other status is received from the server. .Sh SENDING THE AUTHORIZATION REQUEST AND RECEIVING THE RESPONSE After the TACACS+ authorization request has been constructed, it is sent by means of .Fn tac_send_author . This function connects to a server if not already connected, sends the request, and waits for a reply. On failure, .Fn tac_send_author returns \-1. Otherwise, it returns the TACACS+ status code and number of attribute value (AV) pairs received packed into an integer value. The status can be extracted using the macro .Fn TAC_AUTHOR_STATUS . Possible status codes, defined in .In taclib.h , include: .Pp .Bl -item -compact -offset indent .It .Dv TAC_AUTHOR_STATUS_PASS_ADD .It .Dv TAC_AUTHOR_STATUS_PASS_REPL .It .Dv TAC_AUTHOR_STATUS_FAIL .It .Dv TAC_AUTHOR_STATUS_ERROR .El .Pp The number of AV pairs received is obtained using .Fn TAC_AUTHEN_AV_COUNT . .Sh SENDING THE ACCOUNTING REQUEST AND RECEIVING THE RESPONSE After the TACACS+ authorization request has been constructed, it is sent by means of .Fn tac_send_acct . This function connects to a server if not already connected, sends the request, and waits for a reply. On failure, .Fn tac_send_acct returns \-1. -Otherwise, it returns the TACACS+ status code. +Otherwise, it returns the TACACS+ status code Possible status codes, defined in .In taclib.h , include: .Pp .Bl -item -compact -offset indent .It .Dv TAC_ACCT_STATUS_SUCCESS .It .Dv TAC_ACCT_STATUS_ERROR .It .Dv TAC_ACCT_STATUS_FOLLOW .El -.Pp .Sh EXTRACTING INFORMATION FROM THE SERVER'S AUTHORIZATION RESPONSE Like an authentication response packet, an authorization response packet from the server may contain a server message, a data string, or both. Refer to EXTRACTING INFORMATION FROM THE SERVER'S AUTHENTICATION RESPONSE for instruction on extraction of those values. .Pp An authorization response packet from the server may also contain attribute value (AV) pairs. To extract these, use .Fn tac_get_av or .Fn tac_get_av_value . .Fn tac_get_av takes the index of the AV pair as it is positioned in the list. The indexes start at 0 (use .Fn TAC_AUTHEN_AV_COUNT on the return value of .Fn tac_send_author to get the total number of items in this list). Alternatively, .Fn tac_get_av_value can be used. .Fn tac_get_av_value takes the attribute name and returns the corresponding value only, not the AV pair. These functions return dynamically-allocated copies of the information from the packet. The caller is responsible for freeing the copies when it no longer needs them. The data returned from these functions is guaranteed to be terminated by a null byte. .Sh OBTAINING ERROR MESSAGES Those functions which accept a .Va struct tac_handle * argument record an error message if they fail. The error message can be retrieved by calling .Fn tac_strerror . The message text is overwritten on each new error for the given .Va struct tac_handle * . Thus the message must be copied if it is to be preserved through subsequent library calls using the same handle. .Sh CLEANUP To free the resources used by the TACACS+ library, call .Fn tac_close . .Sh RETURN VALUES The following functions return a non-negative value on success. If they detect an error, they return \-1 and record an error message which can be retrieved using .Fn tac_strerror . .Pp .Bl -item -offset indent -compact .It .Fn tac_add_server .It .Fn tac_config .It .Fn tac_create_authen .It .Fn tac_create_author .It .Fn tac_create_acct .It .Fn tac_send_authen .It .Fn tac_send_author .It .Fn tac_send_acct .It .Fn tac_set_av .It .Fn tac_set_data .It .Fn tac_set_msg .It .Fn tac_set_port .It .Fn tac_set_priv .It .Fn tac_set_rem_addr .It .Fn tac_set_user .El .Pp The following functions return a .No non- Ns Dv NULL pointer on success. If they are unable to allocate sufficient virtual memory, they return .Dv NULL and record an error message which can be retrieved using .Fn tac_strerror . .Pp .Bl -item -offset indent -compact .It .Fn tac_get_av .It .Fn tac_get_av_value .It .Fn tac_get_data .It .Fn tac_get_msg .El .Pp The following functions return a .No non- Ns Dv NULL pointer on success. If they are unable to allocate sufficient virtual memory, they return .Dv NULL , without recording an error message. .Pp .Bl -item -offset indent -compact .It .Fn tac_open .El .Sh FILES .Pa /etc/tacplus.conf .Sh SEE ALSO .Xr tacplus.conf 5 .Rs .%A D. Carrel .%A Lol Grant .%T The TACACS+ Protocol, Version 1.78 .%O draft-grant-tacacs-02.txt (Internet Draft) .Re .Sh AUTHORS .An -nosplit This software was written by .An John Polstra and .An Paul Fraley , and donated to the .Fx project by Juniper Networks, Inc. Index: stable/9/lib/libtacplus =================================================================== --- stable/9/lib/libtacplus (revision 237215) +++ stable/9/lib/libtacplus (revision 237216) Property changes on: stable/9/lib/libtacplus ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libtacplus:r233648 Index: stable/9/lib/libulog/utempter_add_record.3 =================================================================== --- stable/9/lib/libulog/utempter_add_record.3 (revision 237215) +++ stable/9/lib/libulog/utempter_add_record.3 (revision 237216) @@ -1,105 +1,105 @@ .\" Copyright (c) 2009 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. .\" .\" $FreeBSD$ .\" .Dd December 6, 2009 .Dt UTEMPTER_ADD_RECORD 3 .Os .Sh NAME .Nm utempter_add_record , .Nm utempter_remove_added_record , .Nm utempter_remove_record , .Nm addToUtmp , .Nm removeFromUtmp , .Nm removeLineFromUtmp .Nd utempter compatibility interface .Sh LIBRARY .Lb libulog .Sh SYNOPSIS .In utempter.h .Ft int .Fn utempter_add_record "int fd" "const char *host" .Ft int .Fn utempter_remove_added_record "void" .Ft int .Fn utempter_remove_record "int fd" .Ft void .Fn addToUtmp "const char *pty" "const char *host" "int fd" .Ft void .Fn removeFromUtmp "void" .Ft void .Fn removeLineFromUtmp "const char *pty" "int fd" .Sh DESCRIPTION The .Fn utempter_add_record and .Fn addToUtmp functions add a login record to the database for the TTY belonging to the pseudo-terminal master file descriptor .Fa fd , using the username corresponding with the real user ID of the calling process and the optional hostname .Fa host . These functions are equivalent to .Xr ulog_login_pseudo 3 . .Pp The .Fn utempter_remove_record and .Fn removeLineFromUtmp functions mark the login session as being closed for the TTY belonging to the pseudo-terminal master file descriptor .Fa fd . These functions are equivalent to .Xr ulog_logout_pseudo 3 . .Pp The .Fn utempter_remove_added_record and .Fn removeFromUtmp functions have the same properties as the previously mentioned functions, except that they use an internally cached value of the file descriptor passed to the login functions. .Pp The .Fa pty -arguments of +arguments of .Fn addToUtmp and .Fn removeLineFromUtmp are unused. .Sh RETURN VALUES In this implementation, the .Fn utempter_add_record , .Fn utempter_remove_added_record and .Fn utempter_remove_record always return a value of 0. .Sh SEE ALSO .Xr pututxline 3 , .Xr ulog_login_pseudo 3 .Sh HISTORY These functions appeared in .Fx 9.0 . Index: stable/9/lib/libulog =================================================================== --- stable/9/lib/libulog (revision 237215) +++ stable/9/lib/libulog (revision 237216) Property changes on: stable/9/lib/libulog ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /head/lib/libulog:r226702,226785,227006,227755,227983,227987,228531,228630,228761,229067,230127,233648,234715-234716,234772 Merged /vendor/resolver/dist/lib/libulog:r1540-186085 Merged /projects/largeSMP/lib/libulog:r221273-222812,222815-223757 Merged /projects/quota64/lib/libulog:r184125-207707 Index: stable/9/lib/libusb/libusb20.3 =================================================================== --- stable/9/lib/libusb/libusb20.3 (revision 237215) +++ stable/9/lib/libusb/libusb20.3 (revision 237216) @@ -1,1031 +1,1031 @@ .\" .\" Copyright (c) 2008 Hans Petter Selasky .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd October 14, 2010 .Dt LIBUSB20 3 .Os .Sh NAME .Nm libusb20 . .Nd "USB access library" . . .Sh LIBRARY . . USB access library (libusb -lusb) . . . .Sh SYNOPSIS .In libusb20.h .Ft int .Fn libusb20_tr_close "struct libusb20_transfer *xfer" .Ft int .Fn libusb20_tr_open "struct libusb20_transfer *xfer" "uint32_t max_buf_size" "uint32_t max_frame_count" "uint8_t ep_no" .Ft struct libusb20_transfer* .Fn libusb20_tr_get_pointer "struct libusb20_device *pdev" "uint16_t tr_index" .Ft uint16_t .Fn libusb20_tr_get_time_complete "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_actual_frames "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_actual_length "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_max_frames "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_max_packet_length "struct libusb20_transfer *xfer" .Ft uint32_t .Fn libusb20_tr_get_max_total_length "struct libusb20_transfer *xfer" .Ft uint8_t .Fn libusb20_tr_get_status "struct libusb20_transfer *xfer" .Ft uint8_t .Fn libusb20_tr_pending "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_callback_wrapper "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_clear_stall_sync "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_drain "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_set_buffer "struct libusb20_transfer *xfer" "void *buffer" "uint16_t fr_index" .Ft void .Fn libusb20_tr_set_callback "struct libusb20_transfer *xfer" "libusb20_tr_callback_t *cb" .Ft void .Fn libusb20_tr_set_flags "struct libusb20_transfer *xfer" "uint8_t flags" .Ft uint32_t .Fn libusb20_tr_get_length "struct libusb20_transfer *xfer" "uint16_t fr_index" .Ft void .Fn libusb20_tr_set_length "struct libusb20_transfer *xfer" "uint32_t length" "uint16_t fr_index" .Ft void .Fn libusb20_tr_set_priv_sc0 "struct libusb20_transfer *xfer" "void *sc0" .Ft void .Fn libusb20_tr_set_priv_sc1 "struct libusb20_transfer *xfer" "void *sc1" .Ft void .Fn libusb20_tr_set_timeout "struct libusb20_transfer *xfer" "uint32_t timeout" .Ft void .Fn libusb20_tr_set_total_frames "struct libusb20_transfer *xfer" "uint32_t nframes" .Ft void .Fn libusb20_tr_setup_bulk "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" .Ft void .Fn libusb20_tr_setup_control "struct libusb20_transfer *xfer" "void *psetup" "void *pbuf" "uint32_t timeout" .Ft void .Fn libusb20_tr_setup_intr "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t timeout" .Ft void .Fn libusb20_tr_setup_isoc "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint61_t fr_index" .Ft uint8_t .Fn libusb20_tr_bulk_intr_sync "struct libusb20_transfer *xfer" "void *pbuf" "uint32_t length" "uint32_t *pactlen" "uint32_t timeout" .Ft void .Fn libusb20_tr_start "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_stop "struct libusb20_transfer *xfer" .Ft void .Fn libusb20_tr_submit "struct libusb20_transfer *xfer" .Ft void * .Fn libusb20_tr_get_priv_sc0 "struct libusb20_transfer *xfer" .Ft void * .Fn libusb20_tr_get_priv_sc1 "struct libusb20_transfer *xfer" .Ft const char * .Fn libusb20_dev_get_backend_name "struct libusb20_device *" .Ft int .Fn libusb20_dev_get_info "struct libusb20_device *pdev" "struct usb_device_info *pinfo" .Ft int .Fn libusb20_dev_get_iface_desc "struct libusb20_device *pdev" "uint8_t iface_index" "char *buf" "uint8_t len" .Ft const char * .Fn libusb20_dev_get_desc "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_close "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_detach_kernel_driver "struct libusb20_device *pdev" "uint8_t iface_index" .Ft int .Fn libusb20_dev_set_config_index "struct libusb20_device *pdev" "uint8_t configIndex" .Ft int .Fn libusb20_dev_get_debug "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_get_fd "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_kernel_driver_active "struct libusb20_device *pdev" "uint8_t iface_index" .Ft int .Fn libusb20_dev_open "struct libusb20_device *pdev" "uint16_t transfer_max" .Ft int .Fn libusb20_dev_process "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_request_sync "struct libusb20_device *pdev" "struct LIBUSB20_CONTROL_SETUP_DECODED *setup" "void *data" "uint16_t *pactlen" "uint32_t timeout" "uint8_t flags" .Ft int .Fn libusb20_dev_req_string_sync "struct libusb20_device *pdev" "uint8_t index" "uint16_t langid" "void *ptr" "uint16_t len" .Ft int .Fn libusb20_dev_req_string_simple_sync "struct libusb20_device *pdev" "uint8_t index" "void *ptr" "uint16_t len" .Ft int .Fn libusb20_dev_reset "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_check_connected "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_set_power_mode "struct libusb20_device *pdev" "uint8_t power_mode" .Ft uint8_t .Fn libusb20_dev_get_power_mode "struct libusb20_device *pdev" .Ft int .Fn libusb20_dev_set_alt_index "struct libusb20_device *pdev" "uint8_t iface_index" "uint8_t alt_index" .Ft struct LIBUSB20_DEVICE_DESC_DECODED * .Fn libusb20_dev_get_device_desc "struct libusb20_device *pdev" .Ft struct libusb20_config * .Fn libusb20_dev_alloc_config "struct libusb20_device *pdev" "uint8_t config_index" .Ft struct libusb20_device * .Fn libusb20_dev_alloc "void" .Ft uint8_t .Fn libusb20_dev_get_address "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_parent_address "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_parent_port "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_bus_number "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_mode "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_speed "struct libusb20_device *pdev" .Ft uint8_t .Fn libusb20_dev_get_config_index "struct libusb20_device *pdev" .Ft void .Fn libusb20_dev_free "struct libusb20_device *pdev" .Ft void .Fn libusb20_dev_set_debug "struct libusb20_device *pdev" "int debug" .Ft void .Fn libusb20_dev_wait_process "struct libusb20_device *pdev" "int timeout" .Ft int .Fn libusb20_be_get_template "struct libusb20_backend *pbe" "int *ptemp" .Ft int .Fn libusb20_be_set_template "struct libusb20_backend *pbe" "int temp" .Ft int .Fn libusb20_be_get_dev_quirk "struct libusb20_backend *pber" "uint16_t index" "struct libusb20_quirk *pq" .Ft int .Fn libusb20_be_get_quirk_name "struct libusb20_backend *pbe" "uint16_t index" "struct libusb20_quirk *pq" .Ft int .Fn libusb20_be_add_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" .Ft int .Fn libusb20_be_remove_dev_quirk "struct libusb20_backend *pbe" "struct libusb20_quirk *pq" .Ft struct libusb20_backend * .Fn libusb20_be_alloc_default "void" .Ft struct libusb20_backend * .Fn libusb20_be_alloc_freebsd "void" .Ft struct libusb20_backend * .Fn libusb20_be_alloc_linux "void" .Ft struct libusb20_device * .Fn libusb20_be_device_foreach "struct libusb20_backend *pbe" "struct libusb20_device *pdev" .Ft void .Fn libusb20_be_dequeue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" .Ft void .Fn libusb20_be_enqueue_device "struct libusb20_backend *pbe" "struct libusb20_device *pdev" .Ft void .Fn libusb20_be_free "struct libusb20_backend *pbe" .Ft uint8_t .Fn libusb20_me_get_1 "const struct libusb20_me_struct *me" "uint16_t off" .Ft uint16_t .Fn libusb20_me_get_2 "const struct libusb20_me_struct *me" "uint16_t off" .Ft uint16_t .Fn libusb20_me_encode "void *pdata" "uint16_t len" "const void *pdecoded" .Ft uint16_t .Fn libusb20_me_decode "const void *pdata" "uint16_t len" "void *pdecoded" .Ft "const uint8_t *" .Fn libusb20_desc_foreach "const struct libusb20_me_struct *me" "const uint8_t *pdesc" .Ft "const char *" .Fn libusb20_strerror "int code" .Ft "const char *" .Fn libusb20_error_name "int code" . . .Sh DESCRIPTION . The .Nm library implements functions to be able to easily access and control USB through the USB file system interface. The .Nm interfaces are specific to the .Fx usb stack and are not available on other operating systems, portable applications should consider using .Xr libusb 3 . . . .Sh USB TRANSFER OPERATIONS . . .Fn libusb20_tr_close will release all kernel resources associated with an USB .Fa xfer . . This function returns zero upon success. . Non-zero return values indicate a LIBUSB20_ERROR value. . .Pp . .Fn libusb20_tr_open will allocate kernel buffer resources according to .Fa max_buf_size and .Fa max_frame_count associated with an USB .Fa pxfer and bind the transfer to the specified .Fa ep_no . .Fa max_buf_size is the minimum buffer size which the data transport layer has to support. If .Fa max_buf_size is zero, the .Nm library will use wMaxPacketSize to compute the buffer size. This can be useful for isochronous transfers. The actual buffer size can be greater than .Fa max_buf_size and is returned by .Fn libusb20_tr_get_max_total_length . . If .Fa max_frame_count is OR'ed with LIBUSB20_MAX_FRAME_PRE_SCALE the remaining part of the argument is converted from milliseconds into the actual number of frames rounded up, when this function returns. This flag is only valid for ISOCHRONOUS transfers and has no effect for other transfer types. The actual number of frames setup is found by calling .Fn libusb20_tr_get_max_frames . . This function returns zero upon success. . Non-zero return values indicate a LIBUSB20_ERROR value. . .Pp . .Fn libusb20_tr_get_pointer will return a pointer to the allocated USB transfer according to the .Fa pdev and .Fa tr_index arguments. . This function returns NULL in case of failure. . .Pp . .Fn libusb20_tr_get_time_complete will return the completion time of an USB transfer in millisecond units. This function is most useful for isochronous USB transfers when doing echo cancelling. . .Pp . .Fn libusb20_tr_get_actual_frames will return the actual number of USB frames after an USB transfer completed. A value of zero means that no data was transferred. . .Pp . .Fn libusb20_tr_get_actual_length will return the sum of the actual length for all transferred USB frames for the given USB transfer. . .Pp . .Fn libusb20_tr_get_max_frames will return the maximum number of USB frames that were allocated when an USB transfer was setup for the given USB transfer. . .Pp . .Fn libusb20_tr_get_max_packet_length will return the maximum packet length in bytes associated with the given USB transfer. . The packet length can be used round up buffer sizes so that short USB packets are avoided for proxy buffers. . . .Pp . .Fn libusb20_tr_get_max_total_length will return the maximum value for the data length sum of all USB frames associated with an USB transfer. In case of control transfers the value returned does not include the length of the SETUP packet, 8 bytes, which is part of frame zero. The returned value of this function is always aligned to the maximum packet size, wMaxPacketSize, of the endpoint which the USB transfer is bound to. . .Pp . .Fn libusb20_tr_get_status will return the status of an USB transfer. . Status values are defined by a set of LIBUSB20_TRANSFER_XXX enums. . .Pp . .Fn libusb20_tr_pending will return non-zero if the given USB transfer is pending for completion. . Else this function returns zero. . .Pp . .Fn libusb20_tr_callback_wrapper This is an internal function used to wrap asynchronous USB callbacks. . .Pp . .Fn libusb20_tr_clear_stall_sync This is an internal function used to synchronously clear the stall on the given USB transfer. . Please see the USB specification for more information on stall clearing. . If the given USB transfer is pending when this function is called, the USB transfer will complete with an error after that this function has been called. . .Pp . .Fn libusb20_tr_drain will stop the given USB transfer and will not return until the USB transfer has been stopped in hardware. . .Pp . .Fn libusb20_tr_set_buffer is used to set the .Fa buffer pointer for the given USB transfer and .Fa fr_index . . Typically the frame index is zero. . . .Pp . .Fn libusb20_tr_set_callback is used to set the USB callback for asynchronous USB transfers. . The callback type is defined by libusb20_tr_callback_t. . .Pp . .Fn libusb20_tr_set_flags is used to set various USB flags for the given USB transfer. .Bl -tag .It LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK Report a short frame as error. .It LIBUSB20_TRANSFER_MULTI_SHORT_NOT_OK Multiple short frames are not allowed. .It LIBUSB20_TRANSFER_FORCE_SHORT All transmitted frames are short terminated. .It LIBUSB20_TRANSFER_DO_CLEAR_STALL Will do a clear-stall before starting the transfer. .El . .Pp . .Fn libusb20_tr_get_length returns the length of the given USB frame by index. After an USB transfer is complete the USB frame length will get updated to the actual transferred length. . .Pp . .Fn libusb20_tr_set_length sets the length of the given USB frame by index. . .Pp . .Fn libusb20_tr_set_priv_sc0 sets private driver pointer number zero. . .Pp . .Fn libusb20_tr_set_priv_sc1 sets private driver pointer number one. . .Pp . .Fn libusb20_tr_set_timeout sets the timeout for the given USB transfer. . A timeout value of zero means no timeout. . The timeout is given in milliseconds. . .Pp . .Fn libusb20_tr_set_total_frames sets the total number of frames that should be executed when the USB transfer is submitted. . The total number of USB frames must be less than the maximum number of USB frames associated with the given USB transfer. . .Pp . .Fn libusb20_tr_setup_bulk is a helper function for setting up a single frame USB BULK transfer. . .Pp . .Fn libusb20_tr_setup_control is a helper function for setting up a single or dual frame USB CONTROL transfer depending on the control transfer length. . .Pp . .Fn libusb20_tr_setup_intr is a helper function for setting up a single frame USB INTERRUPT transfer. . .Pp . .Fn libusb20_tr_setup_isoc is a helper function for setting up a multi frame USB ISOCHRONOUS transfer. . .Pp . .Fn libusb20_tr_bulk_intr_sync will perform a synchronous BULK or INTERRUPT transfer having length given by the .Fa length argument and buffer pointer given by the .Fa pbuf argument on the USB transfer given by the .Fa xfer argument. . If the .Fa pactlen argument is non-NULL the actual transfer length will be stored at the given pointer destination. . If the .Fa timeout argument is non-zero the transfer will timeout after the given value in milliseconds. . This function does not change the transfer flags, like short packet not ok. . This function returns zero on success else a LIBUSB20_TRANSFER_XXX value is returned. . .Pp . .Fn libusb20_tr_start will get the USB transfer started, if not already started. . This function will not get the transfer queued in hardware. . This function is non-blocking. . .Pp . .Fn libusb20_tr_stop will get the USB transfer stopped, if not already stopped. . This function is non-blocking, which means that the actual stop can happen after the return of this function. . .Pp . .Fn libusb20_tr_submit will get the USB transfer queued in hardware. . . .Pp . .Fn libusb20_tr_get_priv_sc0 returns private driver pointer number zero associated with an USB transfer. . . .Pp . .Fn libusb20_tr_get_priv_sc1 returns private driver pointer number one associated with an USB transfer. . . .Sh USB DEVICE OPERATIONS . . .Fn libusb20_dev_get_backend_name returns a zero terminated string describing the backend used. . .Pp . .Fn libusb20_dev_get_info -retrieves the BSD specific usb_device_info structure into the memory location given by +retrieves the BSD specific usb_device_info structure into the memory location given by .Fa pinfo . The USB device given by .Fa pdev must be opened before this function will succeed. This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_iface_desc retrieves the kernel interface description for the given USB .Fa iface_index . The format of the USB interface description is: "drivername: " The description string is always zero terminated. A zero length string is written in case no driver is attached to the given interface. The USB device given by .Fa pdev must be opened before this function will succeed. This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_desc returns a zero terminated string describing the given USB device. The format of the string is: "drivername: " . .Pp . .Fn libusb20_dev_close will close the given USB device. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_detach_kernel_driver will try to detach the kernel driver for the USB interface given by .Fa iface_index . . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_set_config_index will try to set the configuration index on an USB device. . The first configuration index is zero. . The un-configure index is 255. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_debug returns the debug level of an USB device. . .Pp . .Fn libusb20_dev_get_fd returns the file descriptor of the given USB device. . A negative value is returned when no file descriptor is present. . The file descriptor can be used for polling purposes. . .Pp . .Fn libusb20_dev_kernel_driver_active returns zero if a kernel driver is active on the given USB interface. . Else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_open opens an USB device so that setting up USB transfers becomes possible. . The number of USB transfers can be zero which means only control transfers are allowed. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . A return value of LIBUSB20_ERROR_BUSY means that the device is already opened. . .Pp . .Fn libusb20_dev_process is called to sync kernel USB transfers with userland USB transfers. . This function returns zero on success else a LIBUSB20_ERROR value is returned typically indicating that the given USB device has been detached. . .Pp . .Fn libusb20_dev_request_sync will perform a synchronous control request on the given USB device. . Before this call will succeed the USB device must be opened. . .Fa setup is a pointer to a decoded and host endian SETUP packet. .Fa data is a pointer to a data transfer buffer associated with the control transaction. This argument can be NULL. .Fa pactlen is a pointer to a variable that will hold the actual transfer length after the control transaction is complete. .Fa timeout is the transaction timeout given in milliseconds. A timeout of zero means no timeout. .Fa flags is used to specify transaction flags, for example LIBUSB20_TRANSFER_SINGLE_SHORT_NOT_OK. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_req_string_sync will synchronously request an USB string by language ID and string index into the given buffer limited by a maximum length. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_req_string_simple_sync will synchronously request an USB string using the default language ID and convert the string into ASCII before storing the string into the given buffer limited by a maximum length which includes the terminating zero. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . . .Pp . .Fn libusb20_dev_reset will try to BUS reset the given USB device and restore the last set USB configuration. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . . .Pp . .Fn libusb20_dev_check_connected will check if an opened USB device is still connected. . This function returns zero if the device is still connected else a LIBUSB20_ERROR value is returned. . . .Pp . .Fn libusb20_dev_set_power_mode sets the power mode of the USB device. . Valid power modes: .Bl -tag .It LIBUSB20_POWER_OFF .It LIBUSB20_POWER_ON .It LIBUSB20_POWER_SAVE .It LIBUSB20_POWER_SUSPEND .It LIBUSB20_POWER_RESUME .El . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_power_mode returns the currently selected power mode for the given USB device. . .Pp . .Fn libusb20_dev_set_alt_index will try to set the given alternate index for the given USB interface index. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_dev_get_device_desc returns a pointer to the decoded and host endian version of the device descriptor. . The USB device need not be opened when calling this function. . .Pp . .Fn libusb20_dev_alloc_config will read out and decode the USB config descriptor for the given USB device and config index. This function returns a pointer to the decoded configuration which must eventually be passed to free(). NULL is returned in case of failure. . .Pp . .Fn libusb20_dev_alloc is an internal function to allocate a new USB device. . .Pp . .Fn libusb20_dev_get_address returns the internal and not necessarily the real hardware address of the given USB device. Valid addresses start at one. . .Pp . .Fn libusb20_dev_get_parent_address returns the internal and not necessarily the real hardware address of the given parent USB HUB device. This value is zero for the root HUB which usually has a device address equal to one. Valid addresses start at one. . .Pp . .Fn libusb20_dev_get_parent_port returns the port number on the parent USB HUB device. This value is zero for the root HUB which usually has a device address equal to one. Valid port numbers start at one. . .Pp . .Fn libusb20_dev_get_bus_number returns the internal bus number which the given USB device belongs to. Valid bus numbers start at zero. . .Pp . .Fn libusb20_dev_get_mode returns the current operation mode of the USB entity. . Valid return values are: .Bl -tag .It LIBUSB20_MODE_HOST .It LIBUSB20_MODE_DEVICE .El . .Pp . .Fn libusb20_dev_get_speed returns the current speed of the given USB device. . .Bl -tag .It LIBUSB20_SPEED_UNKNOWN .It LIBUSB20_SPEED_LOW .It LIBUSB20_SPEED_FULL .It LIBUSB20_SPEED_HIGH .It LIBUSB20_SPEED_VARIABLE .It LIBUSB20_SPEED_SUPER .El . .Pp . .Fn libusb20_dev_get_config_index returns the currently selected config index for the given USB device. . .Pp . .Fn libusb20_dev_free will free the given USB device and all associated USB transfers. . .Pp . .Fn libusb20_dev_set_debug will set the debug level for the given USB device. . .Pp . .Fn libusb20_dev_wait_process will wait until a pending USB transfer has completed on the given USB device. . A timeout value can be specified which is passed on to the .Xr poll 2 function. . .Sh USB BACKEND OPERATIONS . .Fn libusb20_be_get_template will return the currently selected global USB device side mode template into the integer pointer .Fa ptemp . This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_be_set_template will set the global USB device side mode template to .Fa temp . The new template is not activated until after the next USB enumeration. The template number decides how the USB device will present itself to the USB Host, like Mass Storage Device, USB Ethernet Device. Also see the .Xr usb2_template 4 module. This function returns zero on success else a LIBUSB20_ERROR value is returned. . .Pp . .Fn libusb20_be_get_dev_quirk will return the device quirk according to .Fa index into the libusb20_quirk structure pointed to by .Fa pq . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is returned. . .Pp . .Fn libusb20_be_get_quirk_name will return the quirk name according to .Fa index into the libusb20_quirk structure pointed to by .Fa pq . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is returned. . .Pp . .Fn libusb20_be_add_dev_quirk will add the libusb20_quirk structure pointed to by the .Fa pq argument into the device quirk list. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk cannot be added LIBUSB20_ERROR_NO_MEM is returned. . .Pp . .Fn libusb20_be_remove_dev_quirk will remove the quirk matching the libusb20_quirk structure pointed to by the .Fa pq argument from the device quirk list. . This function returns zero on success else a LIBUSB20_ERROR value is returned. . If the given quirk does not exist LIBUSB20_ERROR_NOT_FOUND is returned. . .Pp . .Fn libusb20_be_alloc_default .Fn libusb20_be_alloc_freebsd .Fn libusb20_be_alloc_linux These functions are used to allocate a specific USB backend or the operating system default USB backend. Allocating a backend is a way to scan for currently present USB devices. . .Pp . .Fn libusb20_be_device_foreach is used to iterate USB devices present in a USB backend. . The starting value of .Fa pdev is NULL. . This function returns the next USB device in the list. . If NULL is returned the end of the USB device list has been reached. . .Pp . .Fn libusb20_be_dequeue_device will dequeue the given USB device pointer from the backend USB device list. . Dequeued USB devices will not be freed when the backend is freed. . .Pp . .Fn libusb20_be_enqueue_device will enqueue the given USB device pointer in the backend USB device list. . Enqueued USB devices will get freed when the backend is freed. . .Pp . .Fn libusb20_be_free will free the given backend and all USB devices in its device list. . . .Sh USB DESCRIPTOR PARSING . .Fn libusb20_me_get_1 pie offset This function will return a byte at the given byte offset of a message entity. . This function is safe against invalid offsets. . .Pp . .Fn libusb20_me_get_2 pie offset This function will return a little endian 16-bit value at the given byte offset of a message entity. . This function is safe against invalid offsets. . .Pp . .Fn libusb20_me_encode pbuf len pdecoded This function will encode a so-called *DECODED structure into binary format. . The total encoded length that will fit in the given buffer is returned. . If the buffer pointer is NULL no data will be written to the buffer location. . .Pp . .Fn libusb20_me_decode pbuf len pdecoded This function will decode a binary structure into a so-called *DECODED structure. . The total decoded length is returned. . The buffer pointer cannot be NULL. . . .Sh USB DEBUGGING .Ft const char * .Fn libusb20_strerror "int code" Get the ASCII representation of the error given by the .Fa code argument. This function does not return NULL. .Pp .Ft const char * .Fn libusb20_error_name "int code" Get the ASCII representation of the error enum given by the .Fa code argument. This function does not return NULL. . .Sh FILES . . /dev/usb .Sh SEE ALSO .Xr usb 4 , .Xr libusb 3 , .Xr usbconfig 8 , .Xr usbdump 8 . . .Sh HISTORY . . Some parts of the .Nm API derives from the libusb project at sourceforge. Index: stable/9/lib/libusb =================================================================== --- stable/9/lib/libusb (revision 237215) +++ stable/9/lib/libusb (revision 237216) Property changes on: stable/9/lib/libusb ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libusb:r233648 Index: stable/9/lib/libutil/login_cap.3 =================================================================== --- stable/9/lib/libutil/login_cap.3 (revision 237215) +++ stable/9/lib/libutil/login_cap.3 (revision 237216) @@ -1,579 +1,579 @@ .\" Copyright (c) 1995 David Nugent .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, is permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice immediately at the beginning of the file, without modification, .\" 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. This work was done expressly for inclusion into FreeBSD. Other use .\" is permitted provided this notation is included. .\" 4. Absolutely no warranty of function or purpose is made by the author .\" David Nugent. .\" 5. Modifications may be freely made to this file providing the above .\" conditions are met. .\" .\" $FreeBSD$ .\" .Dd June 14, 2007 .Dt LOGIN_CAP 3 .Os .Sh NAME .Nm login_close , .Nm login_getcapbool , .Nm login_getcaplist , .Nm login_getcapnum , .Nm login_getcapstr , .Nm login_getcapsize , .Nm login_getcaptime , .Nm login_getclass , .Nm login_getclassbyname , .Nm login_getpwclass , .Nm login_getstyle , .Nm login_getuserclass , .Nm login_setcryptfmt .Nd "functions for accessing the login class capabilities database" .Sh LIBRARY .Lb libutil .Sh SYNOPSIS .In sys/types.h .In login_cap.h .Ft void .Fn login_close "login_cap_t *lc" .Ft login_cap_t * .Fn login_getclassbyname "const char *nam" "const struct passwd *pwd" .Ft login_cap_t * .Fn login_getclass "const char *nam" .Ft login_cap_t * .Fn login_getpwclass "const struct passwd *pwd" .Ft login_cap_t * .Fn login_getuserclass "const struct passwd *pwd" .Ft "const char *" .Fn login_getcapstr "login_cap_t *lc" "const char *cap" "const char *def" "const char *error" .Ft "const char **" .Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars" .Ft "const char *" .Fn login_getpath "login_cap_t *lc" "const char *cap" "const char *error" .Ft rlim_t .Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" .Ft rlim_t .Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" .Ft rlim_t .Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error" .Ft int .Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def" .Ft "const char *" .Fn login_getstyle "login_cap_t *lc" "const char *style" "const char *auth" .Ft const char * .Fn login_setcryptfmt "login_cap_t *lc" "const char *def" "const char *error" .Sh DESCRIPTION These functions represent a programming interface to the login classes database provided in .Xr login.conf 5 . This database contains capabilities, attributes and default environment and accounting settings for users and programs running as specific users, as determined by the login class field within entries in .Pa /etc/master.passwd . .Pp Entries in .Xr login.conf 5 consist of colon .Ql \&: separated fields, the first field in each record being one or more identifiers for the record (which must be unique for the entire database), each separated by a .Ql | , and may optionally include a description as the last .Sq name . Remaining fields in the record consist of keyword/data pairs. Long lines may be continued with a backslash within empty entries, with the second and subsequent lines optionally indented for readability. This is similar to the format used in .Xr termcap 5 , except that keywords are not limited to two significant characters, and are usually longer for improved readability. As with termcap entries, multiple records can be linked together (one record including another) using a field containing .Ql tc= Ns Va . The result is that the entire record referenced by .Va replaces the .Va tc= field at the point at which it occurs. See .Xr getcap 3 for further details on the format and use of a capabilities database. .Pp The .Nm login_cap interface provides a convenient means of retrieving login class records with all .Va tc= references expanded. A program will typically call one of .Fn login_getclass , .Fn login_getpwclass , .Fn login_getuserclass or .Fn login_getclassbyname according to its requirements. Each of these functions returns a login capabilities structure, .Vt login_cap_t , which may subsequently be used to interrogate the database for specific values using the rest of the API. Once the .Vt login_cap_t is of no further use, the .Fn login_close function should be called to free all resources used. .Pp The structure of .Vt login_cap_t is defined in .In login_cap.h , as: .Bd -literal -offset indent typedef struct { char *lc_class; char *lc_cap; char *lc_style; } login_cap_t; .Ed .Pp The .Fa lc_class member contains a pointer to the name of the login class retrieved. This may not necessarily be the same as the one requested, either directly via .Fn login_getclassbyname , or indirectly via a user's login record using .Fn login_getpwclass , by class name using .Fn login_getclass . If the referenced user has no login class specified in .Pa /etc/master.passwd , the class name is .Dv NULL or an empty string. If the class specified does not exist in the database, each of these functions will search for a record with an id of .Ql default , with that name returned in the .Fa lc_class field. In addition, if the referenced user has a UID of 0 (normally, .Ql root , although the user name is not considered) then .Fn login_getpwclass will search for a record with an id of .Ql root before it searches for the record with the id of .Ql default . .Pp The .Fa lc_cap field is used internally by the library to contain the expanded login capabilities record. Programs with unusual requirements may wish to use this with the lower-level .Fn getcap style functions to access the record directly. .Pp The .Fa lc_style field is set by the .Fn login_getstyle function to the authorisation style, according to the requirements of the program handling a login itself. .Pp The .Fn login_getclassbyname function is the basic means to get a .Vt login_cap_t object. It accepts two arguments: the first one, .Fa name , is the record identifier of the record to be retrieved; the second, .Fa pwd , is an optional pointer to a .Vt passwd structure. First of all, its arguments are used by the function to choose between system and user modes of operation. When in system mode, only the system login class database is used. When in user mode, the supplemental login class database in the user's home directory is allowed to override settings from the system database in a limited way as noted below. To minimize security implications, user mode is entered by .Fn login_getclassbyname if and only if .Fa name is .Dv LOGIN_MECLASS .Pq Ql me and .Fa pwd is not .Dv NULL . Otherwise system mode is chosen. .Pp In system mode, any record in the system database .Pa /etc/login.conf can be accessed, and a fallback to the default record is provided as follows. If .Fa name is .Dv NULL , an empty string, or a class that does not exist in the login class database, then the .Dv LOGIN_DEFCLASS record .Pq Ql default is returned instead. .Pp In user mode, only the .Dv LOGIN_MECLASS record .Pq Ql me is accessed and no fallback to the .Ql default record is provided. The directory specified by .Fa pwd->pw_dir is searched for a login database file called .Pa .login_conf , and only the .Ql me capability record contained within it may override the system record with the same name while other records are ignored. Using this scheme, an application can explicitly allow users to override a selected subset of login settings. To do so, the application should obtain two .Vt login_cap_t objects, one in user mode and the other in system mode, and then query the user object before the system object for login parameters that are allowed to be overridden by the user. For example, the user's .Pa .login_conf can provide a convenient way for a user to set up their preferred login environment before the shell is invoked on login if supported by .Xr login 1 . .Pp Note that access to the .Pa /etc/login.conf and .Pa .login_conf files will only be performed subject to the security checks documented in .Xr _secure_path 3 for the uids 0 and .Fa pwd->pw_uid respectively. .Pp If the specified record is .Dv NULL , empty or does not exist, and the system has no .Ql default record available to fall back to, there is a memory allocation error or for some reason .Xr cgetent 3 is unable to access the login capabilities database, this function returns .Dv NULL . .Pp The functions .Fn login_getclass , .Fn login_getpwclass and .Fn login_getuserclass retrieve the applicable login class record for the user's passwd entry or class name by calling .Fn login_getclassbyname . On failure, .Dv NULL is returned. The difference between these functions is that .Fn login_getuserclass includes the user's overriding .Pa .login_conf that exists in the user's home directory, and .Fn login_getpwclass and .Fn login_getclass restrict lookup only to the system login class database in .Pa /etc/login.conf . As explained earlier, .Fn login_getpwclass differs from .Fn login_getclass in that it allows the default class for a super-user as .Ql root if none has been specified in the password database. Otherwise, if the passwd pointer is .Dv NULL , or the user record has no login class, then the system .Ql default entry is retrieved. Essentially, .Fn login_getclass name is equivalent to .Fn login_getclassbyname name NULL and .Fn login_getuserclass pwd to .Fn login_getclassbyname LOGIN_MECLASS pwd . .Pp Once a program no longer wishes to use a .Vt login_cap_t object, .Fn login_close may be called to free all resources used by the login class. The .Fn login_close function may be passed a .Dv NULL pointer with no harmful side-effects. .Pp The remaining functions may be used to retrieve individual capability records. Each function takes a .Vt login_cap_t object as its first parameter, a capability tag as the second, and remaining parameters being default and error values that are returned if the capability is not found. The type of the additional parameters passed and returned depend on the .Em type of capability each deals with, be it a simple string, a list, a time value, a file or memory size value, a path (consisting of a colon-separated list of directories) or a boolean flag. The manpage for .Xr login.conf 5 deals in specific tags and their type. .Pp Note that with all functions in this group, you should not call .Xr free 3 on any pointers returned. Memory allocated during retrieval or processing of capability tags is automatically reused by subsequent calls to functions in this group, or deallocated on calling .Fn login_close . .Bl -tag -width "login_getcaplist()" .It Fn login_getcapstr This function returns a simple string capability. If the string is not found, then the value in .Fa def is returned as the default value, or if an error occurs, the value in the .Fa error parameter is returned. .It Fn login_getcaplist This function returns the value corresponding to the named capability tag as a list of values in a .Dv NULL terminated array. Within the login class database, some tags are of type .Vt list , which consist of one or more comma- or space separated values. Usually, this function is not called directly from an application, but is used indirectly via .Fn login_getstyle . .It Fn login_getpath This function returns a list of directories separated by colons .Ql \&: . Capability tags for which this function is called consist of a list of directories separated by spaces. .It Fn login_getcaptime This function returns a .Vt time value associated with a particular capability tag with the value expressed in seconds (the default), minutes, hours, days, weeks or (365 day) years or any combination of these. A suffix determines the units used: .Ql S for seconds, .Ql M for minutes, .Ql H for hours, .Ql D for days, .Ql W for weeks and .Ql Y for 365 day years. Case of the units suffix is ignored. .Pp Time values are normally used for setting resource, accounting and session limits. If supported by the operating system and compiler (which is true of .Fx ) , the value returned is a .Vt quad .Pq Vt long long , of type .Vt rlim_t . A value .Ql inf or .Ql infinity may be used to express an infinite value, in which case .Dv RLIM_INFINITY is returned. .It Fn login_getcapnum This function returns a numeric value for a tag, expressed either as .Ql tag= or the standard .Fn cgetnum format .Ql tag# . The first format should be used in preference to the second, the second format is provided for compatibility and consistency with the .Xr getcap 3 database format where numeric types use the .Ql \&# as the delimiter for numeric values. If in the first format, then the value given may be .Ql inf or .Ql infinity which results in a return value of .Dv RLIM_INFINITY . If the given capability tag cannot be found, the .Fa def parameter is returned, and if an error occurs, the .Fa error parameter is returned. .It Fn login_getcapsize .Fn login_getcapsize returns a value representing a size (typically, file or memory) which may be expressed as bytes (the default), 512 byte blocks, kilobytes, megabytes, gigabytes, and on systems that support the .Vt long long type, terabytes. The suffix used determines the units, and multiple values and units may be used in combination (e.g.\& 1m500k = 1.5 megabytes). A value with no suffix is interpreted as bytes, .Ql B as 512-byte blocks, .Ql K as kilobytes, .Ql M as megabytes, .Ql G as gigabytes and .Ql T as terabytes. Case is ignored. The error value is returned if there is a login capabilities database error, if an invalid suffix is used, or if a numeric value cannot be interpreted. .It Fn login_getcapbool This function returns a boolean value tied to a particular flag. It returns 0 if the given capability tag is not present or is negated by the presence of a .Ql tag@ (see .Xr getcap 3 for more information on boolean flags), and returns 1 if the tag is found. .It Fn login_getstyle This function is used by the login authorisation system to determine the style of login available in a particular case. The function accepts three parameters, the .Fa lc entry itself and two optional parameters, and authorisation type .Fa auth and .Fa style , and applies these to determine the authorisation style that best suites these rules. .Bl -bullet .It -If +If .Fa auth is neither .Dv NULL nor an empty string, look for a tag of type .Ql auth- Ns Fa in the capability record. If not present, then look for the default tag .Va auth= . .It If no valid authorisation list was found from the previous step, then default to .Ql passwd as the authorisation list. .It -If +If .Fa style is not .Dv NULL or empty, look for it in the list of authorisation methods found from the previous step. If .Fa style is .Dv NULL or an empty string, then default to .Ql passwd authorisation. .It If .Fa style is found in the chosen list of authorisation methods, then return that, otherwise return .Dv NULL . .El .Pp This scheme allows the administrator to determine the types of authorisation methods accepted by the system, depending on the means by which the access occurs. For example, the administrator may require skey or kerberos as the authentication method used for access to the system via the network, and standard methods via direct dialup or console logins, significantly reducing the risk of password discovery by "snooping" network packets. .It Fn login_setcryptfmt The .Fn login_setcryptfmt function is used to set the .Xr crypt 3 format using the .Va passwd_format configuration entry. If no entry is found, .Fa def is taken to be used as the fallback. If calling .Xr crypt_set_format 3 on the specifier fails, .Fa error is returned to indicate this. .El .Sh SEE ALSO .Xr login 1 , .Xr crypt 3 , .Xr getcap 3 , .Xr login_class 3 , .Xr login.conf 5 , .Xr termcap 5 Index: stable/9/lib/libutil/quotafile.3 =================================================================== --- stable/9/lib/libutil/quotafile.3 (revision 237215) +++ stable/9/lib/libutil/quotafile.3 (revision 237216) @@ -1,290 +1,290 @@ .\"- .\" Copyright (c) 2009 Dag-Erling Coïdan Smørgrav and .\" Marshall Kirk McKusick. 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. .\" .\" $FreeBSD$ .\" .Dd December 28, 2009 .Dt QUOTAFILE 3 .Os .Sh NAME .Nm quota_open .Nm quota_close .Nm quota_on .Nm quota_off .Nm quota_read .Nm quota_write_limits .Nm quota_write_usage .Nm quota_fsname .Nm quota_qfname .Nm quota_maxid .Nm quota_check_path .Nm quota_convert .Nd "Manipulate quotas" .Sh LIBRARY .Lb libutil .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In ufs/ufs/quota.h .In fcntl.h .In fstab.h .In libutil.h .Ft "struct quotafile *" .Fn quota_open "struct fstab *fs" "int quotatype" "int openflags" .Ft int .Fn quota_close "struct quotafile *qf" .Ft int .Fn quota_on "const struct quotafile *qf" .Ft int .Fn quota_off "const struct quotafile *qf" .Ft int .Fn quota_read "struct quotafile *qf" "struct dqblk *dqb" "int id" .Ft int .Fn quota_write_limits "struct quotafile *qf" "struct dqblk *dqb" "int id" .Ft int .Fn quota_write_usage "struct quotafile *qf" "struct dqblk *dqb" "int id" .Ft "const char *" .Fn quota_fsname "const struct quotafile *qf" .Ft "const char *" .Fn quota_qfname "const struct quotafile *qf" .Ft int .Fn quota_maxid "const struct quotafile *qf" .Ft int .Fn quota_check_path "const struct quotafile *qf" "const char *path" .Ft int .Fn quota_convert "struct quotafile *qf" "int wordsize" .Sh DESCRIPTION These functions are designed to simplify access to filesystem quotas. If quotas are active on a filesystem, these functions will access them directly from the kernel using the .Fn quotactl system call. If quotas are not active, these functions will access them by reading and writing the quota files directly. .Pp The .Fn quota_open function takes a pointer to an .Vt fstab entry corresponding to the filesystem on which quotas are to be accessed. The .Va quotatype field indicates the type of quotas being sought, either .Dv USRQUOTA or .Dv GRPQUOTA . The .Va openflags are those used by the .Fn open system call, usually either .Dv O_RDONLY if the quotas are just to be read, or .Dv O_RDWR if the quotas are to be updated. The .Dv O_CREAT flag should be specified if a new quota file of the requested type should be created if it does not already exist. .Pp The .Fn quota_close function closes any open file descriptors and frees any storage associated with the filesystem and quota type referenced by .Va qf . .Pp The .Fn quota_on function enables quotas for the filesystem associated with its .Va qf argument which may have been opened with .Dv O_RDONLY or .Dv O_RDWR . The .Fn quota_on function returns 0 if successful; otherwise the value\~-1 is returned and the global variable .Va errno is set to indicate the error, see .Xr quotactl 2 for the possible errors. .Pp The .Fn quota_off function disables quotas for the filesystem associated with its .Va qf argument which may have been opened with .Dv O_RDONLY or .Dv O_RDWR . The .Fn quota_off function returns 0 if successful; otherwise the value\~-1 is returned and the global variable .Va errno is set to indicate the error, see .Xr quotactl 2 for the possible errors. .Pp The .Fn quota_read function reads the quota from the filesystem and quota type referenced by .Va qf for the user (or group) specified by .Va id into the .Vt dqblk quota structure pointed to by .Va dqb . .Pp The .Fn quota_write_limits function updates the limit fields (but not the usage fields) for the filesystem and quota type referenced by .Va qf for the user (or group) specified by .Va id from the .Vt dqblk quota structure pointed to by .Va dqb . .Pp The .Fn quota_write_usage function updates the usage fields (but not the limit fields) for the filesystem and quota type referenced by .Va qf for the user (or group) specified by .Va id from the .Vt dqblk quota structure pointed to by .Va dqb . .Pp The .Fn quota_fsname function returns a pointer to a buffer containing the path to the root of the file system that corresponds to its .Va qf argument, as listed in .Pa /etc/fstab . Note that this may be a symbolic link to the actual directory. .Pp The .Fn quota_qfname function returns a pointer to a buffer containing the name of the quota file that corresponds to its .Va qf argument. Note that this may be a symbolic link to the actual file. .Pp The .Fn quota_maxid function returns the maximum user (or group) .Va id contained in the quota file associated with its .Va qf argument. .Pp The .Fn quota_check_path function checks if the specified path is within the filesystem that corresponds to its .Va qf argument. If the .Va path argument refers to a symbolic link, .Fn quota_check_path will follow it. .Pp The .Fn quota_convert function converts the quota file associated with its .Va qf argument to the data size specified by its .Va wordsize argument. The supported wordsize arguments are 32 for the old 32-bit quota file format and 64 for the new 64-bit quota file format. The .Fn quota_convert function may only be called to operate on quota files that are not currently active. .Sh IMPLEMENTATION NOTES If the underlying quota file is in or converted to the old 32-bit format, limit and usage values written to the quota file will be clipped to 32 bits. .Sh RETURN VALUES If the filesystem has quotas associated with it, .Fn quota_open -returns a pointer to a +returns a pointer to a .Vt quotafile structure used in subsequent quota access calls. If the filesystem has no quotas, or access permission is denied .Dv NULL is returned and .Va errno is set to indicate the error. .Pp The .Fn quota_check_path function returns\~1 for a positive result and\~0 for a negative result. If an error occurs, it returns\~-1 and sets .Va errno to indicate the error. .Pp The .Fn quota_read , .Fn quota_write_limits , .Fn quota_write_usage , .Fn quota_convert , and .Fn quota_close functions return zero on success. On error they return\~-1 and set .Va errno to indicate the error. .Sh SEE ALSO .Xr quotactl 2 , .Xr quota.user 5 , .Xr quota.group 5 .Sh HISTORY The .Nm quotafile functions first appeared in .Fx 8.1 . .Sh AUTHORS .An -nosplit The .Nm quotafile functions and this manual page were written by -.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org +.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org and .An Marshall Kirk McKusick Aq mckusick@mckusick.com . Index: stable/9/lib/libutil =================================================================== --- stable/9/lib/libutil (revision 237215) +++ stable/9/lib/libutil (revision 237216) Property changes on: stable/9/lib/libutil ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/lib/libutil:r233648 Index: stable/9/libexec/tftpd/tftpd.8 =================================================================== --- stable/9/libexec/tftpd/tftpd.8 (revision 237215) +++ stable/9/libexec/tftpd/tftpd.8 (revision 237216) @@ -1,314 +1,314 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" @(#)tftpd.8 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd June 22, 2011 .Dt TFTPD 8 .Os .Sh NAME .Nm tftpd .Nd Internet Trivial File Transfer Protocol server .Sh SYNOPSIS .Nm tftpd .Op Fl cdClnow .Op Fl F Ar strftime-format .Op Fl s Ar directory .Op Fl u Ar user .Op Fl U Ar umask .Op Ar directory ... .Sh DESCRIPTION The .Nm utility is a server which supports the Internet Trivial File Transfer Protocol .Pq Tn RFC 1350 . The .Tn TFTP server operates at the port indicated in the .Ql tftp service description; see .Xr services 5 . The server is normally started by .Xr inetd 8 . .Pp The use of .Xr tftp 1 does not require an account or password on the remote system. Due to the lack of authentication information, .Nm will allow only publicly readable files to be accessed. Files containing the string .Dq Li "/../" or starting with .Dq Li "../" are not allowed. Files may be written only if they already exist and are publicly writable. Note that this extends the concept of .Dq public to include all users on all hosts that can be reached through the network; this may not be appropriate on all systems, and its implications should be considered before enabling tftp service. The server should have the user ID with the lowest possible privilege. .Pp Access to files may be restricted by invoking .Nm with a list of directories by including up to 20 pathnames as server program arguments in .Xr inetd.conf 5 . In this case access is restricted to files whose names are prefixed by the one of the given directories. The given directories are also treated as a search path for relative filename requests. .Pp The .Fl s option provides additional security by changing the root directory of .Nm , thereby prohibiting accesses to outside of the specified .Ar directory . Because .Xr chroot 2 requires super-user privileges, .Nm must be run as .Li root . However, after performing the .Xr chroot 2 call, .Nm will set its user ID to that of the specified .Ar user , or .Dq Li nobody if no .Fl u option is specified. .Pp The options are: .Bl -tag -width Ds .It Fl c Changes the default root directory of a connecting host via .Xr chroot 2 based on the connecting IP address. This prevents multiple clients from writing to the same file at the same time. If the directory does not exist, the client connection is refused. The .Fl s option is required for .Fl c and the specified .Ar directory is used as a base. .It Fl C Operates the same as .Fl c except it falls back to .Ar directory specified via .Fl s if a directory does not exist for the client's IP. .It Fl F Use this .Xr strftime 3 compatible format string for the creation of the suffix if .Fl W is specified. By default the string "%Y%m%d" is used. .It Fl d, d Ar [value] Enables debug output. If .Ar value is not specified, then the debug level is increased by one for each instance of .Fl d which is specified. .Pp If .Ar value -is specified, then the debug level is set to +is specified, then the debug level is set to .Ar value . -The debug level is a bitmask implemented in +The debug level is a bitmask implemented in .Pa src/libexec/tftpd/tftp-utils.h . Valid values are 0 (DEBUG_NONE), 1 (DEBUG_PACKETS), 2, (DEBUG_SIMPLE), 4 (DEBUG_OPTIONS), and 8 (DEBUG_ACCESS). Multiple debug values can be combined in the bitmask by logically OR'ing the values. For example, specifying .Fl d .Ar 15 will enable all the debug values. .It Fl l Log all requests using .Xr syslog 3 with the facility of .Dv LOG_FTP . .Sy Note : Logging of .Dv LOG_FTP messages must also be enabled in the syslog configuration file, .Xr syslog.conf 5 . .It Fl n Suppress negative acknowledgement of requests for nonexistent relative filenames. .It Fl o Disable support for RFC2347 style TFTP Options. .It Fl s Ar directory Cause .Nm to change its root directory to .Ar directory . After doing that but before accepting commands, .Nm will switch credentials to an unprivileged user. .It Fl u Ar user Switch credentials to .Ar user (default .Dq Li nobody ) when the .Fl s option is used. The user must be specified by name, not a numeric UID. .It Fl U Ar umask Set the .Ar umask for newly created files. The default is 022 .Pq Dv S_IWGRP | S_IWOTH . .It Fl w Allow write requests to create new files. By default .Nm requires that the file specified in a write request exist. Note that this only works in directories writable by the user specified with .Fl u option .It Fl W As .Fl w but append a YYYYMMDD.nn sequence number to the end of the filename. Note that the string YYYYMMDD can be changed with the .Fl F option. .El .Sh SEE ALSO .Xr tftp 1 , .Xr chroot 2 , .Xr syslog 3 , .Xr inetd.conf 5 , .Xr services 5 , .Xr syslog.conf 5 , .Xr inetd 8 .Pp The following RFC's are supported: .Rs RFC 1350 .%T The TFTP Protocol (Revision 2) .Re .Rs RFC 2347 .%T TFTP Option Extension .Re .Rs RFC 2348 .%T TFTP Blocksize Option .Re .Rs RFC 2349 .%T TFTP Timeout Interval and Transfer Size Options .Re .Pp The non-standard .Cm rollover and .Cm blksize2 TFTP options are mentioned here: .Rs .%T Extending TFTP .%U http://www.compuphase.com/tftp.htm -.Re +.Re .Sh HISTORY The .Nm utility appeared in .Bx 4.2 ; the .Fl s option was introduced in .Fx 2.2 , the .Fl u option was introduced in .Fx 4.2 , the .Fl c option was introduced in .Fx 4.3 , and the .Fl F and .Fl W options were introduced in .Fx 7.4 . .Pp Support for Timeout Interval and Transfer Size Options (RFC2349) was introduced in .Fx 5.0 , support for the TFTP Blocksize Option (RFC2348) and the blksize2 option was introduced in .Fx 7.4 . .Pp Edwin Groothuis performed a major rewrite of the .Nm and .Xr tftp 1 code to support RFC2348. .Sh NOTES Files larger than 33,553,919 octets (65535 blocks, last one <512 octets) cannot be correctly transferred without client and server supporting blocksize negotiation (RFCs 2347 and 2348), or the non-standard TFTP rollover option. As a kludge, .Nm accepts a sequence of block number which wrap to zero after 65535, even if the rollover option is not specified. .Pp Many tftp clients will not transfer files over 16,776,703 octets (32767 blocks), as they incorrectly count the block number using a signed rather than unsigned 16-bit integer. Index: stable/9/libexec/tftpd =================================================================== --- stable/9/libexec/tftpd (revision 237215) +++ stable/9/libexec/tftpd (revision 237216) Property changes on: stable/9/libexec/tftpd ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/libexec/tftpd:r233648 Index: stable/9/sbin/camcontrol/camcontrol.8 =================================================================== --- stable/9/sbin/camcontrol/camcontrol.8 (revision 237215) +++ stable/9/sbin/camcontrol/camcontrol.8 (revision 237216) @@ -1,1236 +1,1236 @@ .\" .\" Copyright (c) 1998, 1999, 2000, 2002, 2005, 2006, 2007 Kenneth D. Merry. .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd November 30, 2010 .Dt CAMCONTROL 8 .Os .Sh NAME .Nm camcontrol .Nd CAM control program .Sh SYNOPSIS .Nm .Aq Ar command .Op device id .Op generic args .Op command args .Nm .Ic devlist .Op Fl v .Nm .Ic periphlist .Op device id .Op Fl n Ar dev_name .Op Fl u Ar unit_number .Nm .Ic tur .Op device id .Op generic args .Nm .Ic inquiry .Op device id .Op generic args .Op Fl D .Op Fl S .Op Fl R .Nm .Ic identify .Op device id .Op generic args .Op Fl v .Nm .Ic reportluns .Op device id .Op generic args .Op Fl c .Op Fl l .Op Fl r Ar reporttype .Nm .Ic readcap .Op device id .Op generic args .Op Fl b .Op Fl h .Op Fl H .Op Fl N .Op Fl q .Op Fl s .Nm .Ic start .Op device id .Op generic args .Nm .Ic stop .Op device id .Op generic args .Nm .Ic load .Op device id .Op generic args .Nm .Ic eject .Op device id .Op generic args .Nm .Ic rescan .Aq all | bus Ns Op :target:lun .Nm .Ic reset .Aq all | bus Ns Op :target:lun .Nm .Ic defects .Op device id .Op generic args .Aq Fl f Ar format .Op Fl P .Op Fl G .Nm .Ic modepage .Op device id .Op generic args .Aq Fl m Ar page | Fl l .Op Fl P Ar pgctl .Op Fl b | Fl e .Op Fl d .Nm .Ic cmd .Op device id .Op generic args .Aq Fl a Ar cmd Op args .Aq Fl c Ar cmd Op args .Op Fl d .Op Fl f .Op Fl i Ar len Ar fmt .Bk -words .Op Fl o Ar len Ar fmt Op args .Op Fl r Ar fmt .Ek .Nm .Ic smpcmd .Op device id .Op generic args .Aq Fl r Ar len Ar fmt Op args .Aq Fl R Ar len Ar fmt Op args .Nm .Ic smprg .Op device id .Op generic args .Op Fl l .Nm .Ic smppc .Op device id .Op generic args .Aq Fl p Ar phy .Op Fl l .Op Fl o Ar operation .Op Fl d Ar name .Op Fl m Ar rate .Op Fl M Ar rate .Op Fl T Ar pp_timeout .Op Fl a Ar enable|disable .Op Fl A Ar enable|disable .Op Fl s Ar enable|disable .Op Fl S Ar enable|disable .Nm .Ic smpphylist .Op device id .Op generic args .Op Fl l .Op Fl q .Nm .Ic smpmaninfo .Op device id .Op generic args .Op Fl l .Nm .Ic debug .Op Fl I .Op Fl P .Op Fl T .Op Fl S .Op Fl X .Op Fl c .Aq all|off|bus Ns Op :target Ns Op :lun .Nm .Ic tags .Op device id .Op generic args .Op Fl N Ar tags .Op Fl q .Op Fl v .Nm .Ic negotiate .Op device id .Op generic args .Op Fl c .Op Fl D Ar enable|disable .Op Fl M Ar mode .Op Fl O Ar offset .Op Fl q .Op Fl R Ar syncrate .Op Fl T Ar enable|disable .Op Fl U .Op Fl W Ar bus_width .Op Fl v .Nm .Ic format .Op device id .Op generic args .Op Fl q .Op Fl r .Op Fl w .Op Fl y .Nm .Ic idle .Op device id .Op generic args .Op Fl t Ar time .Nm .Ic standby .Op device id .Op generic args .Op Fl t Ar time .Nm .Ic sleep .Op device id .Op generic args .Nm .Ic help .Sh DESCRIPTION The .Nm utility is designed to provide a way for users to access and control the .Fx CAM subsystem. .Pp The .Nm utility can cause a loss of data and/or system crashes if used improperly. Even expert users are encouraged to exercise caution when using this command. Novice users should stay away from this utility. .Pp The .Nm utility has a number of primary functions, many of which support an optional device identifier. A device identifier can take one of three forms: .Bl -tag -width 14n .It deviceUNIT Specify a device name and unit number combination, like "da5" or "cd3". .It bus:target Specify a bus number and target id. The bus number can be determined from the output of .Dq camcontrol devlist . The lun defaults to 0. .It bus:target:lun Specify the bus, target and lun for a device. (e.g.\& 1:2:0) .El .Pp The device identifier, if it is specified, .Em must come immediately after the function name, and before any generic or function-specific arguments. Note that the .Fl n and .Fl u arguments described below will override any device name or unit number specified beforehand. The .Fl n and .Fl u arguments will .Em not override a specified bus:target or bus:target:lun, however. .Pp Most of the .Nm primary functions support these generic arguments: .Bl -tag -width 14n .It Fl C Ar count SCSI command retry count. In order for this to work, error recovery .Pq Fl E must be turned on. .It Fl E Instruct the kernel to perform generic SCSI error recovery for the given command. This is needed in order for the retry count .Pq Fl C to be honored. Other than retrying commands, the generic error recovery in the code will generally attempt to spin up drives that are not spinning. It may take some other actions, depending upon the sense code returned from the command. .It Fl n Ar dev_name Specify the device type to operate on, e.g.\& "da", "cd". .It Fl t Ar timeout SCSI command timeout in seconds. This overrides the default timeout for any given command. .It Fl u Ar unit_number Specify the device unit number, e.g.\& "1", "5". .It Fl v Be verbose, print out sense information for failed SCSI commands. .El .Pp Primary command functions: .Bl -tag -width periphlist .It Ic devlist List all physical devices (logical units) attached to the CAM subsystem. This also includes a list of peripheral drivers attached to each device. With the .Fl v argument, SCSI bus number, adapter name and unit numbers are printed as well. .It Ic periphlist List all peripheral drivers attached to a given physical device (logical unit). .It Ic tur Send the SCSI test unit ready (0x00) command to the given device. The .Nm utility will report whether the device is ready or not. .It Ic inquiry Send a SCSI inquiry command (0x12) to a device. By default, .Nm will print out the standard inquiry data, device serial number, and transfer rate information. The user can specify that only certain types of inquiry data be printed: .Bl -tag -width 4n .It Fl D Get the standard inquiry data. .It Fl S Print out the serial number. If this flag is the only one specified, .Nm will not print out "Serial Number" before the value returned by the drive. This is to aid in script writing. .It Fl R Print out transfer rate information. .El .It Ic identify Send a ATA identify command (0xec) to a device. .It Ic reportluns Send the SCSI REPORT LUNS (0xA0) command to the given device. By default, .Nm will print out the list of logical units (LUNs) supported by the target device. There are a couple of options to modify the output: .Bl -tag -width 14n .It Fl c Just print out a count of LUNs, not the actual LUN numbers. .It Fl l Just print out the LUNs, and don't print out the count. .It Fl r Ar reporttype Specify the type of report to request from the target: .Bl -tag -width 012345678 .It default Return the default report. This is the .Nm default. Most targets will support this report if they support the REPORT LUNS command. .It wellknown Return only well known LUNs. .It all Return all available LUNs. .El .El .Pp .Nm will try to print out LUN numbers in a reasonable format. It can understand the peripheral, flat, LUN and extended LUN formats. .It Ic readcap Send the SCSI READ CAPACITY command to the given device and display the results. If the device is larger than 2TB, the SCSI READ CAPACITY (16) service action will be sent to obtain the full size of the device. By default, .Nm will print out the last logical block of the device, and the blocksize of the device in bytes. To modify the output format, use the following options: .Bl -tag -width 5n .It Fl b Just print out the blocksize, not the last block or device size. This cannot be used with .Fl N or .Fl s . .It Fl h Print out the device size in human readable (base 2, 1K == 1024) format. This implies .Fl N and cannot be used with .Fl q or .Fl b . .It Fl H Print out the device size in human readable (base 10, 1K == 1000) format. .It Fl N Print out the number of blocks in the device instead of the last logical block. .It Fl q Quiet, print out the numbers only (separated by a comma if .Fl b or .Fl s are not specified). .It Fl s Print out the last logical block or the size of the device only, and omit the blocksize. .El .It Ic start Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit set. .It Ic stop Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit cleared. .It Ic load Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit set and the load/eject bit set. .It Ic eject Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit cleared and the load/eject bit set. .It Ic rescan Tell the kernel to scan all busses in the system (with the .Ar all argument), the given bus (XPT_SCAN_BUS), or bus:target:lun (XPT_SCAN_LUN) for new devices or devices that have gone away. The user may specify a scan of all busses, a single bus, or a lun. Scanning all luns on a target is not supported. .It Ic reset Tell the kernel to reset all busses in the system (with the .Ar all argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus reset for that bus, or to reset the given bus:target:lun (XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after connecting to that device. Note that this can have a destructive impact on the system. .It Ic defects Send the SCSI READ DEFECT DATA (10) command (0x37) to the given device, and print out any combination of: the total number of defects, the primary defect list (PLIST), and the grown defect list (GLIST). .Bl -tag -width 11n .It Fl f Ar format The three format options are: .Em block , to print out the list as logical blocks, .Em bfi , to print out the list in bytes from index format, and .Em phys , to print out the list in physical sector format. The format argument is required. Most drives support the physical sector format. Some drives support the logical block format. Many drives, if they do not support the requested format, return the data in an alternate format, along with sense information indicating that the requested data format is not supported. The .Nm utility attempts to detect this, and print out whatever format the drive returns. If the drive uses a non-standard sense code to report that it does not support the requested format, .Nm will probably see the error as a failure to complete the request. .It Fl G Print out the grown defect list. This is a list of bad blocks that have been remapped since the disk left the factory. .It Fl P Print out the primary defect list. .El .Pp If neither .Fl P nor .Fl G is specified, .Nm will print out the number of defects given in the READ DEFECT DATA header returned from the drive. .It Ic modepage Allows the user to display and optionally edit a SCSI mode page. The mode page formats are located in .Pa /usr/share/misc/scsi_modes . This can be overridden by specifying a different file in the .Ev SCSI_MODES environment variable. The .Ic modepage command takes several arguments: .Bl -tag -width 12n .It Fl d Disable block descriptors for mode sense. .It Fl b Displays mode page data in binary format. .It Fl e This flag allows the user to edit values in the mode page. The user may either edit mode page values with the text editor pointed to by his .Ev EDITOR environment variable, or supply mode page values via standard input, using the same format that .Nm uses to display mode page values. The editor will be invoked if .Nm detects that standard input is terminal. .It Fl l Lists all available mode pages. .It Fl m Ar mode_page This specifies the number of the mode page the user would like to view and/or edit. This argument is mandatory unless .Fl l is specified. .It Fl P Ar pgctl This allows the user to specify the page control field. Possible values are: .Bl -tag -width xxx -compact .It 0 Current values .It 1 Changeable values .It 2 Default values .It 3 Saved values .El .El .It Ic cmd Allows the user to send an arbitrary ATA or SCSI CDB to any device. The .Ic cmd function requires the .Fl c argument to specify SCSI CDB or the .Fl a argument to specify ATA Command Block registers values. Other arguments are optional, depending on the command type. The command and data specification syntax is documented in .Xr cam_cdbparse 3 . NOTE: If the CDB specified causes data to be transferred to or from the SCSI device in question, you MUST specify either .Fl i or .Fl o . .Bl -tag -width 17n .It Fl a Ar cmd Op args This specifies the content of 12 ATA Command Block registers (command, features, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp. lba_high_exp, features_exp, sector_count, sector_count_exp). .It Fl c Ar cmd Op args This specifies the SCSI CDB. SCSI CDBs may be 6, 10, 12 or 16 bytes. .It Fl d Specifies DMA protocol to be used for ATA command. .It Fl f Specifies FPDMA (NCQ) protocol to be used for ATA command. .It Fl i Ar len Ar fmt This specifies the amount of data to read, and how it should be displayed. If the format is .Sq - , .Ar len bytes of data will be read from the device and written to standard output. .It Fl o Ar len Ar fmt Op args This specifies the amount of data to be written to a device, and the data that is to be written. If the format is .Sq - , .Ar len bytes of data will be read from standard input and written to the device. .It Fl r Ar fmt This specifies that 11 result ATA Command Block registers should be displayed (status, error, lba_low, lba_mid, lba_high, device, lba_low_exp, lba_mid_exp, lba_high_exp, sector_count, sector_count_exp), and how. If the format is .Sq - , 11 result registers will be written to standard output in hex. .El .It Ic smpcmd -Allows the user to send an arbitrary Serial +Allows the user to send an arbitrary Serial Management Protocol (SMP) command to a device. The .Ic smpcmd function requires the .Fl r argument to specify the SMP request to be sent, and the .Fl R argument to specify the format of the SMP response. The syntax for the SMP request and response arguments is documented in .Xr cam_cdbparse 3 . .Pp Note that SAS adapters that support SMP passthrough (at least the currently known adapters) do not accept CRC bytes from the user in the request and do not pass CRC bytes back to the user in the response. Therefore users should not include the CRC bytes in the length of the request and not expect CRC bytes to be returned in the response. .Bl -tag -width 17n .It Fl r Ar len Ar fmt Op args This specifies the size of the SMP request, without the CRC bytes, and the SMP request format. If the format is .Sq - , .Ar len bytes of data will be read from standard input and written as the SMP request. .It Fl R Ar len Ar fmt Op args This specifies the size of the buffer allocated for the SMP response, and the SMP response format. If the format is .Sq - , .Ar len bytes of data will be allocated for the response and the response will be written to standard output. .El .It Ic smprg Allows the user to send the Serial Management Protocol (SMP) Report General command to a device. .Nm will display the data returned by the Report General command. If the SMP target supports the long response format, the additional data will be requested and displayed automatically. .Bl -tag -width 8n .It Fl l Request the long response format only. Not all SMP targets support the long response format. This option causes .Nm to skip sending the initial report general request without the long bit set and only issue a report general request with the long bit set. .El .It Ic smppc Allows the user to issue the Serial Management Protocol (SMP) PHY Control command to a device. This function should be used with some caution, as it can render devices inaccessible, and could potentially cause data corruption as well. The .Fl p argument is required to specify the PHY to operate on. .Bl -tag -width 17n .It Fl p Ar phy Specify the PHY to operate on. -This argument is required. +This argument is required. .It Fl l Request the long request/response format. Not all SMP targets support the long response format. For the PHY Control command, this currently only affects whether the request length is set to a value other than 0. .It Fl o Ar operation Specify a PHY control operation. Only one .Fl o operation may be specified. The operation may be specified numerically (in decimal, hexadecimal, or octal) or one of the following operation names may be specified: .Bl -tag -width 16n .It nop No operation. It is not necessary to specify this argument. .It linkreset Send the LINK RESET command to the phy. .It hardreset Send the HARD RESET command to the phy. .It disable Send the DISABLE command to the phy. Note that the LINK RESET or HARD RESET commands should re-enable the phy. .It clearerrlog Send the CLEAR ERROR LOG command. This clears the error log counters for the specified phy. .It clearaffiliation Send the CLEAR AFFILIATION command. This clears the affiliation from the STP initiator port with the same SAS address as the SMP initiator that requests the clear operation. .It sataportsel Send the TRANSMIT SATA PORT SELECTION SIGNAL command to the phy. This will cause a SATA port selector to use the given phy as its active phy and make the other phy inactive. .It clearitnl Send the CLEAR STP I_T NEXUS LOSS command to the PHY. .It setdevname Send the SET ATTACHED DEVICE NAME command to the PHY. This requires the .Fl d argument to specify the device name. .El .It Fl d Ar name Specify the attached device name. This option is needed with the .Fl o Ar setdevname phy operation. The name is a 64-bit number, and can be specified in decimal, hexadecimal or octal format. .It Fl m Ar rate Set the minimum physical link rate for the phy. This is a numeric argument. Currently known link rates are: .Bl -tag -width 5n .It 0x0 Do not change current value. .It 0x8 1.5 Gbps .It 0x9 3 Gbps .It 0xa 6 Gbps .El .Pp Other values may be specified for newer physical link rates. .It Fl M Ar rate Set the maximum physical link rate for the phy. This is a numeric argument. See the .Fl m argument description for known link rate arguments. .It Fl T Ar pp_timeout Set the partial pathway timeout value, in microseconds. See the .Tn ANSI .Tn SAS Protcol Layer (SPL) specification for more information on this field. .It Fl a Ar enable|disable Enable or disable SATA slumber phy power conditions. .It Fl A Ar enable|disable Enable or disable SATA partial power conditions. .It Fl s Ar enable|disable Enable or disable SAS slumber phy power conditions. .It Fl S Ar enable|disable Enable or disable SAS partial phy power conditions. .El .It Ic smpphylist List phys attached to a SAS expander, the address of the end device attached to the phy, and the inquiry data for that device and peripheral devices attached to that device. The inquiry data and peripheral devices are displayed if available. .Bl -tag -width 5n .It Fl l Turn on the long response format for the underlying SMP commands used for this command. .It Fl q Only print out phys that are attached to a device in the CAM EDT (Existing Device Table). .El .It Ic smpmaninfo Send the SMP Report Manufacturer Information command to the device and display the response. .Bl -tag -width 5n .It Fl l Turn on the long response format for the underlying SMP commands used for this command. .El .It Ic debug Turn on CAM debugging printfs in the kernel. This requires options CAMDEBUG in your kernel config file. WARNING: enabling debugging printfs currently causes an EXTREME number of kernel printfs. You may have difficulty turning off the debugging printfs once they start, since the kernel will be busy printing messages and unable to service other requests quickly. The .Ic debug function takes a number of arguments: .Bl -tag -width 18n .It Fl I Enable CAM_DEBUG_INFO printfs. .It Fl P Enable CAM_DEBUG_PERIPH printfs. .It Fl T Enable CAM_DEBUG_TRACE printfs. .It Fl S Enable CAM_DEBUG_SUBTRACE printfs. .It Fl X Enable CAM_DEBUG_XPT printfs. .It Fl c Enable CAM_DEBUG_CDB printfs. This will cause the kernel to print out the SCSI CDBs sent to the specified device(s). .It all Enable debugging for all devices. .It off Turn off debugging for all devices .It bus Ns Op :target Ns Op :lun Turn on debugging for the given bus, target or lun. If the lun or target and lun are not specified, they are wildcarded. (i.e., just specifying a bus turns on debugging printfs for all devices on that bus.) .El .It Ic tags Show or set the number of "tagged openings" or simultaneous transactions we attempt to queue to a particular device. By default, the .Ic tags command, with no command-specific arguments (i.e., only generic arguments) prints out the "soft" maximum number of transactions that can be queued to the device in question. For more detailed information, use the .Fl v argument described below. .Bl -tag -width 7n .It Fl N Ar tags Set the number of tags for the given device. This must be between the minimum and maximum number set in the kernel quirk table. The default for most devices that support tagged queueing is a minimum of 2 and a maximum of 255. The minimum and maximum values for a given device may be determined by using the .Fl v switch. The meaning of the .Fl v switch for this .Nm subcommand is described below. .It Fl q Be quiet, and do not report the number of tags. This is generally used when setting the number of tags. .It Fl v The verbose flag has special functionality for the .Em tags argument. It causes .Nm to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB: .Bl -tag -width 13n .It dev_openings This is the amount of capacity for transactions queued to a given device. .It dev_active This is the number of transactions currently queued to a device. .It devq_openings This is the kernel queue space for transactions. This count usually mirrors dev_openings except during error recovery operations when the device queue is frozen (device is not allowed to receive commands), the number of dev_openings is reduced, or transaction replay is occurring. .It devq_queued This is the number of transactions waiting in the kernel queue for capacity on the device. This number is usually zero unless error recovery is in progress. .It held The held count is the number of CCBs held by peripheral drivers that have either just been completed or are about to be released to the transport layer for service by a device. Held CCBs reserve capacity on a given device. .It mintags This is the current "hard" minimum number of transactions that can be queued to a device at once. The .Ar dev_openings value above cannot go below this number. The default value for .Ar mintags is 2, although it may be set higher or lower for various devices. .It maxtags This is the "hard" maximum number of transactions that can be queued to a device at one time. The .Ar dev_openings value cannot go above this number. The default value for .Ar maxtags is 255, although it may be set higher or lower for various devices. .El .El .It Ic negotiate Show or negotiate various communication parameters. Some controllers may not support setting or changing some of these values. For instance, the Adaptec 174x controllers do not support changing a device's sync rate or offset. The .Nm utility will not attempt to set the parameter if the controller indicates that it does not support setting the parameter. To find out what the controller supports, use the .Fl v flag. The meaning of the .Fl v flag for the .Ic negotiate command is described below. Also, some controller drivers do not support setting negotiation parameters, even if the underlying controller supports negotiation changes. Some controllers, such as the Advansys wide controllers, support enabling and disabling synchronous negotiation for a device, but do not support setting the synchronous negotiation rate. .Bl -tag -width 17n .It Fl a Attempt to make the negotiation settings take effect immediately by sending a Test Unit Ready command to the device. .It Fl c Show or set current negotiation settings. This is the default. .It Fl D Ar enable|disable Enable or disable disconnection. .It Fl M Ar mode Set ATA mode. .It Fl O Ar offset Set the command delay offset. .It Fl q Be quiet, do not print anything. This is generally useful when you want to set a parameter, but do not want any status information. .It Fl R Ar syncrate Change the synchronization rate for a device. The sync rate is a floating point value specified in MHz. So, for instance, .Sq 20.000 is a legal value, as is .Sq 20 . .It Fl T Ar enable|disable Enable or disable tagged queueing for a device. .It Fl U Show or set user negotiation settings. The default is to show or set current negotiation settings. .It Fl v The verbose switch has special meaning for the .Ic negotiate subcommand. It causes .Nm to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the controller driver. .It Fl W Ar bus_width Specify the bus width to negotiate with a device. The bus width is specified in bits. The only useful values to specify are 8, 16, and 32 bits. The controller must support the bus width in question in order for the setting to take effect. .El .Pp In general, sync rate and offset settings will not take effect for a device until a command has been sent to the device. The .Fl a switch above will automatically send a Test Unit Ready to the device so negotiation parameters will take effect. .It Ic format Issue the .Tn SCSI FORMAT UNIT command to the named device. .Pp .Em WARNING! WARNING! WARNING! .Pp Low level formatting a disk will destroy ALL data on the disk. Use extreme caution when issuing this command. Many users low-level format disks that do not really need to be low-level formatted. There are relatively few scenarios that call for low-level formatting a disk. One reason for low-level formatting a disk is to initialize the disk after changing its physical sector size. Another reason for low-level formatting a disk is to revive the disk if you are getting "medium format corrupted" errors from the disk in response to read and write requests. .Pp Some disks take longer than others to format. Users should specify a timeout long enough to allow the format to complete. The default format timeout is 3 hours, which should be long enough for most disks. Some hard disks will complete a format operation in a very short period of time (on the order of 5 minutes or less). This is often because the drive does not really support the FORMAT UNIT command -- it just accepts the command, waits a few minutes and then returns it. .Pp The .Sq format subcommand takes several arguments that modify its default behavior. The .Fl q and .Fl y arguments can be useful for scripts. .Bl -tag -width 6n .It Fl q Be quiet, do not print any status messages. This option will not disable the questions, however. To disable questions, use the .Fl y argument, below. .It Fl r Run in .Dq report only mode. This will report status on a format that is already running on the drive. .It Fl w Issue a non-immediate format command. By default, .Nm issues the FORMAT UNIT command with the immediate bit set. This tells the device to immediately return the format command, before the format has actually completed. Then, .Nm gathers .Tn SCSI sense information from the device every second to determine how far along in the format process it is. If the .Fl w argument is specified, .Nm will issue a non-immediate format command, and will be unable to print any information to let the user know what percentage of the disk has been formatted. .It Fl y Do not ask any questions. By default, .Nm will ask the user if he/she really wants to format the disk in question, and also if the default format command timeout is acceptable. The user will not be asked about the timeout if a timeout is specified on the command line. .El .It Ic idle Put ATA device into IDLE state. Optional parameter .Pq Fl t specifies automatic standby timer value in seconds. Value 0 disables timer. .It Ic standby Put ATA device into STANDBY state. Optional parameter .Pq Fl t specifies automatic standby timer value in seconds. Value 0 disables timer. .It Ic sleep Put ATA device into SLEEP state. Note that the only way get device out of this state may be reset. .It Ic help Print out verbose usage information. .El .Sh ENVIRONMENT The .Ev SCSI_MODES variable allows the user to specify an alternate mode page format file. .Pp The .Ev EDITOR variable determines which text editor .Nm starts when editing mode pages. .Sh FILES .Bl -tag -width /usr/share/misc/scsi_modes -compact .It Pa /usr/share/misc/scsi_modes is the SCSI mode format database. .It Pa /dev/xpt0 is the transport layer device. .It Pa /dev/pass* are the CAM application passthrough devices. .El .Sh EXAMPLES .Dl camcontrol eject -n cd -u 1 -v .Pp Eject the CD from cd1, and print SCSI sense information if the command fails. .Pp .Dl camcontrol tur da0 .Pp Send the SCSI test unit ready command to da0. The .Nm utility will report whether the disk is ready, but will not display sense information if the command fails since the .Fl v switch was not specified. .Bd -literal -offset indent camcontrol tur da1 -E -C 4 -t 50 -v .Ed .Pp Send a test unit ready command to da1. Enable kernel error recovery. Specify a retry count of 4, and a timeout of 50 seconds. Enable sense printing (with the .Fl v flag) if the command fails. Since error recovery is turned on, the disk will be spun up if it is not currently spinning. The .Nm utility will report whether the disk is ready. .Bd -literal -offset indent camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" .Ed .Pp Issue a READ BUFFER command (0x3C) to cd1. Display the buffer size of cd1, and display the first 10 bytes from the cache on cd1. Display SCSI sense information if the command fails. .Bd -literal -offset indent camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 .Ed .Pp Issue a WRITE BUFFER (0x3B) command to cd1. Write out 10 bytes of data, not including the (reserved) 4 byte header. Print out sense information if the command fails. Be very careful with this command, improper use may cause data corruption. .Bd -literal -offset indent camcontrol modepage da3 -m 1 -e -P 3 .Ed .Pp Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the settings on the drive. Mode page 1 contains a disk drive's auto read and write reallocation settings, among other things. .Pp .Dl camcontrol rescan all .Pp Rescan all SCSI busses in the system for devices that have been added, removed or changed. .Pp .Dl camcontrol rescan 0 .Pp Rescan SCSI bus 0 for devices that have been added, removed or changed. .Pp .Dl camcontrol rescan 0:1:0 .Pp Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or changed. .Pp .Dl camcontrol tags da5 -N 24 .Pp Set the number of concurrent transactions for da5 to 24. .Bd -literal -offset indent camcontrol negotiate -n da -u 4 -T disable .Ed .Pp Disable tagged queueing for da4. .Bd -literal -offset indent camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a .Ed .Pp Negotiate a sync rate of 20MHz and an offset of 15 with da3. Then send a Test Unit Ready command to make the settings take effect. .Pp .Bd -literal -offset indent camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1" .Ed .Pp Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs it contains. Display SMP errors if the command fails. .Sh SEE ALSO .Xr cam 3 , .Xr cam_cdbparse 3 , .Xr cam 4 , .Xr pass 4 , .Xr xpt 4 .Sh HISTORY The .Nm utility first appeared in .Fx 3.0 . .Pp The mode page editing code and arbitrary SCSI command code are based upon code in the old .Xr scsi 8 utility and .Xr scsi 3 library, written by Julian Elischer and Peter Dufault. The .Xr scsi 8 program first appeared in .Bx 386 0.1.2.4 , and first appeared in .Fx in .Fx 2.0.5 . .Sh AUTHORS .An Kenneth Merry Aq ken@FreeBSD.org .Sh BUGS The code that parses the generic command line arguments does not know that some of the subcommands take multiple arguments. So if, for instance, you tried something like this: .Bd -literal -offset indent camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v .Ed .Pp The sense information from the test unit ready command would not get printed out, since the first .Xr getopt 3 call in .Nm bails out when it sees the second argument to .Fl c (0x00), above. Fixing this behavior would take some gross code, or changes to the .Xr getopt 3 interface. The best way to circumvent this problem is to always make sure to specify generic .Nm arguments before any command-specific arguments. Index: stable/9/sbin/camcontrol =================================================================== --- stable/9/sbin/camcontrol (revision 237215) +++ stable/9/sbin/camcontrol (revision 237216) Property changes on: stable/9/sbin/camcontrol ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin/camcontrol:r233648 Index: stable/9/sbin/devfs/devfs.8 =================================================================== --- stable/9/sbin/devfs/devfs.8 (revision 237215) +++ stable/9/sbin/devfs/devfs.8 (revision 237216) @@ -1,376 +1,376 @@ .\" .\" Copyright (c) 2002 Dima Dorfman. .\" 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. .\" .\" $FreeBSD$ .\" .Dd February 21, 2010 .Dt DEVFS 8 .Os .Sh NAME .Nm devfs .Nd "DEVFS control" .Sh SYNOPSIS .Nm .Op Fl m Ar mount-point .Ar keyword .Ar argument ... .Sh DESCRIPTION The .Nm utility provides an interface to manipulate properties of .Xr devfs 5 mounts. .Pp The .Ar keyword argument determines the context for the rest of the arguments. For example, most of the commands related to the rule subsystem must be preceded by the .Cm rule keyword. The following flags are common to all keywords: .Bl -tag -offset indent .It Fl m Ar mount-point Operate on .Ar mount-point , which is expected to be a .Xr devfs 5 mount. If this option is not specified, .Nm operates on .Pa /dev . .El .Ss Rule Subsystem The .Xr devfs 5 rule subsystem provides a way for the administrator of a system to control the attributes of DEVFS nodes. .\" XXX devfs node? entry? what? Each DEVFS mount-point has a .Dq ruleset , or a list of rules, associated with it. When a device driver creates a new node, all the rules in the ruleset associated with each mount-point are applied (see below) before the node becomes visible to the userland. This permits the administrator to change the properties, including the visibility, of certain nodes. For example, one might want to hide all disk nodes in a .Xr jail 2 Ns 's .Pa /dev . .Ss Rule Manipulation Rule manipulation commands follow the .Cm rule keyword. The following flags are common to all of the rule manipulation commands: .Bl -tag -offset indent .It Fl s Ar ruleset Operate on the ruleset with the number .Ar ruleset . If this is not specified, the commands operate on the ruleset currently associated with the specified mount-point. .El .Pp The following commands are recognized: .Bl -tag -offset indent .It Cm rule add Oo Ar rulenum Oc Ar rulespec Add the rule described by .Ar rulespec (defined below) to the ruleset. The rule has the number .Ar rulenum if it is explicitly specified; otherwise, the rule number is automatically determined by the kernel. .It Cm rule apply Ar rulenum | rulespec Apply rule number .Ar rulenum or the rule described by .Ar rulespec to the mount-point. Rules that are .Dq applied have their conditions checked against all nodes in the mount-point and the actions taken if they match. .It Cm rule applyset Apply all the rules in the ruleset to the mount-point (see above for the definition of .Dq apply ) . .It Cm rule del Ar rulenum Delete rule number .Ar rulenum from the ruleset. .It Cm rule delset Delete all rules from the ruleset. .It Cm rule show Op Ar rulenum Display the rule number .Ar rulenum , or all the rules in the ruleset. The output lines (one line per rule) are expected to be valid .Ar rulespec Ns s . .It Cm rule showsets Report the numbers of existing rulesets. .It Cm ruleset Ar ruleset Set ruleset number .Ar ruleset as the current ruleset for the mount-point. .El .Ss Rule Specification Rules have two parts: the conditions and the actions. The conditions determine which DEVFS nodes the rule matches and the actions determine what should be done when a rule matches a node. For example, a rule can be written that sets the GID to .Dq Li operator for all devices of type tape. If the first token of a rule specification is a single dash .Pq Sq Fl , rules are read from the standard input and the rest of the specification is ignored. .Pp The following conditions are recognized. Conditions are ANDed together when matching a device; if OR is desired, multiple rules can be written. .Bl -tag -offset indent .It Cm path Ar pattern Matches any node with a path that matches .Ar pattern , which is interpreted as a .Xr glob 3 Ns -style pattern. .It Cm type Ar devtype Matches any node that is of type .Ar devtype . Valid types are .Cm disk , mem , tape and .Cm tty . .El .Pp The following actions are recognized. Although there is no explicit delimiter between conditions and actions, they may not be intermixed. .Bl -tag -offset indent .It Cm group Ar gid Set the GID of the node to .Ar gid , which may be a group name (looked up in .Pa /etc/group ) or number. .It Cm hide Hide the node. Nodes may later be revived manually with .Xr mknod 8 or with the .Cm unhide action. .It Cm include Ar ruleset Apply all the rules in ruleset number .Ar ruleset to the node. This does not necessarily result in any changes to the node (e.g., if none of the rules in the included ruleset match). Include commands in the referenced .Ar ruleset are not resolved. .It Cm mode Ar filemode Set the file mode to .Ar filemode , which is interpreted as in .Xr chmod 1 . .It Cm user Ar uid Set the UID to .Ar uid , which may be a user name (looked up in .Pa /etc/passwd ) or number. .It Cm unhide Unhide the node. .El .Sh IMPLEMENTATION NOTES Rulesets are created by the kernel at the first reference and destroyed when the last reference disappears. E.g., a ruleset is created when a rule is added to it or when it is set as the current ruleset for a mount-point, and a ruleset is destroyed when the last rule in it is deleted and no other references to it exist (i.e., it is not included by any rules and it is not the current ruleset for any mount-point). .Pp Ruleset number 0 is the default ruleset for all new mount-points. It is always empty, cannot be modified or deleted, and does not show up in the output of .Cm showsets . .Pp Rules and rulesets are unique to the entire system, not a particular mount-point. I.e., a .Cm showsets will return the same information regardless of the mount-point specified with .Fl m . The mount-point is only relevant when changing what its current ruleset is or when using one of the apply commands. .Sh FILES .Bl -tag -compact .It Pa /etc/defaults/devfs.rules Default .Nm configuration file. .It Pa /etc/devfs.rules Local .Nm configuration file. Rulesets in here override those in -.Pa /etc/defaults/devfs.rules -with the same ruleset number, otherwise the two files are effectively merged. +.Pa /etc/defaults/devfs.rules +with the same ruleset number, otherwise the two files are effectively merged. .It Pa /etc/devfs.conf Boot-time .Nm configuration file. .It Pa /usr/share/examples/etc/devfs.conf Example boot-time .Nm configuration file. .El .Sh EXAMPLES When the system boots, the only ruleset that exists is ruleset number 0; since the latter may not be modified, we have to create another ruleset before adding rules. Note that since most of the following examples do not specify .Fl m , the operations are performed on .Pa /dev (this only matters for things that might change the properties of nodes). .Pp .Dl "devfs ruleset 10" .Pp Specify that ruleset 10 should be the current ruleset for .Pa /dev (if it does not already exist, it is created). .Pp .Dl "devfs rule add path speaker mode 666" .Pp Add a rule that causes all nodes that have a path that matches .Dq Li speaker (this is only .Pa /dev/speaker ) to have the file mode 666 (read and write for all). Note that if any such nodes already exist, their mode will not be changed unless this rule (or ruleset) is explicitly applied (see below). The mode .Em will be changed if the node is created .Em after the rule is added (e.g., the .Pa atspeaker module is loaded after the above rule is added). .Pp .Dl "devfs rule applyset" .Pp Apply all the rules in the current ruleset to all the existing nodes. E.g., if the above rule was added after .Pa /dev/speaker was created, this command will cause its file mode to be changed to 666 as prescribed by the rule. .Pp .Dl devfs rule add path "snp*" mode 660 group snoopers .Pp (Quoting the argument to .Cm path is often necessary to disable the shell's globbing features.) For all devices with a path that matches .Dq Li snp* , set the file mode to 660 and the GID to .Dq Li snoopers . This permits users in the .Dq Li snoopers group to use the .Xr snp 4 devices. .Pp .Dl "devfs rule -s 20 add type disk group wheel" .Pp Add a rule to ruleset number 20. Since this ruleset is not the current ruleset for any mount-points, this rule is never applied automatically (unless ruleset 20 becomes a current ruleset for some mount-point at a later time). However, it can be applied explicitly, as such: .Pp .Dl "devfs -m /my/jail/dev rule -s 20 applyset" .Pp This will apply all rules in ruleset number 20 to the DEVFS mount on .Pa /my/jail/dev . It does not matter that ruleset 20 is not the current ruleset for that mount-point; the rules are still applied. .Pp .Dl "devfs rule apply hide" .Pp Since this rule has no conditions, the action .Pq Cm hide will be applied to all nodes. Since hiding all nodes is not very useful, we can undo it: .Pp .Dl "devfs rule apply unhide" .Pp which applies .Cm unhide to all the nodes, causing them to reappear. .Pp .Dl "devfs rule -s 10 add - < my_rules" .Pp Add all the rules from the file .Pa my_rules to ruleset 10. .Pp .Dl "devfs rule -s 20 show | devfs rule -s 10 add -" .Pp Since .Cm show outputs valid rules, this feature can be used to copy rulesets. The above copies all the rules from ruleset 20 into ruleset 10. The rule numbers are preserved, but ruleset 10 may already have rules with non-conflicting numbers (these will be preserved). .Sh SEE ALSO .Xr chmod 1 , .Xr jail 2 , .Xr glob 3 , .Xr devfs 5 , .Xr devfs.conf 5 , .Xr devfs.rules 5 , .Xr chown 8 , .Xr jail 8 , .Xr mknod 8 .Sh AUTHORS .An Dima Dorfman Index: stable/9/sbin/devfs =================================================================== --- stable/9/sbin/devfs (revision 237215) +++ stable/9/sbin/devfs (revision 237216) Property changes on: stable/9/sbin/devfs ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/quota64/sbin/devfs:r184125-207707 Merged /head/sbin/devfs:r2-3,227006,233648 Merged /user/piso/sbin/devfs:r186725 Merged /projects/largeSMP/sbin/devfs:r221273-222812,222815-223757 Merged /vendor/resolver/dist/sbin/devfs:r1540-186085 Index: stable/9/sbin/gvinum/gvinum.8 =================================================================== --- stable/9/sbin/gvinum/gvinum.8 (revision 237215) +++ stable/9/sbin/gvinum/gvinum.8 (revision 237216) @@ -1,441 +1,441 @@ .\" Copyright (c) 2005 Chris Jones .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris Jones .\" thanks to the support of Google's Summer of Code program and .\" mentoring by Lukas Ertl. .\" .\" 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 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 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 10, 2009 .Dt GVINUM 8 .Os .Sh NAME .Nm gvinum .Nd Logical Volume Manager control program .Sh SYNOPSIS .Nm .Op Ar command .Op Fl options .Sh COMMANDS .Bl -tag -width indent .It Ic attach Ar plex volume Op Cm rename .It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename -Attach a plex to a volume, or a subdisk to a plex. +Attach a plex to a volume, or a subdisk to a plex. If offset is specified, the subdisk will be attached to the given offset within the plex. If rename is specified, the subdisk or plex will change name according to the object it attaches to. .It Ic checkparity Oo Fl f Oc Ar plex Check the parity blocks of a RAID-5 plex. The parity check will start at the beginning of the plex if the .Fl f flag is specified, or otherwise at the location of the parity check pointer, the first location at which plex's parity is incorrect. All subdisks in the plex must be up for a parity check. .It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives Create a concatenated volume from the specified drives. If no name is specified, a unique name will be set by gvinum. .It Ic create Oo Fl f Oc Op Ar description-file Create a volume as described in .Ar description-file . If no .Ar description-file provided, opens an editor and provides the current .Nm configuration for editing. The .Fl f flag will make gvinum ignore any errors regarding creating objects that already exists. However, in contrast to vinum, objects that are not properly named in the .Ar description-file will not be created when the .Fl f flag is given. .It Ic detach Oo Fl f Oc Op Ar plex | subdisk Detach a plex or subdisk from the volume or plex to which it is attached. .It Ic grow Ar plex device Grow a plex by creating a gvinum drive and subdisk on device and attach it to the plex. If required by the plex organization, it will be put into the growable state. .It Ic help Provides a synopsis of .Nm commands and arguments. .It Ic l | list Oo Fl rvV Oc Op Ar volume | plex | subdisk .It Ic ld Oo Fl rvV Oc Op Ar drive ... .It Ic ls Oo Fl rvV Oc Op Ar subdisk ... .It Ic lp Oo Fl rvV Oc Op Ar plex ... .It Ic lv Oo Fl rvV Oc Op Ar volume ... List information about the relevant object(s). The .Fl r flag provides recursive display, showing each object's subordinate objects in proper relation. The .Fl v and .Fl V flags provide progressively more detailed output. .It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives -Create a mirrored volume from the specified drives. +Create a mirrored volume from the specified drives. It requires at least a multiple of 2 drives. If no name is specified, a unique name will be set by gvinum. -If the +If the .Fl s flag is specified, a striped mirror will be created, and thus requires a multiple of 4 drives. .It Ic move | mv Fl f Ar drive subdisk Op Ar ... Move the subdisk(s) to the specified drive. The .Fl f flag is required, as all data on the indicated subdisk(s) will be destroyed as part of the move. This can currently only be done when the subdisk is not being accessed. .Pp If a single subdisk is moved, and it forms a part of a RAID-5 plex, the moved subdisks will need to be set to the .Dq stale state, and the plex will require a .Ic start command. If multiple subdisk(s) is moved, and form part of a RAID-5 plex, the moved disk(s) will need to be set to the .Dq up state and the plex will require a .Ic rebuildparity command. If the subdisk(s) form part of a plex that is mirrored with other plexes, the plex will require restarting and will sync once restarted. Moving more than one subdisk in a RAID-5 plex or subdisks from both sides of a mirrored plex volume will destroy data. Note that parity rebuilds and syncing must be started manually after a move. .It Ic printconfig Write a copy of the current configuration to standard output. .It Ic quit Exit .Nm when running in interactive mode. Normally this would be done by entering the EOF character. .It Ic raid5 Oo Fl fv Oc Oo Fl s Ar stripesize Oc Oo Fl n Ar name Oc Ar drives Create a RAID-5 volume from the specified drives. If no name is specified,a unique name will be set by -.Ic gvinum. +.Ic gvinum. This organization requires at least three drives. .It Ic rename Oo Fl r Oc Ar drive | subdisk | plex | volume newname Change the name of the specified object. The .Fl r flag will recursively rename subordinate objects. .Pp Note that device nodes will not be renamed until .Nm is restarted. .It Ic rebuildparity Oo Fl f Oc Ar plex Rebuild the parity blocks of a RAID-5 plex. The parity rebuild will start at the beginning of the plex if the .Fl f flag is specified, or otherwise at the location of the parity check pointer. All subdisks in the plex must be up for a parity check. .It Ic resetconfig Reset the complete .Nm configuration. .It Ic rm Oo Fl r Oc Ar volume | plex | subdisk Remove an object and, if .Fl r is specified, its subordinate objects. .It Ic saveconfig Save .Nm configuration to disk after configuration failures. .It Ic setstate Oo Fl f Oc Ar state volume | plex | subdisk | drive Set state without influencing other objects, for diagnostic purposes only. The .Fl f flag forces state changes regardless of whether they are legal. .It Ic start Read configuration from all vinum drives. .It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk Allow the system to access the objects. If necessary, plexes will be synced and rebuilt. If a subdisk was added to a running RAID-5 or striped plex, gvinum will expand into this subdisk and grow the whole RAID-5 array. This can be done without unmounting your filesystem. The .Fl S flag is currently ignored. .It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk Terminate access to the objects, or stop .Nm if no parameters are specified. .It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives Create a striped volume from the specified drives. If no name is specified, a unique name will be set by Ic gvinum. This organization requires at least two drives. .El .Sh DESCRIPTION The .Nm utility communicates with the kernel component of the GVinum logical volume manager. It is designed either for interactive use, when started without command line arguments, or to execute a single command if the command is supplied on the command line. In interactive mode, .Nm maintains a command line history. .Sh OPTIONS The .Nm commands may be followed by an option. .Bl -tag -width indent .It Fl f The .Fl f .Pq Dq force option overrides safety checks. It should be used with extreme caution. This option is required in order to use the .Ic move command. .It Fl r The .Fl r .Pq Dq recursive option applies the command recursively to subordinate objects. For example, in conjunction with the .Ic lv command, the .Fl r option will also show information about the plexes and subdisks belonging to the volume. It is also used by the .Ic rename command to indicate that subordinate objects such as subdisks should be renamed to match the object(s) specified and by the .Ic rm command to delete plexes belonging to a volume and so on. .It Fl v The .Fl v .Pq Dq verbose option provides more detailed output. .It Fl V The .Fl V .Pq Dq "very verbose" option provides even more detailed output than .Fl v . .El .Sh ENVIRONMENT .Bl -tag -width ".Ev EDITOR" .It Ev EDITOR The name of the editor to use for editing configuration files, by default .Xr vi 1 is invoked. .El .Sh FILES .Bl -tag -width ".Pa /dev/gvinum/plex" .It Pa /dev/gvinum directory with device nodes for .Nm objects .El .Sh EXAMPLES To create a mirror on disks /dev/ad1 and /dev/ad2, create a filesystem, mount, unmount and then stop Ic gvinum: .Pp .Dl "gvinum mirror /dev/ad1 /dev/ad2" .Dl "newfs /dev/gvinum/gvinumvolume0" -.Dl "mount /dev/gvinum/gvinumvolume0 /mnt" +.Dl "mount /dev/gvinum/gvinumvolume0 /mnt" .Dl "..." .Dl "unmount /mnt" .Dl "gvinum stop" .Pp To create a striped mirror on disks /dev/ad1 /dev/ad2 /dev/ad3 and /dev/ad4 named "data" and create a filesystem: .Pp .Dl "gvinum mirror -s -n data /dev/ad1 /dev/ad2 /dev/ad3 /dev/ad4" .Dl "newfs /dev/gvinum/data" .Pp To create a raid5 array on disks /dev/ad1 /dev/ad2 and /dev/ad3, with stripesize 493k you can use the raid5 command: .Pp .Dl "gvinum raid5 -s 493k /dev/ad1 /dev/ad2 /dev/ad3" .Pp Then the volume will be created automatically. Afterwards, you have to initialize the volume: .Pp .Dl "gvinum start myraid5vol" .Pp The initialization will start, and the states will be updated when it's finished. The list command will give you information about its progress. .Pp Imagine that one of the drives fails, and the output of 'printconfig' looks something like this: .Pp .Dl "drive gvinumdrive1 device /dev/ad2" .Dl "drive gvinumdrive2 device /dev/???" .Dl "drive gvinumdrive0 device /dev/ad1" .Dl "volume myraid5vol" .Dl "plex name myraid5vol.p0 org raid5 986s vol myraid5vol" .Dl "sd name myraid5vol.p0.s2 drive gvinumdrive2 len 32538s driveoffset 265s" .Dl "plex myraid5vol.p0 plexoffset 1972s" .Dl "sd name myraid5vol.p0.s1 drive gvinumdrive1 len 32538s driveoffset 265s" .Dl "plex myraid5vol.p0 plexoffset 986s" .Dl "sd name myraid5vol.p0.s0 drive gvinumdrive0 len 32538s driveoffset 265s" .Dl "plex myraid5vol.p0 plexoffset 0s" .Pp Create a new drive with this configuration: .Pp .Dl "drive gdrive4 device /dev/ad4" .Pp Then move the stale subdisk to the new drive: .Pp .Dl "gvinum move gdrive4 myraid5vol.p0.s2" .Pp Then, initiate the rebuild: .Pp .Dl "gvinum start myraid5vol.p0" .Pp The plex will go up form degraded mode after the rebuild is finished. The plex can still be used while the rebuild is in progress, although requests might be delayed. .Pp Given the configuration as in the previous example, growing a RAID-5 or STRIPED array is accomplished by using the grow command: .Pp .Dl "gvinum grow myraid5vol.p0 /dev/ad4" .Pp If everything went ok, the plex state should now be set to growable. You can then start the growing with the .Ic start command: .Pp .Dl "gvinum start myraid5vol.p0" .Pp As with rebuilding, you can watch the progress using the .Ic list command. .Pp For a more advanced usage and detailed explanation of gvinum, the handbook is recommended. .Pp .Sh SEE ALSO .Xr geom 4 , .Xr geom 8 .Sh HISTORY The .Nm utility first appeared in .Fx 5.3 . The .Nm vinum utility, on which .Nm is based, was written by .An "Greg Lehey" . .Pp The .Nm utility was written by .An "Lukas Ertl" . The .Ic move and .Ic rename commands and documentation were added by .An "Chris Jones" through the 2005 Google Summer of Code program. .Ic a partial rewrite of gvinum was done by "Lukas Ertl" and "Ulf Lilleengen" through the 2007 Google Summer of Code program. The documentation have been updated to reflect the new functionality. .Sh AUTHORS .An Lukas Ertl Aq le@FreeBSD.org .An Chris Jones Aq soc-cjones@FreeBSD.org .An Ulf Lilleengen Aq lulf@FreeBSD.org .Sh BUGS Currently, .Nm does not rename devices in .Pa /dev/gvinum until reloaded. .Pp The .Fl S initsize flag to .Ic start is ignored. .Pp Moving subdisks that are not part of a mirrored or RAID-5 volume will destroy data. It is perhaps a bug to permit this. .Pp Plexes in which subdisks have been moved do not automatically sync or rebuild parity. This may leave data unprotected and is perhaps unwise. .Pp Currently, .Nm does not yet fully implement all of the functions found in .Xr vinum 4 . Specifically, the following commands from .Xr vinum 4 are not supported: .Bl -tag -width indent .It Ic debug Cause the volume manager to enter the kernel debugger. .It Ic debug Ar flags Set debugging flags. .It Ic dumpconfig Op Ar drive ... List the configuration information stored on the specified drives, or all drives in the system if no drive names are specified. .It Ic info Op Fl vV List information about volume manager state. .It Ic label Ar volume Create a volume label. .It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk Reset statistics counters for the specified objects, or for all objects if none are specified. .It Ic setdaemon Op Ar value Set daemon configuration. .El Index: stable/9/sbin/gvinum =================================================================== --- stable/9/sbin/gvinum (revision 237215) +++ stable/9/sbin/gvinum (revision 237216) Property changes on: stable/9/sbin/gvinum ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin/gvinum:r233648 Index: stable/9/sbin/ifconfig/ifconfig.8 =================================================================== --- stable/9/sbin/ifconfig/ifconfig.8 (revision 237215) +++ stable/9/sbin/ifconfig/ifconfig.8 (revision 237216) @@ -1,2640 +1,2640 @@ .\" 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. .\" 4. 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. .\" .\" From: @(#)ifconfig.8 8.3 (Berkeley) 1/5/94 .\" $FreeBSD$ .\" .Dd March 7, 2012 .Dt IFCONFIG 8 .Os .Sh NAME .Nm ifconfig .Nd configure network interface parameters .Sh SYNOPSIS .Nm .Op Fl L .Op Fl k .Op Fl m .Op Fl n .Ar interface .Op Cm create .Ar address_family .Oo .Ar address .Op Ar dest_address .Oc .Op Ar parameters .Nm .Ar interface .Cm destroy .Nm .Fl a .Op Fl L .Op Fl d .Op Fl m .Op Fl u .Op Fl v .Op Ar address_family .Nm .Fl l .Op Fl d .Op Fl u .Op Ar address_family .Nm .Op Fl L .Op Fl d .Op Fl k .Op Fl m .Op Fl u .Op Fl v .Op Fl C .Nm .Op Fl g Ar groupname .Sh DESCRIPTION The .Nm utility is used to assign an address to a network interface and/or configure network interface parameters. The .Nm utility must be used at boot time to define the network address of each interface present on a machine; it may also be used at a later time to redefine an interface's address or other operating parameters. .Pp The following options are available: .Bl -tag -width indent .It Ar address For the .Tn DARPA Ns -Internet family, the address is either a host name present in the host name data base, .Xr hosts 5 , or a .Tn DARPA Internet address expressed in the Internet standard .Dq dot notation . .Pp It is also possible to use the CIDR notation (also known as the slash notation) to include the netmask. That is, one can specify an address like .Li 192.168.0.1/16 . .Pp For the .Dq inet6 family, it is also possible to specify the prefix length using the slash notation, like .Li ::1/128 . See the .Cm prefixlen parameter below for more information. .\" For the Xerox Network Systems(tm) family, .\" addresses are .\" .Ar net:a.b.c.d.e.f , .\" where .\" .Ar net .\" is the assigned network number (in decimal), .\" and each of the six bytes of the host number, .\" .Ar a .\" through .\" .Ar f , .\" are specified in hexadecimal. .\" The host number may be omitted on IEEE 802 protocol .\" (Ethernet, FDDI, and Token Ring) interfaces, .\" which use the hardware physical address, .\" and on interfaces other than the first. .\" For the .\" .Tn ISO .\" family, addresses are specified as a long hexadecimal string, .\" as in the Xerox family. .\" However, two consecutive dots imply a zero .\" byte, and the dots are optional, if the user wishes to (carefully) .\" count out long strings of digits in network byte order. .Pp The link-level .Pq Dq link address is specified as a series of colon-separated hex digits. This can be used to e.g.\& set a new MAC address on an ethernet interface, though the mechanism used is not ethernet-specific. If the interface is already up when this option is used, it will be briefly brought down and then brought back up again in order to ensure that the receive filter in the underlying ethernet hardware is properly reprogrammed. .It Ar address_family Specify the address family which affects interpretation of the remaining parameters. Since an interface can receive transmissions in differing protocols with different naming schemes, specifying the address family is recommended. The address or protocol families currently supported are .Dq inet , .Dq inet6 , .Dq atalk , .Dq ipx , .\" .Dq iso , and .Dq link . .\" and .\" .Dq ns . The default if available is .Dq inet or otherwise .Dq link . .Dq ether and .Dq lladdr are synonyms for .Dq link . .It Ar dest_address Specify the address of the correspondent on the other end of a point to point link. .It Ar interface This parameter is a string of the form .Dq name unit , for example, .Dq Li ed0 . .It Ar groupname List the interfaces in the given group. .El .Pp The following parameters may be set with .Nm : .Bl -tag -width indent .It Cm add Another name for the .Cm alias parameter. Introduced for compatibility with .Bsx . .It Cm alias Establish an additional network address for this interface. This is sometimes useful when changing network numbers, and one wishes to accept packets addressed to the old interface. If the address is on the same subnet as the first network address for this interface, a non-conflicting netmask must be given. Usually .Li 0xffffffff is most appropriate. .It Fl alias Remove the network address specified. This would be used if you incorrectly specified an alias, or it was no longer needed. If you have incorrectly set an NS address having the side effect of specifying the host portion, removing all NS addresses will allow you to respecify the host portion. .It Cm anycast (Inet6 only.) Specify that the address configured is an anycast address. Based on the current specification, only routers may configure anycast addresses. Anycast address will not be used as source address of any of outgoing IPv6 packets. .It Cm arp Enable the use of the Address Resolution Protocol .Pq Xr arp 4 in mapping between network level addresses and link level addresses (default). This is currently implemented for mapping between .Tn DARPA Internet addresses and .Tn IEEE 802 48-bit MAC addresses (Ethernet, FDDI, and Token Ring addresses). .It Fl arp Disable the use of the Address Resolution Protocol .Pq Xr arp 4 . .It Cm staticarp If the Address Resolution Protocol is enabled, the host will only reply to requests for its addresses, and will never send any requests. .It Fl staticarp If the Address Resolution Protocol is enabled, the host will perform normally, sending out requests and listening for replies. .It Cm broadcast (Inet only.) Specify the address to use to represent broadcasts to the network. The default broadcast address is the address with a host part of all 1's. .It Cm debug Enable driver dependent debugging code; usually, this turns on extra console error logging. .It Fl debug Disable driver dependent debugging code. .It Cm promisc Put interface into permanently promiscuous mode. .It Fl promisc Disable permanently promiscuous mode. .It Cm delete Another name for the .Fl alias parameter. .It Cm description Ar value , Cm descr Ar value Specify a description of the interface. This can be used to label interfaces in situations where they may otherwise be difficult to distinguish. .It Cm -description , Cm -descr Clear the interface description. .It Cm down Mark an interface .Dq down . When an interface is marked .Dq down , the system will not attempt to transmit messages through that interface. If possible, the interface will be reset to disable reception as well. This action does not automatically disable routes using the interface. .It Cm group Ar group-name Assign the interface to a .Dq group . Any interface can be in multiple groups. .Pp Cloned interfaces are members of their interface family group by default. For example, a PPP interface such as .Em ppp0 is a member of the PPP interface family group, .Em ppp . .\" The interface(s) the default route(s) point to are members of the .\" .Em egress .\" interface group. .It Cm -group Ar group-name Remove the interface from the given .Dq group . .It Cm eui64 (Inet6 only.) Fill interface index (lowermost 64bit of an IPv6 address) automatically. .It Cm fib Ar fib_number Specify interface FIB. A FIB .Ar fib_number is assigned to all frames or packets received on that interface. The FIB is not inherited, e.g. vlans or other sub-interfaces will use the default FIB (0) irrespective of the parent interface's FIB. The kernel needs to be tuned to support more than the default FIB using the .Va ROUTETABLES kernel configuration option, or the .Va net.fibs tunable. .It Cm ipdst This is used to specify an Internet host who is willing to receive IP packets encapsulating IPX packets bound for a remote network. An apparent point to point link is constructed, and the address specified will be taken as the IPX address and network of the destination. .It Cm maclabel Ar label If Mandatory Access Control support is enabled in the kernel, set the MAC label to .Ar label . .\" (see .\" .Xr maclabel 7 ) . .It Cm media Ar type If the driver supports the media selection system, set the media type of the interface to .Ar type . Some interfaces support the mutually exclusive use of one of several different physical media connectors. For example, a 10Mbit/s Ethernet interface might support the use of either .Tn AUI or twisted pair connectors. Setting the media type to .Cm 10base5/AUI would change the currently active connector to the AUI port. Setting it to .Cm 10baseT/UTP would activate twisted pair. Refer to the interfaces' driver specific documentation or man page for a complete list of the available types. .It Cm mediaopt Ar opts If the driver supports the media selection system, set the specified media options on the interface. The .Ar opts argument is a comma delimited list of options to apply to the interface. Refer to the interfaces' driver specific man page for a complete list of available options. .It Fl mediaopt Ar opts If the driver supports the media selection system, disable the specified media options on the interface. .It Cm mode Ar mode If the driver supports the media selection system, set the specified operating mode on the interface to .Ar mode . For IEEE 802.11 wireless interfaces that support multiple operating modes this directive is used to select between 802.11a .Pq Cm 11a , 802.11b .Pq Cm 11b , and 802.11g .Pq Cm 11g operating modes. .It Cm inst Ar minst , Cm instance Ar minst Set the media instance to .Ar minst . This is useful for devices which have multiple physical layer interfaces .Pq PHYs . .It Cm name Ar name Set the interface name to .Ar name . .It Cm rxcsum , txcsum If the driver supports user-configurable checksum offloading, enable receive (or transmit) checksum offloading on the interface. Some drivers may not be able to enable these flags independently of each other, so setting one may also set the other. The driver will offload as much checksum work as it can reliably support, the exact level of offloading varies between drivers. .It Fl rxcsum , txcsum If the driver supports user-configurable checksum offloading, disable receive (or transmit) checksum offloading on the interface. These settings may not always be independent of each other. .It Cm tso If the driver supports .Xr tcp 4 segmentation offloading, enable TSO on the interface. Some drivers may not be able to support TSO for .Xr ip 4 and .Xr ip6 4 packets, so they may enable only one of them. .It Fl tso If the driver supports .Xr tcp 4 segmentation offloading, disable TSO on the interface. It will always disable TSO for .Xr ip 4 and .Xr ip6 4 . .It Cm lro If the driver supports .Xr tcp 4 large receive offloading, enable LRO on the interface. .It Fl lro If the driver supports .Xr tcp 4 large receive offloading, disable LRO on the interface. .It Cm wol , wol_ucast , wol_mcast , wol_magic Enable Wake On Lan (WOL) support, if available. WOL is a facility whereby a machine in a low power state may be woken in response to a received packet. There are three types of packets that may wake a system: ucast (directed solely to the machine's mac address), mcast (directed to a broadcast or multicast address), or magic (unicast or multicast frames with a ``magic contents''). Not all devices support WOL, those that do indicate the mechanisms they support in their capabilities. .Cm wol is a synonym for enabling all available WOL mechanisms. To disable WOL use .Fl wol . .It Cm vlanmtu , vlanhwtag, vlanhwfilter, vlanhwcsum, vlanhwtso If the driver offers user-configurable VLAN support, enable reception of extended frames, tag processing in hardware, frame filtering in hardware, checksum offloading, or TSO on VLAN, respectively. Note that this must be issued on a physical interface associated with .Xr vlan 4 , not on a .Xr vlan 4 interface itself. .It Fl vlanmtu , vlanhwtag, vlanhwfilter, vlanhwtso If the driver offers user-configurable VLAN support, disable reception of extended frames, tag processing in hardware, frame filtering in hardware, or TSO on VLAN, respectively. .It Cm vnet Ar jail Move the interface to the .Xr jail 8 , specified by name or JID. If the jail has a virtual network stack, the interface will disappear from the current environment and become visible to the jail. .It Fl vnet Ar jail Reclaim the interface from the .Xr jail 8 , specified by name or JID. If the jail has a virtual network stack, the interface will disappear from the jail, and become visible to the current network environment. .It Cm polling Turn on .Xr polling 4 feature and disable interrupts on the interface, if driver supports this mode. .It Fl polling Turn off .Xr polling 4 feature and enable interrupt mode on the interface. .It Cm create Create the specified network pseudo-device. If the interface is given without a unit number, try to create a new device with an arbitrary unit number. If creation of an arbitrary device is successful, the new device name is printed to standard output unless the interface is renamed or destroyed in the same .Nm invocation. .It Cm destroy Destroy the specified network pseudo-device. .It Cm plumb Another name for the .Cm create parameter. Included for .Tn Solaris compatibility. .It Cm unplumb Another name for the .Cm destroy parameter. Included for .Tn Solaris compatibility. .It Cm metric Ar n Set the routing metric of the interface to .Ar n , default 0. The routing metric is used by the routing protocol .Pq Xr routed 8 . Higher metrics have the effect of making a route less favorable; metrics are counted as additional hops to the destination network or host. .It Cm mtu Ar n Set the maximum transmission unit of the interface to .Ar n , default is interface specific. The MTU is used to limit the size of packets that are transmitted on an interface. Not all interfaces support setting the MTU, and some interfaces have range restrictions. .It Cm netmask Ar mask .\" (Inet and ISO.) (Inet only.) Specify how much of the address to reserve for subdividing networks into sub-networks. The mask includes the network part of the local address and the subnet part, which is taken from the host field of the address. The mask can be specified as a single hexadecimal number with a leading .Ql 0x , with a dot-notation Internet address, or with a pseudo-network name listed in the network table .Xr networks 5 . The mask contains 1's for the bit positions in the 32-bit address which are to be used for the network and subnet parts, and 0's for the host part. The mask should contain at least the standard network portion, and the subnet field should be contiguous with the network portion. .Pp The netmask can also be specified in CIDR notation after the address. See the .Ar address option above for more information. .It Cm prefixlen Ar len (Inet6 only.) Specify that .Ar len bits are reserved for subdividing networks into sub-networks. The .Ar len must be integer, and for syntactical reason it must be between 0 to 128. It is almost always 64 under the current IPv6 assignment rule. If the parameter is omitted, 64 is used. .Pp The prefix can also be specified using the slash notation after the address. See the .Ar address option above for more information. .\" see .\" Xr eon 5 . .\" .It Cm nsellength Ar n .\" .Pf ( Tn ISO .\" only) .\" This specifies a trailing number of bytes for a received .\" .Tn NSAP .\" used for local identification, the remaining leading part of which is .\" taken to be the .\" .Tn NET .\" (Network Entity Title). .\" The default value is 1, which is conformant to US .\" .Tn GOSIP . .\" When an ISO address is set in an ifconfig command, .\" it is really the .\" .Tn NSAP .\" which is being specified. .\" For example, in .\" .Tn US GOSIP , .\" 20 hex digits should be .\" specified in the .\" .Tn ISO NSAP .\" to be assigned to the interface. .\" There is some evidence that a number different from 1 may be useful .\" for .\" .Tn AFI .\" 37 type addresses. .It Cm range Ar netrange Under appletalk, set the interface to respond to a .Ar netrange of the form .Ar startnet Ns - Ns Ar endnet . Appletalk uses this scheme instead of netmasks though .Fx implements it internally as a set of netmasks. .It Cm remove Another name for the .Fl alias parameter. Introduced for compatibility with .Bsx . .It Cm phase The argument following this specifies the version (phase) of the Appletalk network attached to the interface. Values of 1 or 2 are permitted. .Sm off .It Cm link Op Cm 0 No - Cm 2 .Sm on Enable special processing of the link level of the interface. These three options are interface specific in actual effect, however, they are in general used to select special modes of operation. An example of this is to enable SLIP compression, or to select the connector type for some Ethernet cards. Refer to the man page for the specific driver for more information. .Sm off .It Fl link Op Cm 0 No - Cm 2 .Sm on Disable special processing at the link level with the specified interface. .It Cm monitor Put the interface in monitor mode. No packets are transmitted, and received packets are discarded after .Xr bpf 4 processing. .It Fl monitor Take the interface out of monitor mode. .It Cm up Mark an interface .Dq up . This may be used to enable an interface after an .Dq Nm Cm down . It happens automatically when setting the first address on an interface. If the interface was reset when previously marked down, the hardware will be re-initialized. .El .Pp The following parameters are for ICMPv6 Neighbor Discovery Protocol. Note that the address family keyword .Dq Li inet6 is needed for them: .Bl -tag -width indent .It Cm accept_rtadv Set a flag to enable accepting ICMPv6 Router Advertisement messages. The .Xr sysctl 8 variable .Va net.inet6.ip6.accept_rtadv controls whether this flag is set by default or not. .It Cm -accept_rtadv Clear a flag .Cm accept_rtadv . .It Cm no_radr Set a flag to control whether routers from which the system accepts Router Advertisement messages will be added to the Default Router List or not. When the .Cm accept_rtadv flag is disabled, this flag has no effect. The .Xr sysctl 8 variable .Va net.inet6.ip6.no_radr controls whether this flag is set by default or not. .It Cm -no_radr Clear a flag .Cm no_radr . .It Cm auto_linklocal Set a flag to perform automatic link-local address configuration when the interface becomes available. The .Xr sysctl 8 variable .Va net.inet6.ip6.auto_linklocal controls whether this flag is set by default or not. .It Cm -auto_linklocal Clear a flag .Cm auto_linklocal . .It Cm defaultif Set the specified interface as the default route when there is no default router. .It Cm -defaultif Clear a flag .Cm defaultif . .It Cm ifdisabled Set a flag to disable all of IPv6 network communications on the specified interface. Note that if there are already configured IPv6 addresses on that interface, all of them are marked as .Dq tentative and DAD will be performed when this flag is cleared. .It Cm -ifdisabled Clear a flag .Cm ifdisabled . -When this flag is cleared and +When this flag is cleared and .Cm auto_linklocal flag is enabled, automatic configuration of a link-local address is performed. .It Cm nud Set a flag to enable Neighbor Unreachability Detection. .It Cm -nud Clear a flag .Cm nud . .It Cm prefer_source Set a flag to prefer addresses on the interface as candidates of the source address for outgoing packets. .It Cm -prefer_source Clear a flag .Cm prefer_source . .El .Pp The following parameters are specific to cloning IEEE 802.11 wireless interfaces with the .Cm create request: .Bl -tag -width indent .It Cm wlandev Ar device Use .Ar device as the parent for the cloned device. .It Cm wlanmode Ar mode Specify the operating mode for this cloned device. .Ar mode is one of .Cm sta , -.Cm ahdemo +.Cm ahdemo (or .Cm adhoc-demo ), .Cm ibss , (or .Cm adhoc ), .Cm ap , (or .Cm hostap ), .Cm wds , .Cm tdma , .Cm mesh , and .Cm monitor . The operating mode of a cloned interface cannot be changed. The .Cm tdma mode is actually implemented as an .Cm adhoc-demo interface with special properties. .It Cm wlanbssid Ar bssid The 802.11 mac address to use for the bssid. This must be specified at create time for a legacy .Cm wds device. .It Cm wlanaddr Ar address The local mac address. If this is not specified then a mac address will automatically be assigned to the cloned device. Typically this address is the same as the address of the parent device but if the .Cm bssid parameter is specified then the driver will craft a unique address for the device (if supported). .It Cm wdslegacy Mark a .Cm wds device as operating in ``legacy mode''. -Legacy +Legacy .Cm wds devices have a fixed peer relationship and do not, for example, roam if their peer stops communicating. For completeness a Dynamic WDS (DWDS) interface may marked as .Fl wdslegacy . .It Cm bssid Request a unique local mac address for the cloned device. This is only possible if the device supports multiple mac addresses. To force use of the parent's mac address use .Fl bssid . .It Cm beacons Mark the cloned interface as depending on hardware support to track received beacons. To have beacons tracked in software use .Fl beacons . -For +For .Cm hostap -mode +mode .Fl beacons can also be used to indicate no beacons should be transmitted; this can be useful when creating a WDS configuration but .Cm wds interfaces can only be created as companions to an access point. .El .Pp The following parameters are specific to IEEE 802.11 wireless interfaces cloned with a .Cm create operation: .Bl -tag -width indent .It Cm ampdu Enable sending and receiving AMPDU frames when using 802.11n (default). The 802.11n specification states a compliant station must be capable of receiving AMPDU frames but transmission is optional. Use .Fl ampdu to disable all use of AMPDU with 802.11n. For testing and/or to work around interoperability problems one can use .Cm ampdutx and .Cm ampdurx to control use of AMPDU in one direction. .It Cm ampdudensity Ar density Set the AMPDU density parameter used when operating with 802.11n. This parameter controls the inter-packet gap for AMPDU frames. The sending device normally controls this setting but a receiving station may request wider gaps. Legal values for .Ar density are 0, .25, .5, 1, 2, 4, 8, and 16 (microseconds). A value of .Cm - is treated the same as 0. .It Cm ampdulimit Ar limit Set the limit on packet size for receiving AMPDU frames when operating with 802.11n. Legal values for .Ar limit are 8192, 16384, 32768, and 65536 but one can also specify just the unique prefix: 8, 16, 32, 64. Note the sender may limit the size of AMPDU frames to be less than the maximum specified by the receiving station. .It Cm amsdu Enable sending and receiving AMSDU frames when using 802.11n. By default AMSDU is received but not transmitted. Use .Fl amsdu to disable all use of AMSDU with 802.11n. For testing and/or to work around interoperability problems one can use .Cm amsdutx and .Cm amsdurx to control use of AMSDU in one direction. .It Cm amsdulimit Ar limit Set the limit on packet size for sending and receiving AMSDU frames when operating with 802.11n. Legal values for .Ar limit are 7935 and 3839 (bytes). Note the sender may limit the size of AMSDU frames to be less than the maximum specified by the receiving station. Note also that devices are not required to support the 7935 limit, only 3839 is required by the specification and the larger value may require more memory to be dedicated to support functionality that is rarely used. .It Cm apbridge When operating as an access point, pass packets between wireless clients directly (default). To instead let them pass up through the system and be forwarded using some other mechanism, use .Fl apbridge . Disabling the internal bridging is useful when traffic is to be processed with packet filtering. .It Cm authmode Ar mode Set the desired authentication mode in infrastructure mode. Not all adapters support all modes. The set of valid modes is .Cm none , open , shared (shared key), .Cm 8021x (IEEE 802.1x), and .Cm wpa (IEEE WPA/WPA2/802.11i). The .Cm 8021x and .Cm wpa modes are only useful when using an authentication service (a supplicant for client operation or an authenticator when operating as an access point). Modes are case insensitive. .It Cm bgscan Enable background scanning when operating as a station. Background scanning is a technique whereby a station associated to an access point will temporarily leave the channel to scan for neighboring stations. This allows a station to maintain a cache of nearby access points so that roaming between access points can be done without a lengthy scan operation. Background scanning is done only when a station is not busy and any outbound traffic will cancel a scan operation. Background scanning should never cause packets to be lost though there may be some small latency if outbound traffic interrupts a scan operation. By default background scanning is enabled if the device is capable. To disable background scanning, use .Fl bgscan . Background scanning is controlled by the .Cm bgscanidle and .Cm bgscanintvl parameters. Background scanning must be enabled for roaming; this is an artifact of the current implementation and may not be required in the future. .It Cm bgscanidle Ar idletime Set the minimum time a station must be idle (not transmitting or receiving frames) before a background scan is initiated. The .Ar idletime parameter is specified in milliseconds. By default a station must be idle at least 250 milliseconds before a background scan is initiated. The idle time may not be set to less than 100 milliseconds. .It Cm bgscanintvl Ar interval Set the interval at which background scanning is attempted. The .Ar interval parameter is specified in seconds. By default a background scan is considered every 300 seconds (5 minutes). -The +The .Ar interval may not be set to less than 15 seconds. .It Cm bintval Ar interval Set the interval at which beacon frames are sent when operating in ad-hoc or ap mode. The .Ar interval parameter is specified in TU's (1024 usecs). By default beacon frames are transmitted every 100 TU's. .It Cm bmissthreshold Ar count Set the number of consecutive missed beacons at which the station will attempt to roam (i.e., search for a new access point). The .Ar count parameter must be in the range 1 to 255; though the upper bound may be reduced according to device capabilities. The default threshold is 7 consecutive missed beacons; but this may be overridden by the device driver. Another name for the .Cm bmissthreshold parameter is .Cm bmiss . .It Cm bssid Ar address Specify the MAC address of the access point to use when operating as a station in a BSS network. This overrides any automatic selection done by the system. To disable a previously selected access point, supply .Cm any , none , or .Cm - for the address. This option is useful when more than one access point uses the same SSID. Another name for the .Cm bssid parameter is .Cm ap . .It Cm burst Enable packet bursting. Packet bursting is a transmission technique whereby the wireless medium is acquired once to send multiple frames and the interframe spacing is reduced. This technique can significantly increase throughput by reducing transmission overhead. Packet bursting is supported by the 802.11e QoS specification and some devices that do not support QoS may still be capable. By default packet bursting is enabled if a device is capable of doing it. To disable packet bursting, use .Fl burst . .It Cm chanlist Ar channels Set the desired channels to use when scanning for access points, neighbors in an IBSS network, or looking for unoccupied channels when operating as an access point. The set of channels is specified as a comma-separated list with each element in the list representing either a single channel number or a range of the form .Dq Li a-b . Channel numbers must be in the range 1 to 255 and be permissible according to the operating characteristics of the device. .It Cm channel Ar number Set a single desired channel. Channels range from 1 to 255, but the exact selection available depends on the region your adaptor was manufactured for. Setting the channel to .Li any , or .Cm - will clear any desired channel and, if the device is marked up, force a scan for a channel to operate on. Alternatively the frequency, in megahertz, may be specified instead of the channel number. .Pp When there are several ways to use a channel the channel number/frequency may be appended with attributes to clarify. For example, if a device is capable of operating on channel 6 with 802.11n and 802.11g then one can specify that g-only use should be used by specifying ``6:g''. Similarly the channel width can be specified by appending it with ``/''; e.g. ``6/40'' specifies a 40MHz wide channel, These attributes can be combined as in: ``6:ht/40''. The full set of flags specified following a ``:'' are: .Cm a (802.11a), .Cm b (802.11b), .Cm d (Atheros Dynamic Turbo mode), .Cm g (802.11g), .Cm h or .Cm n (802.11n aka HT), .Cm s (Atheros Static Turbo mode), and .Cm t (Atheros Dynamic Turbo mode, or appended to ``st'' and ``dt''). The full set of channel widths following a '/' are: -.Cm 5 +.Cm 5 (5MHz aka quarter-rate channel), -.Cm 10 +.Cm 10 (10MHz aka half-rate channel), -.Cm 20 +.Cm 20 (20MHz mostly for use in specifying ht20), and -.Cm 40 +.Cm 40 (40MHz mostly for use in specifying ht40). In addition, a 40MHz HT channel specification may include the location of the extension channel by appending ``+'' or ``-'' for above and below, -respectively; e.g. ``2437:ht/40+'' specifies 40MHz wide HT operation +respectively; e.g. ``2437:ht/40+'' specifies 40MHz wide HT operation with the center channel at frequency 2437 and the extension channel above. .It Cm country Ar name Set the country code to use in calculating the regulatory constraints for operation. In particular the set of available channels, how the wireless device will operation on the channels, and the maximum transmit power that can be used on a channel are defined by this setting. Country/Region codes are specified as a 2-character abbreviation defined by ISO 3166 or using a longer, but possibly ambiguous, spelling; e.g. "ES" and "Spain". The set of country codes are taken from /etc/regdomain.xml and can also be viewed with the ``list countries'' request. Note that not all devices support changing the country code from a default setting; typically stored in EEPROM. See also .Cm regdomain , .Cm indoor , .Cm outdoor , and .Cm anywhere . .It Cm dfs Enable Dynamic Frequency Selection (DFS) as specified in 802.11h. DFS embodies several facilities including detection of overlapping radar signals, dynamic transmit power control, and channel selection according to a least-congested criteria. DFS support is mandatory for some 5GHz frequencies in certain locales (e.g. ETSI). By default DFS is enabled according to the regulatory definitions specified in /etc/regdomain.xml and the current country code, regdomain, and channel. Note the underlying device (and driver) must support radar detection for full DFS support to work. To be fully compliant with the local regulatory agency frequencies that require DFS should not be used unless it is fully supported. Use .Fl dfs to disable this functionality for testing. .It Cm dotd Enable support for the 802.11d specification (default). When this support is enabled in station mode, beacon frames that advertise a country code different than the currently configured country code will cause an event to be dispatched to user applications. This event can be used by the station to adopt that country code and operate according to the associated regulatory constraints. When operating as an access point with 802.11d enabled the beacon and probe response frames transmitted will advertise the current regulatory domain settings. To disable 802.11d use .Fl dotd . .It Cm doth Enable 802.11h support including spectrum management. When 802.11h is enabled beacon and probe response frames will have the SpectrumMgt bit set in the capabilities field and country and power constraint information elements will be present. 802.11h support also includes handling Channel Switch Announcements (CSA) which are a mechanism to coordinate channel changes by an access point. By default 802.11h is enabled if the device is capable. To disable 802.11h use .Fl doth . .It Cm deftxkey Ar index Set the default key to use for transmission. Typically this is only set when using WEP encryption. Note that you must set a default transmit key for the system to know which key to use in encrypting outbound traffic. The .Cm weptxkey is an alias for this request; it is provided for backwards compatibility. .It Cm dtimperiod Ar period Set the DTIM period for transmitting buffered multicast data frames when operating in ap mode. The .Ar period specifies the number of beacon intervals between DTIM and must be in the range 1 to 15. By default DTIM is 1 (i.e., DTIM occurs at each beacon). .It Cm dturbo Enable the use of Atheros Dynamic Turbo mode when communicating with another Dynamic Turbo-capable station. Dynamic Turbo mode is an Atheros-specific mechanism by which stations switch between normal 802.11 operation and a ``boosted'' mode in which a 40MHz wide channel is used for communication. Stations using Dynamic Turbo mode operate boosted only when the channel is free of non-dturbo stations; when a non-dturbo station is identified on the channel all stations will automatically drop back to normal operation. By default, Dynamic Turbo mode is not enabled, even if the device is capable. Note that turbo mode (dynamic or static) is only allowed on some channels depending on the regulatory constraints; use the .Cm list chan command to identify the channels where turbo mode may be used. To disable Dynamic Turbo mode use .Fl dturbo . .It Cm dwds Enable Dynamic WDS (DWDS) support. DWDS is a facility by which 4-address traffic can be carried between stations operating in infrastructure mode. A station first associates to an access point and authenticates using normal procedures (e.g. WPA). Then 4-address frames are passed to carry traffic for stations operating on either side of the wireless link. DWDS extends the normal WDS mechanism by leveraging existing security protocols and eliminating static binding. .Pp When DWDS is enabled on an access point 4-address frames received from an authorized station will generate a ``DWDS discovery'' event to user applications. This event should be used to create a WDS interface that is bound to the remote station (and usually plumbed into a bridge). Once the WDS interface is up and running 4-address traffic then logically flows through that interface. .Pp When DWDS is enabled on a station, traffic with a destination address different from the peer station are encapsulated in a 4-address frame and transmitted to the peer. All 4-address traffic uses the security information of the stations (e.g. cryptographic keys). A station is associated using 802.11n facilities may transport 4-address traffic using these same mechanisms; this depends on available resources and capabilities of the device. The DWDS implementation guards against layer 2 routing loops of multicast traffic. .It Cm ff Enable the use of Atheros Fast Frames when communicating with another Fast Frames-capable station. Fast Frames are an encapsulation technique by which two 802.3 frames are transmitted in a single 802.11 frame. This can noticeably improve throughput but requires that the receiving station understand how to decapsulate the frame. Fast frame use is negotiated using the Atheros 802.11 vendor-specific protocol extension so enabling use is safe when communicating with non-Atheros devices. By default, use of fast frames is enabled if the device is capable. To explicitly disable fast frames, use .Fl ff . .It Cm fragthreshold Ar length Set the threshold for which transmitted frames are broken into fragments. The .Ar length argument is the frame size in bytes and must be in the range 256 to 2346. Setting .Ar length to .Li 2346 , .Cm any , or .Cm - disables transmit fragmentation. Not all adapters honor the fragmentation threshold. .It Cm hidessid When operating as an access point, do not broadcast the SSID in beacon frames or respond to probe request frames unless they are directed to the ap (i.e., they include the ap's SSID). By default, the SSID is included in beacon frames and undirected probe request frames are answered. To re-enable the broadcast of the SSID etc., use .Fl hidessid . .It Cm ht Enable use of High Throughput (HT) when using 802.11n (default). The 802.11n specification includes mechanisms for operation on 20MHz and 40MHz wide channels using different signalling mechanisms than specified in 802.11b, 802.11g, and 802.11a. Stations negotiate use of these facilities, termed HT20 and HT40, when they associate. To disable all use of 802.11n use .Fl ht . To disable use of HT20 (e.g. to force only HT40 use) use .Fl ht20 . To disable use of HT40 use .Fl ht40 . .Pp HT configuration is used to ``auto promote'' operation when several choices are available. For example, if a station associates to an 11n-capable access point it controls whether the station uses legacy operation, HT20, or HT40. When an 11n-capable device is setup as an access point and Auto Channel Selection is used to locate a channel to operate on, HT configuration controls whether legacy, HT20, or HT40 operation is setup on the selected channel. If a fixed channel is specified for a station then HT configuration can be given as part of the channel specification; e.g. 6:ht/20 to setup HT20 operation on channel 6. .It Cm htcompat Enable use of compatibility support for pre-802.11n devices (default). The 802.11n protocol specification went through several incompatible iterations. Some vendors implemented 11n support to older specifications that will not interoperate with a purely 11n-compliant station. In particular the information elements included in management frames for old devices are different. When compatibility support is enabled both standard and compatible data will be provided. Stations that associate using the compatibility mechanisms are flagged in ``list sta''. To disable compatibility support use .Fl htcompat . .It Cm htprotmode Ar technique For interfaces operating in 802.11n, use the specified .Ar technique for protecting HT frames in a mixed legacy/HT network. The set of valid techniques is .Cm off , and .Cm rts (RTS/CTS, default). Technique names are case insensitive. .It Cm inact Enable inactivity processing for stations associated to an access point (default). When operating as an access point the 802.11 layer monitors the activity of each associated station. When a station is inactive for 5 minutes it will send several ``probe frames'' to see if the station is still present. If no response is received then the station is deauthenticated. Applications that prefer to handle this work can disable this facility by using .Fl inact . .It Cm indoor Set the location to use in calculating regulatory constraints. The location is also advertised in beacon and probe response frames when 802.11d is enabled with .Cm dotd . See also .Cm outdoor , .Cm anywhere , .Cm country , and .Cm regdomain . .It Cm list active Display the list of channels available for use taking into account any restrictions set with the .Cm chanlist directive. See the description of .Cm list chan for more information. .It Cm list caps Display the adaptor's capabilities, including the operating modes supported. .It Cm list chan Display the list of channels available for use. Channels are shown with their IEEE channel number, equivalent frequency, and usage modes. Channels identified as .Ql 11g are also usable in .Ql 11b mode. Channels identified as .Ql 11a Turbo may be used only for Atheros' Static Turbo mode (specified with . Cm mediaopt turbo ) . Channels marked with a .Ql * have a regulatory constraint that they be passively scanned. This means a station is not permitted to transmit on the channel until it identifies the channel is being used for 802.11 communication; typically by hearing a beacon frame from an access point operating on the channel. .Cm list freq is another way of requesting this information. By default a compacted list of channels is displayed; if the .Fl v option is specified then all channels are shown. .It Cm list countries Display the set of country codes and regulatory domains that can be used in regulatory configuration. .It Cm list mac Display the current MAC Access Control List state. Each address is prefixed with a character that indicates the current policy applied to it: .Ql + indicates the address is allowed access, .Ql - indicates the address is denied access, .Ql * indicates the address is present but the current policy open (so the ACL is not consulted). .It Cm list mesh Displays the mesh routing table, used for forwarding packets on a mesh network. .It Cm list regdomain Display the current regulatory settings including the available channels and transmit power caps. .It Cm list roam Display the parameters that govern roaming operation. .It Cm list txparam Display the parameters that govern transmit operation. .It Cm list txpower Display the transmit power caps for each channel. .It Cm list scan Display the access points and/or ad-hoc neighbors located in the vicinity. This information may be updated automatically by the adapter with a .Cm scan request or through background scanning. Depending on the capabilities of the stations the following flags can be included in the output: .Bl -tag -width 3n .It Li A Authorized. Indicates that the station is permitted to send/receive data frames. .It Li E Extended Rate Phy (ERP). Indicates that the station is operating in an 802.11g network using extended transmit rates. .It Li H High Throughput (HT). Indicates that the station is using HT transmit rates. If a `+' follows immediately after then the station associated using deprecated mechanisms supported only when .Cm htcompat is enabled. .It Li P Power Save. Indicates that the station is operating in power save mode. .It Li Q Quality of Service (QoS). Indicates that the station is using QoS encapsulation for data frame. QoS encapsulation is enabled only when WME mode is enabled. .It Li S Short Preamble. Indicates that the station is doing short preamble to optionally improve throughput performance with 802.11g and 802.11b. .It Li T Transitional Security Network (TSN). Indicates that the station associated using TSN; see also .Cm tsn below. .It Li W Wi-Fi Protected Setup (WPS). Indicates that the station associated using WPS. .El .Pp By default interesting information elements captured from the neighboring stations are displayed at the end of each row. Possible elements include: .Cm WME (station supports WME), .Cm WPA (station supports WPA), .Cm WPS (station supports WPS), .Cm RSN (station supports 802.11i/RSN), .Cm HTCAP (station supports 802.11n/HT communication), .Cm ATH (station supports Atheros protocol extensions), .Cm VEN (station supports unknown vendor-specific extensions). If the .Fl v flag is used all the information elements and their contents will be shown. Specifying the .Fl v flag also enables display of long SSIDs. The .Cm list ap command is another way of requesting this information. .It Cm list sta When operating as an access point display the stations that are currently associated. When operating in ad-hoc mode display stations identified as neighbors in the IBSS. When operating in mesh mode display stations identified as neighbors in the MBSS. When operating in station mode display the access point. Capabilities advertised by the stations are described under the .Cm scan request. Depending on the capabilities of the stations the following flags can be included in the output: .Bl -tag -width 3n .It Li A Authorized. Indicates that the station is permitted to send/receive data frames. .It Li E Extended Rate Phy (ERP). Indicates that the station is operating in an 802.11g network using extended transmit rates. .It Li H High Throughput (HT). Indicates that the station is using HT transmit rates. If a `+' follows immediately after then the station associated using deprecated mechanisms supported only when .Cm htcompat is enabled. .It Li P Power Save. Indicates that the station is operating in power save mode. .It Li Q Quality of Service (QoS). Indicates that the station is using QoS encapsulation for data frame. QoS encapsulation is enabled only when WME mode is enabled. .It Li S Short Preamble. Indicates that the station is doing short preamble to optionally improve throughput performance with 802.11g and 802.11b. .It Li T Transitional Security Network (TSN). Indicates that the station associated using TSN; see also .Cm tsn below. .It Li W Wi-Fi Protected Setup (WPS). Indicates that the station associated using WPS. .El .Pp By default information elements received from associated stations are displayed in a short form; the .Fl v flag causes this information to be displayed symbolically. .It Cm list wme Display the current channel parameters to use when operating in WME mode. If the .Fl v option is specified then both channel and BSS parameters are displayed for each AC (first channel, then BSS). When WME mode is enabled for an adaptor this information will be displayed with the regular status; this command is mostly useful for examining parameters when WME mode is disabled. See the description of the .Cm wme directive for information on the various parameters. .It Cm maxretry Ar count Set the maximum number of tries to use in sending unicast frames. The default setting is 6 but drivers may override this with a value they choose. .It Cm mcastrate Ar rate Set the rate for transmitting multicast/broadcast frames. Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s. This rate should be valid for the current operating conditions; if an invalid rate is specified drivers are free to chose an appropriate rate. .It Cm mgtrate Ar rate Set the rate for transmitting management and/or control frames. Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s. .It Cm outdoor Set the location to use in calculating regulatory constraints. The location is also advertised in beacon and probe response frames when 802.11d is enabled with .Cm dotd . See also .Cm anywhere , .Cm country , .Cm indoor , and .Cm regdomain . .It Cm powersave Enable powersave operation. When operating as a client, the station will conserve power by periodically turning off the radio and listening for messages from the access point telling it there are packets waiting. The station must then retrieve the packets. Not all devices support power save operation as a client. The 802.11 specification requires that all access points support power save but some drivers do not. Use .Fl powersave to disable powersave operation when operating as a client. .It Cm powersavesleep Ar sleep Set the desired max powersave sleep time in TU's (1024 usecs). By default the max powersave sleep time is 100 TU's. .It Cm protmode Ar technique For interfaces operating in 802.11g, use the specified .Ar technique for protecting OFDM frames in a mixed 11b/11g network. The set of valid techniques is .Cm off , cts (CTS to self), and .Cm rtscts (RTS/CTS). Technique names are case insensitive. Not all devices support .Cm cts as a protection technique. .It Cm pureg When operating as an access point in 802.11g mode allow only 11g-capable stations to associate (11b-only stations are not permitted to associate). To allow both 11g and 11b-only stations to associate, use .Fl pureg . .It Cm puren When operating as an access point in 802.11n mode allow only HT-capable stations to associate (legacy stations are not permitted to associate). To allow both HT and legacy stations to associate, use .Fl puren . .It Cm regdomain Ar sku Set the regulatory domain to use in calculating the regulatory constraints for operation. In particular the set of available channels, how the wireless device will operation on the channels, and the maximum transmit power that can be used on a channel are defined by this setting. Regdomain codes (SKU's) are taken from /etc/regdomain.xml and can also be viewed with the ``list countries'' request. Note that not all devices support changing the regdomain from a default setting; typically stored in EEPROM. See also .Cm country , .Cm indoor , .Cm outdoor , and .Cm anywhere . .It Cm rifs Enable use of Reduced InterFrame Spacing (RIFS) when operating in 802.11n on an HT channel. Note that RIFS must be supported by both the station and access point for it to be used. To disable RIFS use .Fl rifs . .It Cm roam:rate Ar rate Set the threshold for controlling roaming when operating in a BSS. The .Ar rate parameter specifies the transmit rate in megabits at which roaming should be considered. If the current transmit rate drops below this setting and background scanning is enabled, then the system will check if a more desirable access point is available and switch over to it. The current scan cache contents are used if they are considered valid according to the .Cm scanvalid parameter; otherwise a background scan operation is triggered before any selection occurs. Each channel type has a separate rate threshold; the default values are: 12 Mb/s (11a), 2 Mb/s (11b), 2 Mb/s (11g), MCS 1 (11na, 11ng). .It Cm roam:rssi Ar rssi Set the threshold for controlling roaming when operating in a BSS. The .Ar rssi parameter specifies the receive signal strength in dBm units at which roaming should be considered. If the current rssi drops below this setting and background scanning is enabled, then the system will check if a more desirable access point is available and switch over to it. The current scan cache contents are used if they are considered valid according to the .Cm scanvalid parameter; otherwise a background scan operation is triggered before any selection occurs. Each channel type has a separate rssi threshold; the default values are all 7 dBm. .It Cm roaming Ar mode When operating as a station, control how the system will behave when communication with the current access point is broken. The .Ar mode argument may be one of .Cm device (leave it to the hardware device to decide), .Cm auto (handle either in the device or the operating system\[em]as appropriate), .Cm manual (do nothing until explicitly instructed). By default, the device is left to handle this if it is capable; otherwise, the operating system will automatically attempt to reestablish communication. Manual mode is used by applications such as .Xr wpa_supplicant 8 that want to control the selection of an access point. .It Cm rtsthreshold Ar length Set the threshold for which transmitted frames are preceded by transmission of an RTS control frame. The .Ar length argument is the frame size in bytes and must be in the range 1 to 2346. Setting .Ar length to .Li 2346 , .Cm any , or .Cm - disables transmission of RTS frames. Not all adapters support setting the RTS threshold. .It Cm scan Initiate a scan of neighboring stations, wait for it to complete, and display all stations found. Only the super-user can initiate a scan. See .Cm list scan for information on the display. By default a background scan is done; otherwise a foreground scan is done and the station may roam to a different access point. The .Cm list scan request can be used to show recent scan results without initiating a new scan. .It Cm scanvalid Ar threshold Set the maximum time the scan cache contents are considered valid; i.e. will be used without first triggering a scan operation to refresh the data. The .Ar threshold parameter is specified in seconds and defaults to 60 seconds. The minimum setting for .Ar threshold is 10 seconds. One should take care setting this threshold; if it is set too low then attempts to roam to another access point may trigger unnecessary background scan operations. .It Cm shortgi Enable use of Short Guard Interval when operating in 802.11n on an HT channel. NB: this currently enables Short GI on both HT40 and HT20 channels. To disable Short GI use .Fl shortgi . .It Cm smps Enable use of Static Spatial Multiplexing Power Save (SMPS) when operating in 802.11n. A station operating with Static SMPS maintains only a single receive chain active (this can significantly reduce power consumption). To disable SMPS use .Fl smps . .It Cm smpsdyn Enable use of Dynamic Spatial Multiplexing Power Save (SMPS) when operating in 802.11n. A station operating with Dynamic SMPS maintains only a single receive chain active but switches to multiple receive chains when it receives an RTS frame (this can significantly reduce power consumption). Note that stations cannot distinguish between RTS/CTS intended to enable multiple receive chains and those used for other purposes. To disable SMPS use .Fl smps . .It Cm ssid Ar ssid Set the desired Service Set Identifier (aka network name). The SSID is a string up to 32 characters in length and may be specified as either a normal string or in hexadecimal when preceded by .Ql 0x . Additionally, the SSID may be cleared by setting it to .Ql - . .It Cm tdmaslot Ar slot When operating with TDMA, use the specified .Ar slot configuration. The .Ar slot is a number between 0 and the maximum number of slots in the BSS. Note that a station configured as slot 0 is a master and will broadcast beacon frames advertising the BSS; stations configured to use other slots will always scan to locate a master before they ever transmit. By default .Cm tdmaslot is set to 1. .It Cm tdmaslotcnt Ar cnt When operating with TDMA, setup a BSS with .Ar cnt slots. The slot count may be at most 8. The current implementation is only tested with two stations (i.e. point to point applications). This setting is only meaningful when a station is configured as slot 0; other stations adopt this setting from the BSS they join. By default .Cm tdmaslotcnt is set to 2. .It Cm tdmaslotlen Ar len When operating with TDMA, setup a BSS such that each station has a slot .Ar len microseconds long. The slot length must be at least 150 microseconds (1/8 TU) and no more than 65 milliseconds. Note that setting too small a slot length may result in poor channel bandwidth utilization due to factors such as timer granularity and guard time. This setting is only meaningful when a station is configured as slot 0; other stations adopt this setting from the BSS they join. By default .Cm tdmaslotlen is set to 10 milliseconds. .It Cm tdmabintval Ar intval When operating with TDMA, setup a BSS such that beacons are transmitted every .Ar intval superframes to synchronize the TDMA slot timing. A superframe is defined as the number of slots times the slot length; e.g. a BSS with two slots of 10 milliseconds has a 20 millisecond superframe. The beacon interval may not be zero. A lower setting of .Cm tdmabintval causes the timers to be resynchronized more often; this can be help if significant timer drift is observed. By default .Cm tdmabintval is set to 5. .It Cm tsn When operating as an access point with WPA/802.11i allow legacy stations to associate using static key WEP and open authentication. To disallow legacy station use of WEP, use .Fl tsn . .It Cm txpower Ar power Set the power used to transmit frames. The .Ar power argument is specified in .5 dBm units. Out of range values are truncated. Typically only a few discreet power settings are available and the driver will use the setting closest to the specified value. Not all adapters support changing the transmit power. .It Cm ucastrate Ar rate Set a fixed rate for transmitting unicast frames. Rates are specified as megabits/second in decimal; e.g.\& 5.5 for 5.5 Mb/s. This rate should be valid for the current operating conditions; if an invalid rate is specified drivers are free to chose an appropriate rate. .It Cm wepmode Ar mode Set the desired WEP mode. Not all adapters support all modes. The set of valid modes is .Cm off , on , and .Cm mixed . The .Cm mixed mode explicitly tells the adaptor to allow association with access points which allow both encrypted and unencrypted traffic. On these adapters, .Cm on means that the access point must only allow encrypted connections. On other adapters, .Cm on is generally another name for .Cm mixed . Modes are case insensitive. .It Cm weptxkey Ar index Set the WEP key to be used for transmission. This is the same as setting the default transmission key with .Cm deftxkey . .It Cm wepkey Ar key Ns | Ns Ar index : Ns Ar key Set the selected WEP key. If an .Ar index is not given, key 1 is set. A WEP key will be either 5 or 13 characters (40 or 104 bits) depending on the local network and the capabilities of the adaptor. It may be specified either as a plain string or as a string of hexadecimal digits preceded by .Ql 0x . For maximum portability, hex keys are recommended; the mapping of text keys to WEP encryption is usually driver-specific. In particular, the .Tn Windows drivers do this mapping differently to .Fx . A key may be cleared by setting it to .Ql - . If WEP is supported then there are at least four keys. Some adapters support more than four keys. If that is the case, then the first four keys (1-4) will be the standard temporary keys and any others will be adaptor specific keys such as permanent keys stored in NVRAM. .Pp Note that you must set a default transmit key with .Cm deftxkey for the system to know which key to use in encrypting outbound traffic. .It Cm wme Enable Wireless Multimedia Extensions (WME) support, if available, for the specified interface. WME is a subset of the IEEE 802.11e standard to support the efficient communication of realtime and multimedia data. To disable WME support, use .Fl wme . Another name for this parameter is .Cm wmm . .Pp The following parameters are meaningful only when WME support is in use. Parameters are specified per-AC (Access Category) and split into those that are used by a station when acting as an access point and those for client stations in the BSS. The latter are received from the access point and may not be changed (at the station). The following Access Categories are recognized: .Pp .Bl -tag -width ".Cm AC_BK" -compact .It Cm AC_BE (or .Cm BE ) best effort delivery, .It Cm AC_BK (or .Cm BK ) background traffic, .It Cm AC_VI (or .Cm VI ) video traffic, .It Cm AC_VO (or .Cm VO ) voice traffic. .El .Pp AC parameters are case-insensitive. Traffic classification is done in the operating system using the vlan priority associated with data frames or the ToS (Type of Service) indication in IP-encapsulated frames. If neither information is present, traffic is assigned to the Best Effort (BE) category. .Bl -tag -width indent .It Cm ack Ar ac Set the ACK policy for QoS transmissions by the local station; this controls whether or not data frames transmitted by a station require an ACK response from the receiving station. To disable waiting for an ACK use .Fl ack . This parameter is applied only to the local station. .It Cm acm Ar ac Enable the Admission Control Mandatory (ACM) mechanism for transmissions by the local station. To disable the ACM use .Fl acm . On stations in a BSS this parameter is read-only and indicates the setting received from the access point. NB: ACM is not supported right now. .It Cm aifs Ar ac Ar count Set the Arbitration Inter Frame Spacing (AIFS) channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm cwmin Ar ac Ar count Set the CWmin channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm cwmax Ar ac Ar count Set the CWmax channel access parameter to use for transmissions by the local station. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm txoplimit Ar ac Ar limit Set the Transmission Opportunity Limit channel access parameter to use for transmissions by the local station. This parameter defines an interval of time when a WME station has the right to initiate transmissions onto the wireless medium. On stations in a BSS this parameter is read-only and indicates the setting received from the access point. .It Cm bss:aifs Ar ac Ar count Set the AIFS channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:cwmin Ar ac Ar count Set the CWmin channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:cwmax Ar ac Ar count Set the CWmax channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .It Cm bss:txoplimit Ar ac Ar limit Set the TxOpLimit channel access parameter to send to stations in a BSS. This parameter is meaningful only when operating in ap mode. .El .It Cm wps Enable Wireless Privacy Subscriber support. Note that WPS support requires a WPS-capable supplicant. To disable this function use .Fl wps . .El .Pp The following parameters support an optional access control list feature available with some adapters when operating in ap mode; see .Xr wlan_acl 4 . This facility allows an access point to accept/deny association requests based on the MAC address of the station. Note that this feature does not significantly enhance security as MAC address spoofing is easy to do. .Bl -tag -width indent .It Cm mac:add Ar address Add the specified MAC address to the database. Depending on the policy setting association requests from the specified station will be allowed or denied. .It Cm mac:allow Set the ACL policy to permit association only by stations registered in the database. .It Cm mac:del Ar address Delete the specified MAC address from the database. .It Cm mac:deny Set the ACL policy to deny association only by stations registered in the database. .It Cm mac:kick Ar address Force the specified station to be deauthenticated. This typically is done to block a station after updating the address database. .It Cm mac:open Set the ACL policy to allow all stations to associate. .It Cm mac:flush Delete all entries in the database. .It Cm mac:radius Set the ACL policy to permit association only by stations approved by a RADIUS server. Note that this feature requires the .Xr hostapd 8 program be configured to do the right thing as it handles the RADIUS processing (and marks stations as authorized). .El .Pp The following parameters are related to a wireless interface operating in mesh mode: .Bl -tag -width indent .It Cm meshid Ar meshid Set the desired Mesh Identifier. The Mesh ID is a string up to 32 characters in length. A mesh interface must have a Mesh Identifier specified to reach an operational state. .It Cm meshttl Ar ttl Set the desired ``time to live'' for mesh forwarded packets; this is the number of hops a packet may be forwarded before it is discarded. The default setting for .Cm meshttl is 31. .It Cm meshpeering Enable or disable peering with neighbor mesh stations. Stations must peer before any data packets can be exchanged. By default .Cm meshpeering is enabled. .It Cm meshforward Enable or disable forwarding packets by a mesh interface. By default .Cm meshforward is enabled. .It Cm meshmetric Ar protocol Set the specified .Ar protocol as the link metric protocol used on a mesh network. The default protocol is called .Ar AIRTIME . The mesh interface will restart after changing this setting. .It Cm meshpath Ar protocol Set the specified .Ar protocol as the path selection protocol used on a mesh network. The only available protocol at the moment is called .Ar HWMP (Hybrid Wireless Mesh Protocol). The mesh interface will restart after changing this setting. .It Cm hwmprootmode Ar mode Stations on a mesh network can operate as ``root nodes.'' Root nodes try to find paths to all mesh nodes and advertise themselves regularly. When there is a root mesh node on a network, other mesh nodes can setup paths between themselves faster because they can use the root node to find the destination. This path may not be the best, but on-demand routing will eventually find the best path. The following modes are recognized: .Pp .Bl -tag -width ".Cm PROACTIVE" -compact .It Cm DISABLED Disable root mode. .It Cm NORMAL Send broadcast path requests every two seconds. Nodes on the mesh without a path to this root mesh station with try to discover a path to us. .It Cm PROACTIVE Send broadcast path requests every two seconds and every node must reply with with a path reply even if it already has a path to this root mesh station. .It Cm RANN Send broadcast root announcement (RANN) frames. Nodes on the mesh without a path to this root mesh station with try to discover a path to us. .El By default -.Cm hwmprootmode +.Cm hwmprootmode is set to .Ar DISABLED . .It Cm hwmpmaxhops Ar cnt Set the maximum number of hops allowed in an HMWP path to .Ar cnt . The default setting for .Cm hwmpmaxhops is 31. .El .Pp The following parameters are for compatibility with other systems: .Bl -tag -width indent .It Cm nwid Ar ssid Another name for the .Cm ssid parameter. Included for .Nx compatibility. .It Cm stationname Ar name Set the name of this station. The station name is not part of the IEEE 802.11 protocol though some interfaces support it. As such it only seems to be meaningful to identical or virtually identical equipment. Setting the station name is identical in syntax to setting the SSID. One can also use .Cm station for .Bsx compatibility. .It Cm wep Another way of saying .Cm wepmode on . Included for .Bsx compatibility. .It Fl wep Another way of saying .Cm wepmode off . Included for .Bsx compatibility. .It Cm nwkey key Another way of saying: .Dq Li "wepmode on weptxkey 1 wepkey 1:key wepkey 2:- wepkey 3:- wepkey 4:-" . Included for .Nx compatibility. .It Cm nwkey Xo .Sm off .Ar n : k1 , k2 , k3 , k4 .Sm on .Xc Another way of saying .Dq Li "wepmode on weptxkey n wepkey 1:k1 wepkey 2:k2 wepkey 3:k3 wepkey 4:k4" . Included for .Nx compatibility. .It Fl nwkey Another way of saying .Cm wepmode off . Included for .Nx compatibility. .El .Pp The following parameters are specific to bridge interfaces: .Bl -tag -width indent .It Cm addm Ar interface Add the interface named by .Ar interface as a member of the bridge. The interface is put into promiscuous mode so that it can receive every packet sent on the network. .It Cm deletem Ar interface Remove the interface named by .Ar interface from the bridge. Promiscuous mode is disabled on the interface when it is removed from the bridge. .It Cm maxaddr Ar size Set the size of the bridge address cache to .Ar size . The default is 2000 entries. .It Cm timeout Ar seconds Set the timeout of address cache entries to .Ar seconds seconds. If .Ar seconds is zero, then address cache entries will not be expired. The default is 1200 seconds. .It Cm addr Display the addresses that have been learned by the bridge. .It Cm static Ar interface-name Ar address Add a static entry into the address cache pointing to .Ar interface-name . Static entries are never aged out of the cache or re-placed, even if the address is seen on a different interface. .It Cm deladdr Ar address Delete .Ar address from the address cache. .It Cm flush Delete all dynamically-learned addresses from the address cache. .It Cm flushall Delete all addresses, including static addresses, from the address cache. .It Cm discover Ar interface Mark an interface as a .Dq discovering interface. When the bridge has no address cache entry (either dynamic or static) for the destination address of a packet, the bridge will forward the packet to all member interfaces marked as .Dq discovering . This is the default for all interfaces added to a bridge. .It Cm -discover Ar interface Clear the .Dq discovering attribute on a member interface. For packets without the .Dq discovering attribute, the only packets forwarded on the interface are broadcast or multicast packets and packets for which the destination address is known to be on the interface's segment. .It Cm learn Ar interface Mark an interface as a .Dq learning interface. When a packet arrives on such an interface, the source address of the packet is entered into the address cache as being a destination address on the interface's segment. This is the default for all interfaces added to a bridge. .It Cm -learn Ar interface Clear the .Dq learning attribute on a member interface. .It Cm sticky Ar interface Mark an interface as a .Dq sticky interface. Dynamically learned address entries are treated at static once entered into the cache. Sticky entries are never aged out of the cache or replaced, even if the address is seen on a different interface. .It Cm -sticky Ar interface Clear the .Dq sticky attribute on a member interface. .It Cm private Ar interface Mark an interface as a .Dq private interface. A private interface does not forward any traffic to any other port that is also a private interface. .It Cm -private Ar interface Clear the .Dq private attribute on a member interface. .It Cm span Ar interface Add the interface named by .Ar interface as a span port on the bridge. Span ports transmit a copy of every frame received by the bridge. This is most useful for snooping a bridged network passively on another host connected to one of the span ports of the bridge. .It Cm -span Ar interface Delete the interface named by .Ar interface from the list of span ports of the bridge. .It Cm stp Ar interface Enable Spanning Tree protocol on .Ar interface . The .Xr if_bridge 4 driver has support for the IEEE 802.1D Spanning Tree protocol (STP). Spanning Tree is used to detect and remove loops in a network topology. .It Cm -stp Ar interface Disable Spanning Tree protocol on .Ar interface . This is the default for all interfaces added to a bridge. .It Cm edge Ar interface Set .Ar interface as an edge port. An edge port connects directly to end stations cannot create bridging loops in the network, this allows it to transition straight to forwarding. .It Cm -edge Ar interface Disable edge status on .Ar interface . .It Cm autoedge Ar interface Allow .Ar interface to automatically detect edge status. This is the default for all interfaces added to a bridge. .It Cm -autoedge Ar interface Disable automatic edge status on .Ar interface . .It Cm ptp Ar interface Set the .Ar interface as a point to point link. This is required for straight transitions to forwarding and should be enabled on a direct link to another RSTP capable switch. .It Cm -ptp Ar interface Disable point to point link status on .Ar interface . This should be disabled for a half duplex link and for an interface connected to a shared network segment, like a hub or a wireless network. .It Cm autoptp Ar interface Automatically detect the point to point status on .Ar interface by checking the full duplex link status. This is the default for interfaces added to the bridge. .It Cm -autoptp Ar interface Disable automatic point to point link detection on .Ar interface . .It Cm maxage Ar seconds Set the time that a Spanning Tree protocol configuration is valid. The default is 20 seconds. The minimum is 6 seconds and the maximum is 40 seconds. .It Cm fwddelay Ar seconds Set the time that must pass before an interface begins forwarding packets when Spanning Tree is enabled. The default is 15 seconds. The minimum is 4 seconds and the maximum is 30 seconds. .It Cm hellotime Ar seconds Set the time between broadcasting of Spanning Tree protocol configuration messages. The hello time may only be changed when operating in legacy stp mode. The default is 2 seconds. The minimum is 1 second and the maximum is 2 seconds. .It Cm priority Ar value Set the bridge priority for Spanning Tree. The default is 32768. The minimum is 0 and the maximum is 61440. .It Cm proto Ar value Set the Spanning Tree protocol. The default is rstp. The available options are stp and rstp. .It Cm holdcnt Ar value Set the transmit hold count for Spanning Tree. This is the number of packets transmitted before being rate limited. The default is 6. The minimum is 1 and the maximum is 10. .It Cm ifpriority Ar interface Ar value Set the Spanning Tree priority of .Ar interface to .Ar value . The default is 128. The minimum is 0 and the maximum is 240. .It Cm ifpathcost Ar interface Ar value Set the Spanning Tree path cost of .Ar interface to .Ar value . The default is calculated from the link speed. To change a previously selected path cost back to automatic, set the cost to 0. The minimum is 1 and the maximum is 200000000. .It Cm ifmaxaddr Ar interface Ar size Set the maximum number of hosts allowed from an interface, packets with unknown source addresses are dropped until an existing host cache entry expires or is removed. Set to 0 to disable. .El .Pp The following parameters are specific to lagg interfaces: .Bl -tag -width indent .It Cm laggport Ar interface Add the interface named by .Ar interface as a port of the aggregation interface. .It Cm -laggport Ar interface Remove the interface named by .Ar interface from the aggregation interface. .It Cm laggproto Ar proto Set the aggregation protocol. The default is failover. The available options are failover, fec, lacp, loadbalance, roundrobin and none. .It Cm lagghash Ar option Ns Oo , Ns Ar option Oc Set the packet layers to hash for aggregation protocols which load balance. The default is .Dq l2,l3,l4 . The options can be combined using commas. .Pp .Bl -tag -width ".Cm l2" -compact .It Cm l2 src/dst mac address and optional vlan number. .It Cm l3 src/dst address for IPv4 or IPv6. .It Cm l4 src/dst port for TCP/UDP/SCTP. .El .Pp .El .Pp The following parameters are specific to IP tunnel interfaces, .Xr gif 4 : .Bl -tag -width indent .It Cm tunnel Ar src_addr dest_addr Configure the physical source and destination address for IP tunnel interfaces. The arguments .Ar src_addr and .Ar dest_addr are interpreted as the outer source/destination for the encapsulating IPv4/IPv6 header. .It Fl tunnel Unconfigure the physical source and destination address for IP tunnel interfaces previously configured with .Cm tunnel . .It Cm deletetunnel Another name for the .Fl tunnel parameter. .It Cm accept_rev_ethip_ver Set a flag to accept both correct EtherIP packets and ones with reversed version field. Enabled by default. This is for backward compatibility with .Fx 6.1 , 6.2, 6.3, 7.0, and 7.1. .It Cm -accept_rev_ethip_ver Clear a flag .Cm accept_rev_ethip_ver . .It Cm send_rev_ethip_ver Set a flag to send EtherIP packets with reversed version field intentionally. Disabled by default. This is for backward compatibility with .Fx 6.1 , 6.2, 6.3, 7.0, and 7.1. .It Cm -send_rev_ethip_ver Clear a flag .Cm send_rev_ethip_ver . .El .Pp The following parameters are specific to GRE tunnel interfaces, .Xr gre 4 : .Bl -tag -width indent .It Cm grekey Ar key Configure the GRE key to be used for outgoing packets. Note that .Xr gre 4 will always accept GRE packets with invalid or absent keys. This command will result in a four byte MTU reduction on the interface. .El .Pp The following parameters are specific to .Xr pfsync 4 interfaces: .Bl -tag -width indent .It Cm maxupd Ar n Set the maximum number of updates for a single state which can be collapsed into one. This is an 8-bit number; the default value is 128. .El .Pp The following parameters are specific to .Xr vlan 4 interfaces: .Bl -tag -width indent .It Cm vlan Ar vlan_tag Set the VLAN tag value to .Ar vlan_tag . This value is a 16-bit number which is used to create an 802.1Q VLAN header for packets sent from the .Xr vlan 4 interface. Note that .Cm vlan and .Cm vlandev must both be set at the same time. .It Cm vlandev Ar iface Associate the physical interface .Ar iface with a .Xr vlan 4 interface. Packets transmitted through the .Xr vlan 4 interface will be diverted to the specified physical interface .Ar iface with 802.1Q VLAN encapsulation. Packets with 802.1Q encapsulation received by the parent interface with the correct VLAN tag will be diverted to the associated .Xr vlan 4 pseudo-interface. The .Xr vlan 4 interface is assigned a copy of the parent interface's flags and the parent's ethernet address. The .Cm vlandev and .Cm vlan must both be set at the same time. If the .Xr vlan 4 interface already has a physical interface associated with it, this command will fail. To change the association to another physical interface, the existing association must be cleared first. .Pp Note: if the hardware tagging capability is set on the parent interface, the .Xr vlan 4 pseudo interface's behavior changes: the .Xr vlan 4 interface recognizes that the parent interface supports insertion and extraction of VLAN tags on its own (usually in firmware) and that it should pass packets to and from the parent unaltered. .It Fl vlandev Op Ar iface If the driver is a .Xr vlan 4 pseudo device, disassociate the parent interface from it. This breaks the link between the .Xr vlan 4 interface and its parent, clears its VLAN tag, flags and its link address and shuts the interface down. The .Ar iface argument is useless and hence deprecated. .El .Pp The following parameters are specific to .Xr carp 4 interfaces: .Bl -tag -width indent .It Cm advbase Ar seconds Specifies the base of the advertisement interval in seconds. The acceptable values are 1 to 255. The default value is 1. .\" The default value is .\" .Dv CARP_DFLTINTV . .It Cm advskew Ar interval Specifies the skew to add to the base advertisement interval to make one host advertise slower than another host. It is specified in 1/256 of seconds. The acceptable values are 1 to 254. The default value is 0. .It Cm pass Ar phrase Set the authentication key to .Ar phrase . .It Cm vhid Ar n Set the virtual host ID. This is a required setting. Acceptable values are 1 to 255. .It Cm state Ar state Force the interface into state .Ar state . Valid states are INIT, BACKUP, and MASTER. Note that manually setting the state to INIT is ignored by .Xr carp 4 . This state is set automatically when the underlying interface is down. .El .Pp The .Nm utility displays the current configuration for a network interface when no optional parameters are supplied. If a protocol family is specified, .Nm will report only the details specific to that protocol family. .Pp If the .Fl m flag is passed before an interface name, .Nm will display the capability list and all of the supported media for the specified interface. If .Fl L flag is supplied, address lifetime is displayed for IPv6 addresses, as time offset string. .Pp Optionally, the .Fl a flag may be used instead of an interface name. This flag instructs .Nm to display information about all interfaces in the system. The .Fl d flag limits this to interfaces that are down, and .Fl u limits this to interfaces that are up. When no arguments are given, .Fl a is implied. .Pp The .Fl l flag may be used to list all available interfaces on the system, with no other additional information. Use of this flag is mutually exclusive with all other flags and commands, except for .Fl d (only list interfaces that are down) and .Fl u (only list interfaces that are up). .Pp The .Fl v flag may be used to get more verbose status for an interface. .Pp The .Fl C flag may be used to list all of the interface cloners available on the system, with no additional information. Use of this flag is mutually exclusive with all other flags and commands. .Pp The .Fl k flag causes keying information for the interface, if available, to be printed. For example, the values of 802.11 WEP keys will be printed, if accessible to the current user. This information is not printed by default, as it may be considered sensitive. -.Pp +.Pp If the network interface driver is not present in the kernel then .Nm will attempt to load it. The .Fl n flag disables this behavior. .Pp Only the super-user may modify the configuration of a network interface. .Sh NOTES The media selection system is relatively new and only some drivers support it (or have need for it). .Sh EXAMPLES Assign the IPv4 address .Li 192.0.2.10 , with a network mask of .Li 255.255.255.0 , to the interface .Li fxp0 : .Dl # ifconfig fxp0 inet 192.0.2.10 netmask 255.255.255.0 .Pp Add the IPv4 address .Li 192.0.2.45 , with the CIDR network prefix .Li /28 , to the interface .Li ed0 , using .Cm add as a synonym for the canonical form of the option .Cm alias : .Dl # ifconfig ed0 inet 192.0.2.45/28 add .Pp Remove the IPv4 address .Li 192.0.2.45 from the interface .Li ed0 : .Dl # ifconfig ed0 inet 192.0.2.45 -alias .Pp Enable IPv6 functionality of the interface: .Dl # ifconfig em0 inet6 -ifdisabled .Pp Add the IPv6 address .Li 2001:DB8:DBDB::123/48 to the interface .Li em0 : .Dl # ifconfig em0 inet6 2001:db8:bdbd::123 prefixlen 48 alias Note that lower case hexadecimal IPv6 addresses are acceptable. .Pp Remove the IPv6 address added in the above example, using the .Li / character as shorthand for the network prefix, and using .Cm delete as a synonym for the canonical form of the option .Fl alias : .Dl # ifconfig em0 inet6 2001:db8:bdbd::123/48 delete .Pp Configure the interface .Li xl0 , to use 100baseTX, full duplex Ethernet media options: .Dl # ifconfig xl0 media 100baseTX mediaopt full-duplex .Pp Label the em0 interface as an uplink: .Dl # ifconfig em0 description \&"Uplink to Gigabit Switch 2\&" .Pp Create the software network interface .Li gif1 : .Dl # ifconfig gif1 create .Pp Destroy the software network interface .Li gif1 : .Dl # ifconfig gif1 destroy .Pp Display available wireless networks using .Li wlan0 : .Dl # ifconfig wlan0 list scan .Sh DIAGNOSTICS Messages indicating the specified interface does not exist, the requested address is unknown, or the user is not privileged and tried to alter an interface's configuration. .Sh SEE ALSO .Xr netstat 1 , .Xr carp 4 , .Xr gif 4 , .Xr netintro 4 , .Xr pfsync 4 , .Xr polling 4 , .Xr vlan 4 , .\" .Xr eon 5 , .Xr rc 8 , .Xr routed 8 , .Xr jail 8 , .Xr sysctl 8 .Sh HISTORY The .Nm utility appeared in .Bx 4.2 . .Sh BUGS Basic IPv6 node operation requires a link-local address on each interface configured for IPv6. Normally, such an address is automatically configured by the kernel on each interface added to the system or enabled; this behavior may be disabled by setting per-interface flag .Cm -auto_linklocal . The default value of this flag is 1 and can be disabled by using the sysctl MIB variable .Va net.inet6.ip6.auto_linklocal . .Pp Do not configure IPv6 addresses with no link-local address by using .Nm . It can result in unexpected behaviors of the kernel. Index: stable/9/sbin/ifconfig =================================================================== --- stable/9/sbin/ifconfig (revision 237215) +++ stable/9/sbin/ifconfig (revision 237216) Property changes on: stable/9/sbin/ifconfig ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin/ifconfig:r233648 Index: stable/9/sbin/ipfw/ipfw.8 =================================================================== --- stable/9/sbin/ipfw/ipfw.8 (revision 237215) +++ stable/9/sbin/ipfw/ipfw.8 (revision 237216) @@ -1,3370 +1,3370 @@ .\" .\" $FreeBSD$ .\" .Dd March 9, 2012 .Dt IPFW 8 .Os .Sh NAME .Nm ipfw .Nd User interface for firewall, traffic shaper, packet scheduler, in-kernel NAT. .Sh SYNOPSIS .Ss FIREWALL CONFIGURATION .Nm .Op Fl cq .Cm add .Ar rule .Nm .Op Fl acdefnNStT .Op Cm set Ar N .Brq Cm list | show .Op Ar rule | first-last ... .Nm .Op Fl f | q .Op Cm set Ar N .Cm flush .Nm .Op Fl q .Op Cm set Ar N .Brq Cm delete | zero | resetlog .Op Ar number ... .Pp .Nm .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... .Nm .Cm set move .Op Cm rule .Ar number Cm to Ar number .Nm .Cm set swap Ar number number .Nm .Cm set show .Ss SYSCTL SHORTCUTS .Pp .Nm .Cm enable .Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive .Nm .Cm disable .Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive .Pp .Ss LOOKUP TABLES .Nm .Cm table Ar number Cm add Ar addr Ns Oo / Ns Ar masklen Oc Op Ar value .Nm .Cm table Ar number Cm delete Ar addr Ns Op / Ns Ar masklen .Nm .Cm table .Brq Ar number | all .Cm flush .Nm .Cm table .Brq Ar number | all .Cm list .Pp .Ss DUMMYNET CONFIGURATION (TRAFFIC SHAPER AND PACKET SCHEDULER) .Nm .Brq Cm pipe | queue | sched .Ar number .Cm config .Ar config-options .Nm .Op Fl s Op Ar field .Brq Cm pipe | queue | sched .Brq Cm delete | list | show .Op Ar number ... .Pp .Ss IN-KERNEL NAT .Nm .Op Fl q .Cm nat .Ar number .Cm config .Ar config-options .Pp .Nm .Op Fl cfnNqS .Oo .Fl p Ar preproc .Oo .Ar preproc-flags .Oc .Oc .Ar pathname .Sh DESCRIPTION The .Nm utility is the user interface for controlling the .Xr ipfw 4 firewall, the .Xr dummynet 4 traffic shaper/packet scheduler, and the in-kernel NAT services. .Pp A firewall configuration, or .Em ruleset , is made of a list of .Em rules numbered from 1 to 65535. Packets are passed to the firewall from a number of different places in the protocol stack (depending on the source and destination of the packet, it is possible for the firewall to be invoked multiple times on the same packet). The packet passed to the firewall is compared against each of the rules in the .Em ruleset , in rule-number order (multiple rules with the same number are permitted, in which case they are processed in order of insertion). When a match is found, the action corresponding to the matching rule is performed. .Pp Depending on the action and certain system settings, packets can be reinjected into the firewall at some rule after the matching one for further processing. .Pp A ruleset always includes a .Em default rule (numbered 65535) which cannot be modified or deleted, and matches all packets. The action associated with the .Em default rule can be either .Cm deny or .Cm allow depending on how the kernel is configured. .Pp If the ruleset includes one or more rules with the .Cm keep-state or .Cm limit option, the firewall will have a .Em stateful behaviour, i.e., upon a match it will create .Em dynamic rules , i.e. rules that match packets with the same 5-tuple (protocol, source and destination addresses and ports) as the packet which caused their creation. Dynamic rules, which have a limited lifetime, are checked at the first occurrence of a .Cm check-state , .Cm keep-state or .Cm limit rule, and are typically used to open the firewall on-demand to legitimate traffic only. See the .Sx STATEFUL FIREWALL and .Sx EXAMPLES Sections below for more information on the stateful behaviour of .Nm . .Pp All rules (including dynamic ones) have a few associated counters: a packet count, a byte count, a log count and a timestamp indicating the time of the last match. Counters can be displayed or reset with .Nm commands. .Pp Each rule belongs to one of 32 different .Em sets , and there are .Nm commands to atomically manipulate sets, such as enable, disable, swap sets, move all rules in a set to another one, delete all rules in a set. These can be useful to install temporary configurations, or to test them. See Section .Sx SETS OF RULES for more information on .Em sets . .Pp Rules can be added with the .Cm add command; deleted individually or in groups with the .Cm delete command, and globally (except those in set 31) with the .Cm flush command; displayed, optionally with the content of the counters, using the .Cm show and .Cm list commands. Finally, counters can be reset with the .Cm zero and .Cm resetlog commands. .Pp .Ss COMMAND OPTIONS The following general options are available when invoking .Nm : .Bl -tag -width indent .It Fl a Show counter values when listing rules. The .Cm show command implies this option. .It Fl b Only show the action and the comment, not the body of a rule. Implies .Fl c . .It Fl c When entering or showing rules, print them in compact form, i.e., omitting the "ip from any to any" string when this does not carry any additional information. .It Fl d When listing, show dynamic rules in addition to static ones. .It Fl e When listing and .Fl d is specified, also show expired dynamic rules. .It Fl f Do not ask for confirmation for commands that can cause problems if misused, .No i.e. Cm flush . If there is no tty associated with the process, this is implied. .It Fl i When listing a table (see the .Sx LOOKUP TABLES section below for more information on lookup tables), format values as IP addresses. By default, values are shown as integers. .It Fl n Only check syntax of the command strings, without actually passing them to the kernel. .It Fl N Try to resolve addresses and service names in output. .It Fl q Be quiet when executing the .Cm add , .Cm nat , .Cm zero , .Cm resetlog or .Cm flush commands; (implies .Fl f ) . This is useful when updating rulesets by executing multiple .Nm commands in a script (e.g., .Ql sh\ /etc/rc.firewall ) , or by processing a file with many .Nm rules across a remote login session. It also stops a table add or delete from failing if the entry already exists or is not present. .Pp The reason why this option may be important is that for some of these actions, .Nm may print a message; if the action results in blocking the traffic to the remote client, the remote login session will be closed and the rest of the ruleset will not be processed. Access to the console would then be required to recover. .It Fl S When listing rules, show the .Em set each rule belongs to. If this flag is not specified, disabled rules will not be listed. .It Fl s Op Ar field When listing pipes, sort according to one of the four counters (total or current packets or bytes). .It Fl t When listing, show last match timestamp converted with ctime(). .It Fl T When listing, show last match timestamp as seconds from the epoch. This form can be more convenient for postprocessing by scripts. .El .Pp .Ss LIST OF RULES AND PREPROCESSING To ease configuration, rules can be put into a file which is processed using .Nm as shown in the last synopsis line. An absolute .Ar pathname must be used. The file will be read line by line and applied as arguments to the .Nm utility. .Pp Optionally, a preprocessor can be specified using .Fl p Ar preproc where .Ar pathname is to be piped through. Useful preprocessors include .Xr cpp 1 and .Xr m4 1 . If .Ar preproc does not start with a slash .Pq Ql / as its first character, the usual .Ev PATH name search is performed. Care should be taken with this in environments where not all file systems are mounted (yet) by the time .Nm is being run (e.g.\& when they are mounted over NFS). Once .Fl p has been specified, any additional arguments are passed on to the preprocessor for interpretation. This allows for flexible configuration files (like conditionalizing them on the local hostname) and the use of macros to centralize frequently required arguments like IP addresses. .Pp .Ss TRAFFIC SHAPER CONFIGURATION The .Nm .Cm pipe , queue and .Cm sched commands are used to configure the traffic shaper and packet scheduler. See the .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION Section below for details. .Pp If the world and the kernel get out of sync the .Nm ABI may break, preventing you from being able to add any rules. This can adversely effect the booting process. You can use .Nm .Cm disable .Cm firewall to temporarily disable the firewall to regain access to the network, allowing you to fix the problem. .Sh PACKET FLOW A packet is checked against the active ruleset in multiple places in the protocol stack, under control of several sysctl variables. These places and variables are shown below, and it is important to have this picture in mind in order to design a correct ruleset. .Bd -literal -offset indent ^ to upper layers V | | +----------->-----------+ ^ V [ip(6)_input] [ip(6)_output] net.inet(6).ip(6).fw.enable=1 | | ^ V [ether_demux] [ether_output_frame] net.link.ether.ipfw=1 | | +-->--[bdg_forward]-->--+ net.link.bridge.ipfw=1 ^ V | to devices | .Ed .Pp The number of times the same packet goes through the firewall can vary between 0 and 4 depending on packet source and destination, and system configuration. .Pp Note that as packets flow through the stack, headers can be stripped or added to it, and so they may or may not be available for inspection. E.g., incoming packets will include the MAC header when .Nm is invoked from .Cm ether_demux() , but the same packets will have the MAC header stripped off when .Nm is invoked from .Cm ip_input() or .Cm ip6_input() . .Pp Also note that each packet is always checked against the complete ruleset, irrespective of the place where the check occurs, or the source of the packet. If a rule contains some match patterns or actions which are not valid for the place of invocation (e.g.\& trying to match a MAC header within .Cm ip_input or .Cm ip6_input ), the match pattern will not match, but a .Cm not operator in front of such patterns .Em will cause the pattern to .Em always match on those packets. It is thus the responsibility of the programmer, if necessary, to write a suitable ruleset to differentiate among the possible places. .Cm skipto rules can be useful here, as an example: .Bd -literal -offset indent # packets from ether_demux or bdg_forward ipfw add 10 skipto 1000 all from any to any layer2 in # packets from ip_input ipfw add 10 skipto 2000 all from any to any not layer2 in # packets from ip_output ipfw add 10 skipto 3000 all from any to any not layer2 out # packets from ether_output_frame ipfw add 10 skipto 4000 all from any to any layer2 out .Ed .Pp (yes, at the moment there is no way to differentiate between ether_demux and bdg_forward). .Sh SYNTAX In general, each keyword or argument must be provided as a separate command line argument, with no leading or trailing spaces. Keywords are case-sensitive, whereas arguments may or may not be case-sensitive depending on their nature (e.g.\& uid's are, hostnames are not). .Pp Some arguments (e.g. port or address lists) are comma-separated lists of values. In this case, spaces after commas ',' are allowed to make the line more readable. You can also put the entire command (including flags) into a single argument. E.g., the following forms are equivalent: .Bd -literal -offset indent ipfw -q add deny src-ip 10.0.0.0/24,127.0.0.1/8 ipfw -q add deny src-ip 10.0.0.0/24, 127.0.0.1/8 ipfw "-q add deny src-ip 10.0.0.0/24, 127.0.0.1/8" .Ed .Sh RULE FORMAT The format of firewall rules is the following: .Bd -ragged -offset indent .Bk -words .Op Ar rule_number .Op Cm set Ar set_number .Op Cm prob Ar match_probability .Ar action .Op Cm log Op Cm logamount Ar number .Op Cm altq Ar queue .Oo .Bro Cm tag | untag .Brc Ar number .Oc .Ar body .Ek .Ed .Pp where the body of the rule specifies which information is used for filtering packets, among the following: .Pp .Bl -tag -width "Source and dest. addresses and ports" -offset XXX -compact .It Layer-2 header fields When available .It IPv4 and IPv6 Protocol TCP, UDP, ICMP, etc. .It Source and dest. addresses and ports .It Direction See Section .Sx PACKET FLOW .It Transmit and receive interface By name or address .It Misc. IP header fields Version, type of service, datagram length, identification, fragment flag (non-zero IP offset), Time To Live .It IP options .It IPv6 Extension headers Fragmentation, Hop-by-Hop options, Routing Headers, Source routing rthdr0, Mobile IPv6 rthdr2, IPSec options. .It IPv6 Flow-ID .It Misc. TCP header fields TCP flags (SYN, FIN, ACK, RST, etc.), sequence number, acknowledgment number, window .It TCP options .It ICMP types for ICMP packets .It ICMP6 types for ICMP6 packets .It User/group ID When the packet can be associated with a local socket. .It Divert status Whether a packet came from a divert socket (e.g., .Xr natd 8 ) . .It Fib annotation state Whether a packet has been tagged for using a specific FIB (routing table) in future forwarding decisions. .El .Pp Note that some of the above information, e.g.\& source MAC or IP addresses and TCP/UDP ports, can be easily spoofed, so filtering on those fields alone might not guarantee the desired results. .Bl -tag -width indent .It Ar rule_number Each rule is associated with a .Ar rule_number in the range 1..65535, with the latter reserved for the .Em default rule. Rules are checked sequentially by rule number. Multiple rules can have the same number, in which case they are checked (and listed) according to the order in which they have been added. If a rule is entered without specifying a number, the kernel will assign one in such a way that the rule becomes the last one before the .Em default rule. Automatic rule numbers are assigned by incrementing the last non-default rule number by the value of the sysctl variable .Ar net.inet.ip.fw.autoinc_step which defaults to 100. If this is not possible (e.g.\& because we would go beyond the maximum allowed rule number), the number of the last non-default value is used instead. .It Cm set Ar set_number Each rule is associated with a .Ar set_number in the range 0..31. Sets can be individually disabled and enabled, so this parameter is of fundamental importance for atomic ruleset manipulation. It can be also used to simplify deletion of groups of rules. If a rule is entered without specifying a set number, set 0 will be used. .br Set 31 is special in that it cannot be disabled, and rules in set 31 are not deleted by the .Nm ipfw flush command (but you can delete them with the .Nm ipfw delete set 31 command). Set 31 is also used for the .Em default rule. .It Cm prob Ar match_probability A match is only declared with the specified probability (floating point number between 0 and 1). This can be useful for a number of applications such as random packet drop or (in conjunction with .Nm dummynet ) to simulate the effect of multiple paths leading to out-of-order packet delivery. .Pp Note: this condition is checked before any other condition, including ones such as keep-state or check-state which might have side effects. .It Cm log Op Cm logamount Ar number Packets matching a rule with the .Cm log keyword will be made available for logging in two ways: if the sysctl variable .Va net.inet.ip.fw.verbose is set to 0 (default), one can use .Xr bpf 4 attached to the .Li ipfw0 -pseudo interface. There is no overhead if no +pseudo interface. There is no overhead if no .Xr bpf 4 is attached to the pseudo interface. .Pp If .Va net.inet.ip.fw.verbose is set to 1, packets will be logged to .Xr syslogd 8 with a .Dv LOG_SECURITY facility up to a maximum of .Cm logamount packets. If no .Cm logamount is specified, the limit is taken from the sysctl variable .Va net.inet.ip.fw.verbose_limit . In both cases, a value of 0 means unlimited logging. .Pp Once the limit is reached, logging can be re-enabled by clearing the logging counter or the packet counter for that entry, see the .Cm resetlog command. .Pp Note: logging is done after all other packet matching conditions have been successfully verified, and before performing the final action (accept, deny, etc.) on the packet. .It Cm tag Ar number When a packet matches a rule with the .Cm tag keyword, the numeric tag for the given .Ar number in the range 1..65534 will be attached to the packet. The tag acts as an internal marker (it is not sent out over the wire) that can be used to identify these packets later on. This can be used, for example, to provide trust between interfaces and to start doing policy-based filtering. A packet can have multiple tags at the same time. Tags are "sticky", meaning once a tag is applied to a packet by a matching rule it exists until explicit removal. Tags are kept with the packet everywhere within the kernel, but are lost when packet leaves the kernel, for example, on transmitting packet out to the network or sending packet to a .Xr divert 4 socket. .Pp To check for previously applied tags, use the .Cm tagged rule option. To delete previously applied tag, use the .Cm untag keyword. .Pp Note: since tags are kept with the packet everywhere in kernelspace, they can be set and unset anywhere in the kernel network subsystem (using the .Xr mbuf_tags 9 facility), not only by means of the .Xr ipfw 4 .Cm tag and .Cm untag keywords. For example, there can be a specialized .Xr netgraph 4 node doing traffic analyzing and tagging for later inspecting in firewall. .It Cm untag Ar number When a packet matches a rule with the .Cm untag keyword, the tag with the number .Ar number is searched among the tags attached to this packet and, if found, removed from it. Other tags bound to packet, if present, are left untouched. .It Cm altq Ar queue When a packet matches a rule with the .Cm altq keyword, the ALTQ identifier for the given .Ar queue (see .Xr altq 4 ) will be attached. Note that this ALTQ tag is only meaningful for packets going "out" of IPFW, and not being rejected or going to divert sockets. Note that if there is insufficient memory at the time the packet is processed, it will not be tagged, so it is wise to make your ALTQ "default" queue policy account for this. If multiple .Cm altq rules match a single packet, only the first one adds the ALTQ classification tag. In doing so, traffic may be shaped by using .Cm count Cm altq Ar queue rules for classification early in the ruleset, then later applying the filtering decision. For example, .Cm check-state and .Cm keep-state rules may come later and provide the actual filtering decisions in addition to the fallback ALTQ tag. .Pp You must run .Xr pfctl 8 to set up the queues before IPFW will be able to look them up by name, and if the ALTQ disciplines are rearranged, the rules in containing the queue identifiers in the kernel will likely have gone stale and need to be reloaded. Stale queue identifiers will probably result in misclassification. .Pp All system ALTQ processing can be turned on or off via .Nm .Cm enable Ar altq and .Nm .Cm disable Ar altq . The usage of .Va net.inet.ip.fw.one_pass is irrelevant to ALTQ traffic shaping, as the actual rule action is followed always after adding an ALTQ tag. .El .Ss RULE ACTIONS A rule can be associated with one of the following actions, which will be executed when the packet matches the body of the rule. .Bl -tag -width indent .It Cm allow | accept | pass | permit Allow packets that match rule. The search terminates. .It Cm check-state Checks the packet against the dynamic ruleset. If a match is found, execute the action associated with the rule which generated this dynamic rule, otherwise move to the next rule. .br .Cm Check-state rules do not have a body. If no .Cm check-state rule is found, the dynamic ruleset is checked at the first .Cm keep-state or .Cm limit rule. .It Cm count Update counters for all packets that match rule. The search continues with the next rule. .It Cm deny | drop Discard packets that match this rule. The search terminates. .It Cm divert Ar port Divert packets that match this rule to the .Xr divert 4 socket bound to port .Ar port . The search terminates. .It Cm fwd | forward Ar ipaddr | tablearg Ns Op , Ns Ar port Change the next-hop on matching packets to .Ar ipaddr , which can be an IP address or a host name. For IPv4, the next hop can also be supplied by the last table looked up for the packet by using the .Cm tablearg keyword instead of an explicit address. The search terminates if this rule matches. .Pp If .Ar ipaddr is a local address, then matching packets will be forwarded to .Ar port (or the port number in the packet if one is not specified in the rule) on the local machine. .br If .Ar ipaddr is not a local address, then the port number (if specified) is ignored, and the packet will be forwarded to the remote address, using the route as found in the local routing table for that IP. .br A .Ar fwd rule will not match layer-2 packets (those received on ether_input, ether_output, or bridged). .br The .Cm fwd action does not change the contents of the packet at all. In particular, the destination address remains unmodified, so packets forwarded to another system will usually be rejected by that system unless there is a matching rule on that system to capture them. For packets forwarded locally, the local address of the socket will be set to the original destination address of the packet. This makes the .Xr netstat 1 entry look rather weird but is intended for use with transparent proxy servers. .Pp To enable .Cm fwd a custom kernel needs to be compiled with the option .Cd "options IPFIREWALL_FORWARD" . .It Cm nat Ar nat_nr | tablearg Pass packet to a nat instance (for network address translation, address redirect, etc.): see the .Sx NETWORK ADDRESS TRANSLATION (NAT) Section for further information. .It Cm pipe Ar pipe_nr Pass packet to a .Nm dummynet .Dq pipe (for bandwidth limitation, delay, etc.). See the .Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION Section for further information. The search terminates; however, on exit from the pipe and if the .Xr sysctl 8 variable .Va net.inet.ip.fw.one_pass is not set, the packet is passed again to the firewall code starting from the next rule. .It Cm queue Ar queue_nr Pass packet to a .Nm dummynet .Dq queue (for bandwidth limitation using WF2Q+). .It Cm reject (Deprecated). Synonym for .Cm unreach host . .It Cm reset Discard packets that match this rule, and if the packet is a TCP packet, try to send a TCP reset (RST) notice. The search terminates. .It Cm reset6 Discard packets that match this rule, and if the packet is a TCP packet, try to send a TCP reset (RST) notice. The search terminates. .It Cm skipto Ar number | tablearg Skip all subsequent rules numbered less than .Ar number . The search continues with the first rule numbered .Ar number or higher. -It is possible to use the +It is possible to use the .Cm tablearg -keyword with a skipto for a +keyword with a skipto for a .Em computed skipto, but care should be used, as no destination caching is possible in this case so the rules are always walked to find it, -starting from the +starting from the .Cm skipto . .It Cm call Ar number | tablearg The current rule number is saved in the internal stack and ruleset processing continues with the first rule numbered .Ar number or higher. If later a rule with the .Cm return action is encountered, the processing returns to the first rule with number of this .Cm call rule plus one or higher (the same behaviour as with packets returning from .Xr divert 4 socket after a .Cm divert action). This could be used to make somewhat like an assembly language .Dq subroutine calls to rules with common checks for different interfaces, etc. .Pp Rule with any number could be called, not just forward jumps as with .Cm skipto . So, to prevent endless loops in case of mistakes, both .Cm call and .Cm return actions don't do any jumps and simply go to the next rule if memory can't be allocated or stack overflowed/undeflowed. .Pp Internally stack for rule numbers is implemented using .Xr mbuf_tags 9 facility and currently has size of 16 entries. As mbuf tags are lost when packet leaves the kernel, .Cm divert should not be used in subroutines to avoid endless loops and other undesired effects. .It Cm return Takes rule number saved to internal stack by the last .Cm call action and returns ruleset processing to the first rule with number greater than number of corresponding .Cm call rule. See description of the .Cm call action for more details. .Pp Note that .Cm return rules usually end a .Dq subroutine and thus are unconditional, but .Nm command-line utility currently requires every action except .Cm check-state to have body. While it is sometimes useful to return only on some packets, usually you want to print just .Dq return for readability. A workaround for this is to use new syntax and .Fl c switch: .Pp .Bd -literal -offset indent # Add a rule without actual body ipfw add 2999 return via any # List rules without "from any to any" part ipfw -c list .Ed .Pp This cosmetic annoyance may be fixed in future releases. .It Cm tee Ar port Send a copy of packets matching this rule to the .Xr divert 4 socket bound to port .Ar port . The search continues with the next rule. .It Cm unreach Ar code Discard packets that match this rule, and try to send an ICMP unreachable notice with code .Ar code , where .Ar code is a number from 0 to 255, or one of these aliases: .Cm net , host , protocol , port , .Cm needfrag , srcfail , net-unknown , host-unknown , .Cm isolated , net-prohib , host-prohib , tosnet , .Cm toshost , filter-prohib , host-precedence or .Cm precedence-cutoff . The search terminates. .It Cm unreach6 Ar code Discard packets that match this rule, and try to send an ICMPv6 unreachable notice with code .Ar code , where .Ar code is a number from 0, 1, 3 or 4, or one of these aliases: .Cm no-route, admin-prohib, address or .Cm port . The search terminates. .It Cm netgraph Ar cookie Divert packet into netgraph with given .Ar cookie . The search terminates. If packet is later returned from netgraph it is either accepted or continues with the next rule, depending on .Va net.inet.ip.fw.one_pass sysctl variable. .It Cm ngtee Ar cookie A copy of packet is diverted into netgraph, original packet continues with the next rule. See .Xr ng_ipfw 4 for more information on .Cm netgraph and .Cm ngtee actions. .It Cm setfib Ar fibnum | tablearg The packet is tagged so as to use the FIB (routing table) .Ar fibnum in any subsequent forwarding decisions. Initially this is limited to the values 0 through 15, see .Xr setfib 1 . Processing continues at the next rule. -It is possible to use the +It is possible to use the .Cm tablearg keyword with a setfib. If tablearg value is not within compiled FIB range packet fib is set to 0. .It Cm reass Queue and reassemble ip fragments. If the packet is not fragmented, counters are updated and processing continues with the next rule. If the packet is the last logical fragment, the packet is reassembled and, if .Va net.inet.ip.fw.one_pass is set to 0, processing continues with the next rule, else packet is allowed to pass and search terminates. If the packet is a fragment in the middle, it is consumed and processing stops immediately. .Pp Fragments handling can be tuned via .Va net.inet.ip.maxfragpackets and .Va net.inet.ip.maxfragsperpacket which limit, respectively, the maximum number of processable fragments (default: 800) and the maximum number of fragments per packet (default: 16). .Pp NOTA BENE: since fragments do not contain port numbers, they should be avoided with the .Nm reass rule. -Alternatively, direction-based (like +Alternatively, direction-based (like .Nm in / .Nm out ) and source-based (like .Nm via ) match patterns can be used to select fragments. .Pp Usually a simple rule like: .Bd -literal -offset indent # reassemble incoming fragments ipfw add reass all from any to any in .Ed .Pp is all you need at the beginning of your ruleset. .El .Ss RULE BODY The body of a rule contains zero or more patterns (such as specific source and destination addresses or ports, protocol options, incoming or outgoing interfaces, etc.) that the packet must match in order to be recognised. In general, the patterns are connected by (implicit) .Cm and operators -- i.e., all must match in order for the rule to match. Individual patterns can be prefixed by the .Cm not operator to reverse the result of the match, as in .Pp .Dl "ipfw add 100 allow ip from not 1.2.3.4 to any" .Pp Additionally, sets of alternative match patterns .Pq Em or-blocks can be constructed by putting the patterns in lists enclosed between parentheses ( ) or braces { }, and using the .Cm or operator as follows: .Pp .Dl "ipfw add 100 allow ip from { x or not y or z } to any" .Pp Only one level of parentheses is allowed. Beware that most shells have special meanings for parentheses or braces, so it is advisable to put a backslash \\ in front of them to prevent such interpretations. .Pp The body of a rule must in general include a source and destination address specifier. The keyword .Ar any can be used in various places to specify that the content of a required field is irrelevant. .Pp The rule body has the following format: .Bd -ragged -offset indent .Op Ar proto Cm from Ar src Cm to Ar dst .Op Ar options .Ed .Pp The first part (proto from src to dst) is for backward compatibility with earlier versions of .Fx . In modern .Fx any match pattern (including MAC headers, IP protocols, addresses and ports) can be specified in the .Ar options section. .Pp Rule fields have the following meaning: .Bl -tag -width indent .It Ar proto : protocol | Cm { Ar protocol Cm or ... } .It Ar protocol : Oo Cm not Oc Ar protocol-name | protocol-number An IP protocol specified by number or name (for a complete list see .Pa /etc/protocols ) , or one of the following keywords: .Bl -tag -width indent .It Cm ip4 | ipv4 Matches IPv4 packets. .It Cm ip6 | ipv6 Matches IPv6 packets. .It Cm ip | all Matches any packet. .El .Pp The .Cm ipv6 in .Cm proto option will be treated as inner protocol. And, the .Cm ipv4 is not available in .Cm proto option. .Pp The .Cm { Ar protocol Cm or ... } format (an .Em or-block ) is provided for convenience only but its use is deprecated. .It Ar src No and Ar dst : Bro Cm addr | Cm { Ar addr Cm or ... } Brc Op Oo Cm not Oc Ar ports An address (or a list, see below) optionally followed by .Ar ports specifiers. .Pp The second format .Em ( or-block with multiple addresses) is provided for convenience only and its use is discouraged. .It Ar addr : Oo Cm not Oc Bro .Cm any | me | me6 | .Cm table Ns Pq Ar number Ns Op , Ns Ar value .Ar | addr-list | addr-set .Brc .Bl -tag -width indent .It Cm any matches any IP address. .It Cm me matches any IP address configured on an interface in the system. .It Cm me6 matches any IPv6 address configured on an interface in the system. The address list is evaluated at the time the packet is analysed. .It Cm table Ns Pq Ar number Ns Op , Ns Ar value Matches any IPv4 address for which an entry exists in the lookup table .Ar number . If an optional 32-bit unsigned .Ar value is also specified, an entry will match only if it has this value. See the .Sx LOOKUP TABLES section below for more information on lookup tables. .El .It Ar addr-list : ip-addr Ns Op Ns , Ns Ar addr-list .It Ar ip-addr : A host or subnet address specified in one of the following ways: .Bl -tag -width indent .It Ar numeric-ip | hostname Matches a single IPv4 address, specified as dotted-quad or a hostname. Hostnames are resolved at the time the rule is added to the firewall list. .It Ar addr Ns / Ns Ar masklen Matches all addresses with base .Ar addr (specified as an IP address, a network number, or a hostname) and mask width of .Cm masklen bits. As an example, 1.2.3.4/25 or 1.2.3.0/25 will match all IP numbers from 1.2.3.0 to 1.2.3.127 . .It Ar addr Ns : Ns Ar mask Matches all addresses with base .Ar addr (specified as an IP address, a network number, or a hostname) and the mask of .Ar mask , specified as a dotted quad. As an example, 1.2.3.4:255.0.255.0 or 1.0.3.0:255.0.255.0 will match 1.*.3.*. This form is advised only for non-contiguous masks. It is better to resort to the .Ar addr Ns / Ns Ar masklen format for contiguous masks, which is more compact and less error-prone. .El .It Ar addr-set : addr Ns Oo Ns / Ns Ar masklen Oc Ns Cm { Ns Ar list Ns Cm } .It Ar list : Bro Ar num | num-num Brc Ns Op Ns , Ns Ar list Matches all addresses with base address .Ar addr (specified as an IP address, a network number, or a hostname) and whose last byte is in the list between braces { } . Note that there must be no spaces between braces and numbers (spaces after commas are allowed). Elements of the list can be specified as single entries or ranges. The .Ar masklen field is used to limit the size of the set of addresses, and can have any value between 24 and 32. If not specified, it will be assumed as 24. .br This format is particularly useful to handle sparse address sets within a single rule. Because the matching occurs using a bitmask, it takes constant time and dramatically reduces the complexity of rulesets. .br As an example, an address specified as 1.2.3.4/24{128,35-55,89} or 1.2.3.0/24{128,35-55,89} will match the following IP addresses: .br 1.2.3.128, 1.2.3.35 to 1.2.3.55, 1.2.3.89 . .It Ar addr6-list : ip6-addr Ns Op Ns , Ns Ar addr6-list .It Ar ip6-addr : A host or subnet specified one of the following ways: .Bl -tag -width indent .It Ar numeric-ip | hostname Matches a single IPv6 address as allowed by .Xr inet_pton 3 or a hostname. Hostnames are resolved at the time the rule is added to the firewall list. .It Ar addr Ns / Ns Ar masklen Matches all IPv6 addresses with base .Ar addr (specified as allowed by .Xr inet_pton or a hostname) and mask width of .Cm masklen bits. .El .Pp No support for sets of IPv6 addresses is provided because IPv6 addresses are typically random past the initial prefix. .It Ar ports : Bro Ar port | port Ns \&- Ns Ar port Ns Brc Ns Op , Ns Ar ports For protocols which support port numbers (such as TCP and UDP), optional .Cm ports may be specified as one or more ports or port ranges, separated by commas but no spaces, and an optional .Cm not operator. The .Ql \&- notation specifies a range of ports (including boundaries). .Pp Service names (from .Pa /etc/services ) may be used instead of numeric port values. The length of the port list is limited to 30 ports or ranges, though one can specify larger ranges by using an .Em or-block in the .Cm options section of the rule. .Pp A backslash .Pq Ql \e can be used to escape the dash .Pq Ql - character in a service name (from a shell, the backslash must be typed twice to avoid the shell itself interpreting it as an escape character). .Pp .Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any" .Pp Fragmented packets which have a non-zero offset (i.e., not the first fragment) will never match a rule which has one or more port specifications. See the .Cm frag option for details on matching fragmented packets. .El .Ss RULE OPTIONS (MATCH PATTERNS) Additional match patterns can be used within rules. Zero or more of these so-called .Em options can be present in a rule, optionally prefixed by the .Cm not operand, and possibly grouped into .Em or-blocks . .Pp The following match patterns can be used (listed in alphabetical order): .Bl -tag -width indent .It Cm // this is a comment. Inserts the specified text as a comment in the rule. Everything following // is considered as a comment and stored in the rule. You can have comment-only rules, which are listed as having a .Cm count action followed by the comment. .It Cm bridged Alias for .Cm layer2 . .It Cm diverted Matches only packets generated by a divert socket. .It Cm diverted-loopback Matches only packets coming from a divert socket back into the IP stack input for delivery. .It Cm diverted-output Matches only packets going from a divert socket back outward to the IP stack output for delivery. .It Cm dst-ip Ar ip-address Matches IPv4 packets whose destination IP is one of the address(es) specified as argument. .It Bro Cm dst-ip6 | dst-ipv6 Brc Ar ip6-address Matches IPv6 packets whose destination IP is one of the address(es) specified as argument. .It Cm dst-port Ar ports Matches IP packets whose destination port is one of the port(s) specified as argument. .It Cm established Matches TCP packets that have the RST or ACK bits set. .It Cm ext6hdr Ar header Matches IPv6 packets containing the extended header given by .Ar header . Supported headers are: .Pp Fragment, .Pq Cm frag , Hop-to-hop options .Pq Cm hopopt , any type of Routing Header .Pq Cm route , Source routing Routing Header Type 0 .Pq Cm rthdr0 , Mobile IPv6 Routing Header Type 2 .Pq Cm rthdr2 , Destination options .Pq Cm dstopt , IPSec authentication headers .Pq Cm ah , and IPsec encapsulated security payload headers .Pq Cm esp . .It Cm fib Ar fibnum Matches a packet that has been tagged to use the given FIB (routing table) number. .It Cm flow-id Ar labels Matches IPv6 packets containing any of the flow labels given in .Ar labels . .Ar labels is a comma separated list of numeric flow labels. .It Cm frag Matches packets that are fragments and not the first fragment of an IP datagram. Note that these packets will not have the next protocol header (e.g.\& TCP, UDP) so options that look into these headers cannot match. .It Cm gid Ar group Matches all TCP or UDP packets sent by or received for a .Ar group . A .Ar group may be specified by name or number. .It Cm jail Ar prisonID Matches all TCP or UDP packets sent by or received for the jail whos prison ID is .Ar prisonID . .It Cm icmptypes Ar types Matches ICMP packets whose ICMP type is in the list .Ar types . The list may be specified as any combination of individual types (numeric) separated by commas. .Em Ranges are not allowed . The supported ICMP types are: .Pp echo reply .Pq Cm 0 , destination unreachable .Pq Cm 3 , source quench .Pq Cm 4 , redirect .Pq Cm 5 , echo request .Pq Cm 8 , router advertisement .Pq Cm 9 , router solicitation .Pq Cm 10 , time-to-live exceeded .Pq Cm 11 , IP header bad .Pq Cm 12 , timestamp request .Pq Cm 13 , timestamp reply .Pq Cm 14 , information request .Pq Cm 15 , information reply .Pq Cm 16 , address mask request .Pq Cm 17 and address mask reply .Pq Cm 18 . .It Cm icmp6types Ar types Matches ICMP6 packets whose ICMP6 type is in the list of .Ar types . The list may be specified as any combination of individual types (numeric) separated by commas. .Em Ranges are not allowed . .It Cm in | out Matches incoming or outgoing packets, respectively. .Cm in and .Cm out are mutually exclusive (in fact, .Cm out is implemented as .Cm not in Ns No ). .It Cm ipid Ar id-list Matches IPv4 packets whose .Cm ip_id field has value included in .Ar id-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm iplen Ar len-list Matches IP packets whose total length, including header and data, is in the set .Ar len-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm ipoptions Ar spec Matches packets whose IPv4 header contains the comma separated list of options specified in .Ar spec . The supported IP options are: .Pp .Cm ssrr (strict source route), .Cm lsrr (loose source route), .Cm rr (record packet route) and .Cm ts (timestamp). The absence of a particular option may be denoted with a .Ql \&! . .It Cm ipprecedence Ar precedence Matches IPv4 packets whose precedence field is equal to .Ar precedence . .It Cm ipsec Matches packets that have IPSEC history associated with them (i.e., the packet comes encapsulated in IPSEC, the kernel has IPSEC support and IPSEC_FILTERTUNNEL option, and can correctly decapsulate it). .Pp Note that specifying .Cm ipsec is different from specifying .Cm proto Ar ipsec as the latter will only look at the specific IP protocol field, irrespective of IPSEC kernel support and the validity of the IPSEC data. .Pp Further note that this flag is silently ignored in kernels without IPSEC support. It does not affect rule processing when given and the rules are handled as if with no .Cm ipsec flag. .It Cm iptos Ar spec Matches IPv4 packets whose .Cm tos field contains the comma separated list of service types specified in .Ar spec . The supported IP types of service are: .Pp .Cm lowdelay .Pq Dv IPTOS_LOWDELAY , .Cm throughput .Pq Dv IPTOS_THROUGHPUT , .Cm reliability .Pq Dv IPTOS_RELIABILITY , .Cm mincost .Pq Dv IPTOS_MINCOST , .Cm congestion .Pq Dv IPTOS_ECN_CE . The absence of a particular type may be denoted with a .Ql \&! . .It Cm ipttl Ar ttl-list Matches IPv4 packets whose time to live is included in .Ar ttl-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm ipversion Ar ver Matches IP packets whose IP version field is .Ar ver . .It Cm keep-state Upon a match, the firewall will create a dynamic rule, whose default behaviour is to match bidirectional traffic between source and destination IP/port using the same protocol. The rule has a limited lifetime (controlled by a set of .Xr sysctl 8 variables), and the lifetime is refreshed every time a matching packet is found. .It Cm layer2 Matches only layer2 packets, i.e., those passed to .Nm from ether_demux() and ether_output_frame(). .It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N The firewall will only allow .Ar N connections with the same set of parameters as specified in the rule. One or more of source and destination addresses and ports can be specified. Currently, only IPv4 flows are supported. .It Cm lookup Bro Cm dst-ip | dst-port | src-ip | src-port | uid | jail Brc Ar N Search an entry in lookup table .Ar N that matches the field specified as argument. If not found, the match fails. Otherwise, the match succeeds and .Cm tablearg is set to the value extracted from the table. .Pp This option can be useful to quickly dispatch traffic based on certain packet fields. See the .Sx LOOKUP TABLES section below for more information on lookup tables. .It Cm { MAC | mac } Ar dst-mac src-mac Match packets with a given .Ar dst-mac and .Ar src-mac addresses, specified as the .Cm any keyword (matching any MAC address), or six groups of hex digits separated by colons, and optionally followed by a mask indicating the significant bits. The mask may be specified using either of the following methods: .Bl -enum -width indent .It A slash .Pq / followed by the number of significant bits. For example, an address with 33 significant bits could be specified as: .Pp .Dl "MAC 10:20:30:40:50:60/33 any" .Pp .It An ampersand .Pq & followed by a bitmask specified as six groups of hex digits separated by colons. For example, an address in which the last 16 bits are significant could be specified as: .Pp .Dl "MAC 10:20:30:40:50:60&00:00:00:00:ff:ff any" .Pp Note that the ampersand character has a special meaning in many shells and should generally be escaped. .Pp .El Note that the order of MAC addresses (destination first, source second) is the same as on the wire, but the opposite of the one used for IP addresses. .It Cm mac-type Ar mac-type Matches packets whose Ethernet Type field corresponds to one of those specified as argument. .Ar mac-type is specified in the same way as .Cm port numbers (i.e., one or more comma-separated single values or ranges). You can use symbolic names for known values such as .Em vlan , ipv4, ipv6 . Values can be entered as decimal or hexadecimal (if prefixed by 0x), and they are always printed as hexadecimal (unless the .Cm -N option is used, in which case symbolic resolution will be attempted). .It Cm proto Ar protocol Matches packets with the corresponding IP protocol. .It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar table Ns Pq Ar number Ns Op , Ns Ar value | Ar ipno | Ar any Matches packets received, transmitted or going through, respectively, the interface specified by exact name .Ns No ( Ar ifX Ns No ), by device name .Ns No ( Ar if Ns Ar * Ns No ), by IP address, or through some interface. .Pp The .Cm via keyword causes the interface to always be checked. If .Cm recv or .Cm xmit is used instead of .Cm via , then only the receive or transmit interface (respectively) is checked. By specifying both, it is possible to match packets based on both receive and transmit interface, e.g.: .Pp .Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1" .Pp The .Cm recv interface can be tested on either incoming or outgoing packets, while the .Cm xmit interface can only be tested on outgoing packets. So .Cm out is required (and .Cm in is invalid) whenever .Cm xmit is used. .Pp A packet might not have a receive or transmit interface: packets originating from the local host have no receive interface, while packets destined for the local host have no transmit interface. .It Cm setup Matches TCP packets that have the SYN bit set but no ACK bit. This is the short form of .Dq Li tcpflags\ syn,!ack . .It Cm sockarg Matches packets that are associated to a local socket and for which the SO_USER_COOKIE socket option has been set to a non-zero value. As a side effect, the value of the option is made available as .Cm tablearg value, which in turn can be used as .Cm skipto or .Cm pipe number. .It Cm src-ip Ar ip-address Matches IPv4 packets whose source IP is one of the address(es) specified as an argument. .It Cm src-ip6 Ar ip6-address Matches IPv6 packets whose source IP is one of the address(es) specified as an argument. .It Cm src-port Ar ports Matches IP packets whose source port is one of the port(s) specified as argument. .It Cm tagged Ar tag-list Matches packets whose tags are included in .Ar tag-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . Tags can be applied to the packet using .Cm tag rule action parameter (see it's description for details on tags). .It Cm tcpack Ar ack TCP packets only. Match if the TCP header acknowledgment number field is set to .Ar ack . .It Cm tcpdatalen Ar tcpdatalen-list Matches TCP packets whose length of TCP data is .Ar tcpdatalen-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm tcpflags Ar spec TCP packets only. Match if the TCP header contains the comma separated list of flags specified in .Ar spec . The supported TCP flags are: .Pp .Cm fin , .Cm syn , .Cm rst , .Cm psh , .Cm ack and .Cm urg . The absence of a particular flag may be denoted with a .Ql \&! . A rule which contains a .Cm tcpflags specification can never match a fragmented packet which has a non-zero offset. See the .Cm frag option for details on matching fragmented packets. .It Cm tcpseq Ar seq TCP packets only. Match if the TCP header sequence number field is set to .Ar seq . .It Cm tcpwin Ar tcpwin-list Matches TCP packets whose header window field is set to .Ar tcpwin-list , which is either a single value or a list of values or ranges specified in the same way as .Ar ports . .It Cm tcpoptions Ar spec TCP packets only. Match if the TCP header contains the comma separated list of options specified in .Ar spec . The supported TCP options are: .Pp .Cm mss (maximum segment size), .Cm window (tcp window advertisement), .Cm sack (selective ack), .Cm ts (rfc1323 timestamp) and .Cm cc (rfc1644 t/tcp connection count). The absence of a particular option may be denoted with a .Ql \&! . .It Cm uid Ar user Match all TCP or UDP packets sent by or received for a .Ar user . A .Ar user may be matched by name or identification number. .It Cm verrevpath For incoming packets, a routing table lookup is done on the packet's source address. If the interface on which the packet entered the system matches the outgoing interface for the route, the packet matches. If the interfaces do not match up, the packet does not match. All outgoing packets or packets with no incoming interface match. .Pp The name and functionality of the option is intentionally similar to the Cisco IOS command: .Pp .Dl ip verify unicast reverse-path .Pp This option can be used to make anti-spoofing rules to reject all packets with source addresses not from this interface. See also the option .Cm antispoof . .It Cm versrcreach For incoming packets, a routing table lookup is done on the packet's source address. If a route to the source address exists, but not the default route or a blackhole/reject route, the packet matches. Otherwise, the packet does not match. All outgoing packets match. .Pp The name and functionality of the option is intentionally similar to the Cisco IOS command: .Pp .Dl ip verify unicast source reachable-via any .Pp This option can be used to make anti-spoofing rules to reject all packets whose source address is unreachable. .It Cm antispoof For incoming packets, the packet's source address is checked if it belongs to a directly connected network. If the network is directly connected, then the interface the packet came on in is compared to the interface the network is connected to. When incoming interface and directly connected interface are not the same, the packet does not match. Otherwise, the packet does match. All outgoing packets match. .Pp This option can be used to make anti-spoofing rules to reject all packets that pretend to be from a directly connected network but do not come in through that interface. This option is similar to but more restricted than .Cm verrevpath because it engages only on packets with source addresses of directly connected networks instead of all source addresses. .El .Sh LOOKUP TABLES Lookup tables are useful to handle large sparse sets of addresses or other search keys (e.g. ports, jail IDs, interface names). In the rest of this section we will use the term ``address''. There may be up to 4096 different lookup tables, numbered 0 to 4095. .Pp Each entry is represented by an .Ar addr Ns Op / Ns Ar masklen and will match all addresses with base .Ar addr (specified as an IPv4/IPv6 address, a hostname or an unsigned integer) and mask width of .Ar masklen bits. If .Ar masklen is not specified, it defaults to 32 for IPv4 and 128 for IPv6. When looking up an IP address in a table, the most specific entry will match. Associated with each entry is a 32-bit unsigned .Ar value , which can optionally be checked by a rule matching code. When adding an entry, if .Ar value is not specified, it defaults to 0. .Pp An entry can be added to a table .Pq Cm add , or removed from a table .Pq Cm delete . A table can be examined .Pq Cm list or flushed .Pq Cm flush . .Pp Internally, each table is stored in a Radix tree, the same way as the routing table (see .Xr route 4 ) . .Pp Lookup tables currently support only ports, jail IDs, IPv4/IPv6 addresses and interface names. Wildcards is not supported for interface names. .Pp The .Cm tablearg feature provides the ability to use a value, looked up in the table, as the argument for a rule action, action parameter or rule option. This can significantly reduce number of rules in some configurations. If two tables are used in a rule, the result of the second (destination) is used. The .Cm tablearg argument can be used with the following actions: .Cm nat, pipe , queue, divert, tee, netgraph, ngtee, fwd, skipto, setfib, action parameters: .Cm tag, untag, rule options: .Cm limit, tagged. .Pp When used with .Cm fwd it is possible to supply table entries with values that are in the form of IP addresses or hostnames. See the .Sx EXAMPLES Section for example usage of tables and the tablearg keyword. .Pp When used with the .Cm skipto action, the user should be aware that the code will walk the ruleset up to a rule equal to, or past, the given number, and should therefore try keep the -ruleset compact between the skipto and the target rules. +ruleset compact between the skipto and the target rules. .Sh SETS OF RULES Each rule belongs to one of 32 different .Em sets , numbered 0 to 31. Set 31 is reserved for the default rule. .Pp By default, rules are put in set 0, unless you use the .Cm set N attribute when entering a new rule. Sets can be individually and atomically enabled or disabled, so this mechanism permits an easy way to store multiple configurations of the firewall and quickly (and atomically) switch between them. The command to enable/disable sets is .Bd -ragged -offset indent .Nm .Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... .Ed .Pp where multiple .Cm enable or .Cm disable sections can be specified. Command execution is atomic on all the sets specified in the command. By default, all sets are enabled. .Pp When you disable a set, its rules behave as if they do not exist in the firewall configuration, with only one exception: .Bd -ragged -offset indent dynamic rules created from a rule before it had been disabled will still be active until they expire. In order to delete dynamic rules you have to explicitly delete the parent rule which generated them. .Ed .Pp The set number of rules can be changed with the command .Bd -ragged -offset indent .Nm .Cm set move .Brq Cm rule Ar rule-number | old-set .Cm to Ar new-set .Ed .Pp Also, you can atomically swap two rulesets with the command .Bd -ragged -offset indent .Nm .Cm set swap Ar first-set second-set .Ed .Pp See the .Sx EXAMPLES Section on some possible uses of sets of rules. .Sh STATEFUL FIREWALL Stateful operation is a way for the firewall to dynamically create rules for specific flows when packets that match a given pattern are detected. Support for stateful operation comes through the .Cm check-state , keep-state and .Cm limit options of .Nm rules . .Pp Dynamic rules are created when a packet matches a .Cm keep-state or .Cm limit rule, causing the creation of a .Em dynamic rule which will match all and only packets with a given .Em protocol between a .Em src-ip/src-port dst-ip/dst-port pair of addresses .Em ( src and .Em dst are used here only to denote the initial match addresses, but they are completely equivalent afterwards). Dynamic rules will be checked at the first .Cm check-state, keep-state or .Cm limit occurrence, and the action performed upon a match will be the same as in the parent rule. .Pp Note that no additional attributes other than protocol and IP addresses and ports are checked on dynamic rules. .Pp The typical use of dynamic rules is to keep a closed firewall configuration, but let the first TCP SYN packet from the inside network install a dynamic rule for the flow so that packets belonging to that session will be allowed through the firewall: .Pp .Dl "ipfw add check-state" .Dl "ipfw add allow tcp from my-subnet to any setup keep-state" .Dl "ipfw add deny tcp from any to any" .Pp A similar approach can be used for UDP, where an UDP packet coming from the inside will install a dynamic rule to let the response through the firewall: .Pp .Dl "ipfw add check-state" .Dl "ipfw add allow udp from my-subnet to any keep-state" .Dl "ipfw add deny udp from any to any" .Pp Dynamic rules expire after some time, which depends on the status of the flow and the setting of some .Cm sysctl variables. See Section .Sx SYSCTL VARIABLES for more details. For TCP sessions, dynamic rules can be instructed to periodically send keepalive packets to refresh the state of the rule when it is about to expire. .Pp See Section .Sx EXAMPLES for more examples on how to use dynamic rules. .Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION .Nm is also the user interface for the .Nm dummynet traffic shaper, packet scheduler and network emulator, a subsystem that can artificially queue, delay or drop packets emulating the behaviour of certain network links or queueing systems. .Pp .Nm dummynet operates by first using the firewall to select packets using any match pattern that can be used in .Nm rules. Matching packets are then passed to either of two different objects, which implement the traffic regulation: .Bl -hang -offset XXXX .It Em pipe A .Em pipe emulates a .Em link with given bandwidth and propagation delay, driven by a FIFO scheduler and a single queue with programmable queue size and packet loss rate. Packets are appended to the queue as they come out from .Nm ipfw , and then transferred in FIFO order to the link at the desired rate. .It Em queue A .Em queue is an abstraction used to implement packet scheduling using one of several packet scheduling algorithms. Packets sent to a .Em queue are first grouped into flows according to a mask on the 5-tuple. Flows are then passed to the scheduler associated to the .Em queue , and each flow uses scheduling parameters (weight and others) as configured in the .Em queue itself. A scheduler in turn is connected to an emulated link, and arbitrates the link's bandwidth among backlogged flows according to weights and to the features of the scheduling algorithm in use. .El .Pp In practice, .Em pipes can be used to set hard limits to the bandwidth that a flow can use, whereas .Em queues can be used to determine how different flows share the available bandwidth. .Pp A graphical representation of the binding of queues, flows, schedulers and links is below. .Bd -literal -offset indent (flow_mask|sched_mask) sched_mask +---------+ weight Wx +-------------+ | |->-[flow]-->--| |-+ -->--| QUEUE x | ... | | | | |->-[flow]-->--| SCHEDuler N | | +---------+ | | | ... | +--[LINK N]-->-- +---------+ weight Wy | | +--[LINK N]-->-- | |->-[flow]-->--| | | -->--| QUEUE y | ... | | | | |->-[flow]-->--| | | +---------+ +-------------+ | +-------------+ .Ed It is important to understand the role of the SCHED_MASK and FLOW_MASK, which are configured through the commands .Dl "ipfw sched N config mask SCHED_MASK ..." and .Dl "ipfw queue X config mask FLOW_MASK ..." . .Pp The SCHED_MASK is used to assign flows to one or more scheduler instances, one for each value of the packet's 5-tuple after applying SCHED_MASK. As an example, using ``src-ip 0xffffff00'' creates one instance for each /24 destination subnet. .Pp The FLOW_MASK, together with the SCHED_MASK, is used to split packets into flows. As an example, using ``src-ip 0x000000ff'' together with the previous SCHED_MASK makes a flow for each individual source address. In turn, flows for each /24 subnet will be sent to the same scheduler instance. .Pp The above diagram holds even for the .Em pipe case, with the only restriction that a .Em pipe only supports a SCHED_MASK, and forces the use of a FIFO scheduler (these are for backward compatibility reasons; in fact, internally, a .Nm dummynet's pipe is implemented exactly as above). .Pp There are two modes of .Nm dummynet operation: .Dq normal and .Dq fast . The .Dq normal mode tries to emulate a real link: the .Nm dummynet scheduler ensures that the packet will not leave the pipe faster than it would on the real link with a given bandwidth. The .Dq fast mode allows certain packets to bypass the .Nm dummynet scheduler (if packet flow does not exceed pipe's bandwidth). This is the reason why the .Dq fast mode requires less CPU cycles per packet (on average) and packet latency can be significantly lower in comparison to a real link with the same bandwidth. The default mode is .Dq normal . The .Dq fast mode can be enabled by setting the .Va net.inet.ip.dummynet.io_fast .Xr sysctl 8 variable to a non-zero value. .Pp .Ss PIPE, QUEUE AND SCHEDULER CONFIGURATION The .Em pipe , .Em queue and .Em scheduler configuration commands are the following: .Bd -ragged -offset indent .Cm pipe Ar number Cm config Ar pipe-configuration .Pp .Cm queue Ar number Cm config Ar queue-configuration .Pp .Cm sched Ar number Cm config Ar sched-configuration .Ed .Pp The following parameters can be configured for a pipe: .Pp .Bl -tag -width indent -compact .It Cm bw Ar bandwidth | device Bandwidth, measured in .Sm off .Op Cm K | M .Brq Cm bit/s | Byte/s . .Sm on .Pp A value of 0 (default) means unlimited bandwidth. The unit must immediately follow the number, as in .Pp .Dl "ipfw pipe 1 config bw 300Kbit/s" .Pp If a device name is specified instead of a numeric value, as in .Pp .Dl "ipfw pipe 1 config bw tun0" .Pp then the transmit clock is supplied by the specified device. At the moment only the .Xr tun 4 device supports this functionality, for use in conjunction with .Xr ppp 8 . .Pp .It Cm delay Ar ms-delay Propagation delay, measured in milliseconds. The value is rounded to the next multiple of the clock tick (typically 10ms, but it is a good practice to run kernels with .Dq "options HZ=1000" to reduce the granularity to 1ms or less). The default value is 0, meaning no delay. .Pp .It Cm burst Ar size If the data to be sent exceeds the pipe's bandwidth limit (and the pipe was previously idle), up to .Ar size bytes of data are allowed to bypass the .Nm dummynet scheduler, and will be sent as fast as the physical link allows. Any additional data will be transmitted at the rate specified by the .Nm pipe bandwidth. The burst size depends on how long the pipe has been idle; the effective burst size is calculated as follows: MAX( .Ar size , .Nm bw * pipe_idle_time). .Pp .It Cm profile Ar filename A file specifying the additional overhead incurred in the transmission of a packet on the link. .Pp Some link types introduce extra delays in the transmission of a packet, e.g. because of MAC level framing, contention on the use of the channel, MAC level retransmissions and so on. From our point of view, the channel is effectively unavailable for this extra time, which is constant or variable depending on the link type. Additionally, packets may be dropped after this time (e.g. on a wireless link after too many retransmissions). We can model the additional delay with an empirical curve that represents its distribution. .Bd -literal -offset indent cumulative probability 1.0 ^ | L +-- loss-level x | ****** | * | ***** | * | ** | * +-------*-------------------> delay .Ed The empirical curve may have both vertical and horizontal lines. Vertical lines represent constant delay for a range of probabilities. Horizontal lines correspond to a discontinuity in the delay distribution: the pipe will use the largest delay for a given probability. .Pp The file format is the following, with whitespace acting as a separator and '#' indicating the beginning a comment: .Bl -tag -width indent .It Cm name Ar identifier optional name (listed by "ipfw pipe show") to identify the delay distribution; .It Cm bw Ar value the bandwidth used for the pipe. If not specified here, it must be present explicitly as a configuration parameter for the pipe; .It Cm loss-level Ar L the probability above which packets are lost. (0.0 <= L <= 1.0, default 1.0 i.e. no loss); .It Cm samples Ar N the number of samples used in the internal representation of the curve (2..1024; default 100); .It Cm "delay prob" | "prob delay" One of these two lines is mandatory and defines the format of the following lines with data points. .It Ar XXX Ar YYY 2 or more lines representing points in the curve, with either delay or probability first, according to the chosen format. The unit for delay is milliseconds. Data points do not need to be sorted. Also, the number of actual lines can be different from the value of the "samples" parameter: .Nm utility will sort and interpolate the curve as needed. .El .Pp Example of a profile file: .Bd -literal -offset indent name bla_bla_bla samples 100 loss-level 0.86 prob delay 0 200 # minimum overhead is 200ms 0.5 200 0.5 300 0.8 1000 0.9 1300 1 1300 #configuration file end .Ed .El .Pp The following parameters can be configured for a queue: .Pp .Bl -tag -width indent -compact .It Cm pipe Ar pipe_nr Connects a queue to the specified pipe. Multiple queues (with the same or different weights) can be connected to the same pipe, which specifies the aggregate rate for the set of queues. .Pp .It Cm weight Ar weight Specifies the weight to be used for flows matching this queue. The weight must be in the range 1..100, and defaults to 1. .El .Pp The following parameters can be configured for a scheduler: .Pp .Bl -tag -width indent -compact .It Cm type Ar {fifo | wf2qp | rr | qfq} specifies the scheduling algorithm to use. .Bl -tag -width indent -compact .It cm fifo is just a FIFO scheduler (which means that all packets are stored in the same queue as they arrive to the scheduler). FIFO has O(1) per-packet time complexity, with very low constants (estimate 60-80ns on a 2GHz desktop machine) but gives no service guarantees. .It Cm wf2qp implements the WF2Q+ algorithm, which is a Weighted Fair Queueing algorithm which permits flows to share bandwidth according to their weights. Note that weights are not priorities; even a flow with a minuscule weight will never starve. WF2Q+ has O(log N) per-packet processing cost, where N is the number of flows, and is the default algorithm used by previous versions dummynet's queues. .It Cm rr implements the Deficit Round Robin algorithm, which has O(1) processing costs (roughly, 100-150ns per packet) and permits bandwidth allocation according to weights, but with poor service guarantees. .It Cm qfq implements the QFQ algorithm, which is a very fast variant of WF2Q+, with similar service guarantees and O(1) processing costs (roughly, 200-250ns per packet). .El .El .Pp In addition to the type, all parameters allowed for a pipe can also be specified for a scheduler. .Pp Finally, the following parameters can be configured for both pipes and queues: .Pp .Bl -tag -width XXXX -compact .It Cm buckets Ar hash-table-size Specifies the size of the hash table used for storing the various queues. Default value is 64 controlled by the .Xr sysctl 8 variable .Va net.inet.ip.dummynet.hash_size , allowed range is 16 to 65536. .Pp .It Cm mask Ar mask-specifier Packets sent to a given pipe or queue by an .Nm rule can be further classified into multiple flows, each of which is then sent to a different .Em dynamic pipe or queue. A flow identifier is constructed by masking the IP addresses, ports and protocol types as specified with the .Cm mask options in the configuration of the pipe or queue. For each different flow identifier, a new pipe or queue is created with the same parameters as the original object, and matching packets are sent to it. .Pp Thus, when .Em dynamic pipes are used, each flow will get the same bandwidth as defined by the pipe, whereas when .Em dynamic queues are used, each flow will share the parent's pipe bandwidth evenly with other flows generated by the same queue (note that other queues with different weights might be connected to the same pipe). .br Available mask specifiers are a combination of one or more of the following: .Pp .Cm dst-ip Ar mask , .Cm dst-ip6 Ar mask , .Cm src-ip Ar mask , .Cm src-ip6 Ar mask , .Cm dst-port Ar mask , .Cm src-port Ar mask , .Cm flow-id Ar mask , .Cm proto Ar mask or .Cm all , .Pp where the latter means all bits in all fields are significant. .Pp .It Cm noerror When a packet is dropped by a .Nm dummynet queue or pipe, the error is normally reported to the caller routine in the kernel, in the same way as it happens when a device queue fills up. Setting this option reports the packet as successfully delivered, which can be needed for some experimental setups where you want to simulate loss or congestion at a remote router. .Pp .It Cm plr Ar packet-loss-rate Packet loss rate. Argument .Ar packet-loss-rate is a floating-point number between 0 and 1, with 0 meaning no loss, 1 meaning 100% loss. The loss rate is internally represented on 31 bits. .Pp .It Cm queue Brq Ar slots | size Ns Cm Kbytes Queue size, in .Ar slots or .Cm KBytes . Default value is 50 slots, which is the typical queue size for Ethernet devices. Note that for slow speed links you should keep the queue size short or your traffic might be affected by a significant queueing delay. E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit or 20s of queue on a 30Kbit/s pipe. Even worse effects can result if you get packets from an interface with a much larger MTU, e.g.\& the loopback interface with its 16KB packets. The .Xr sysctl 8 variables .Em net.inet.ip.dummynet.pipe_byte_limit and .Em net.inet.ip.dummynet.pipe_slot_limit control the maximum lengths that can be specified. .Pp .It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p Make use of the RED (Random Early Detection) queue management algorithm. .Ar w_q and .Ar max_p are floating point numbers between 0 and 1 (0 not included), while .Ar min_th and .Ar max_th are integer numbers specifying thresholds for queue management (thresholds are computed in bytes if the queue has been defined in bytes, in slots otherwise). The .Nm dummynet also supports the gentle RED variant (gred). Three .Xr sysctl 8 variables can be used to control the RED behaviour: .Bl -tag -width indent .It Va net.inet.ip.dummynet.red_lookup_depth specifies the accuracy in computing the average queue when the link is idle (defaults to 256, must be greater than zero) .It Va net.inet.ip.dummynet.red_avg_pkt_size specifies the expected average packet size (defaults to 512, must be greater than zero) .It Va net.inet.ip.dummynet.red_max_pkt_size specifies the expected maximum packet size, only used when queue thresholds are in bytes (defaults to 1500, must be greater than zero). .El .El .Pp When used with IPv6 data, .Nm dummynet currently has several limitations. Information necessary to route link-local packets to an interface is not available after processing by .Nm dummynet so those packets are dropped in the output path. Care should be taken to ensure that link-local packets are not passed to .Nm dummynet . .Sh CHECKLIST Here are some important points to consider when designing your rules: .Bl -bullet .It Remember that you filter both packets going .Cm in and .Cm out . Most connections need packets going in both directions. .It Remember to test very carefully. It is a good idea to be near the console when doing this. If you cannot be near the console, use an auto-recovery script such as the one in .Pa /usr/share/examples/ipfw/change_rules.sh . .It Do not forget the loopback interface. .El .Sh FINE POINTS .Bl -bullet .It There are circumstances where fragmented datagrams are unconditionally dropped. TCP packets are dropped if they do not contain at least 20 bytes of TCP header, UDP packets are dropped if they do not contain a full 8 byte UDP header, and ICMP packets are dropped if they do not contain 4 bytes of ICMP header, enough to specify the ICMP type, code, and checksum. These packets are simply logged as .Dq pullup failed since there may not be enough good data in the packet to produce a meaningful log entry. .It Another type of packet is unconditionally dropped, a TCP packet with a fragment offset of one. This is a valid packet, but it only has one use, to try to circumvent firewalls. When logging is enabled, these packets are reported as being dropped by rule -1. .It If you are logged in over a network, loading the .Xr kld 4 version of .Nm is probably not as straightforward as you would think. The following command line is recommended: .Bd -literal -offset indent kldload ipfw && \e ipfw add 32000 allow ip from any to any .Ed .Pp Along the same lines, doing an .Bd -literal -offset indent ipfw flush .Ed .Pp in similar surroundings is also a bad idea. .It The .Nm filter list may not be modified if the system security level is set to 3 or higher (see .Xr init 8 for information on system security levels). .El .Sh PACKET DIVERSION A .Xr divert 4 socket bound to the specified port will receive all packets diverted to that port. If no socket is bound to the destination port, or if the divert module is not loaded, or if the kernel was not compiled with divert socket support, the packets are dropped. .Sh NETWORK ADDRESS TRANSLATION (NAT) .Pp .Nm support in-kernel NAT using the kernel version of .Xr libalias 3 . .Pp The nat configuration command is the following: .Bd -ragged -offset indent .Bk -words -.Cm nat -.Ar nat_number -.Cm config +.Cm nat +.Ar nat_number +.Cm config .Ar nat-configuration .Ek .Ed .Pp The following parameters can be configured: .Bl -tag -width indent .It Cm ip Ar ip_address Define an ip address to use for aliasing. .It Cm if Ar nic Use ip address of NIC for aliasing, dynamically changing it if NIC's ip address changes. .It Cm log Enable logging on this nat instance. .It Cm deny_in Deny any incoming connection from outside world. .It Cm same_ports Try to leave the alias port numbers unchanged from the actual local port numbers. .It Cm unreg_only Traffic on the local network not originating from an unregistered address spaces will be ignored. .It Cm reset Reset table of the packet aliasing engine on address change. .It Cm reverse Reverse the way libalias handles aliasing. .It Cm proxy_only Obey transparent proxy rules only, packet aliasing is not performed. .It Cm skip_global Skip instance in case of global state lookup (see below). .El .Pp Some specials value can be supplied instead of .Va nat_number: .Bl -tag -width indent .It Cm global Looks up translation state in all configured nat instances. If an entry is found, packet is aliased according to that entry. If no entry was found in any of the instances, packet is passed unchanged, and no new entry will be created. See section .Sx MULTIPLE INSTANCES in .Xr natd 8 for more information. .It Cm tablearg Uses argument supplied in lookup table. See .Sx LOOKUP TABLES section below for more information on lookup tables. .El .Pp To let the packet continue after being (de)aliased, set the sysctl variable -.Va net.inet.ip.fw.one_pass +.Va net.inet.ip.fw.one_pass to 0. For more information about aliasing modes, refer to .Xr libalias 3 . See Section .Sx EXAMPLES for some examples about nat usage. .Ss REDIRECT AND LSNAT SUPPORT IN IPFW Redirect and LSNAT support follow closely the syntax used in -.Xr natd 8 . +.Xr natd 8 . See Section .Sx EXAMPLES for some examples on how to do redirect and lsnat. .Ss SCTP NAT SUPPORT SCTP nat can be configured in a similar manner to TCP through the .Nm command line tool. -The main difference is that -.Nm sctp nat +The main difference is that +.Nm sctp nat does not do port translation. Since the local and global side ports will be the same, there is no need to specify both. Ports are redirected as follows: .Bd -ragged -offset indent .Bk -words -.Cm nat -.Ar nat_number +.Cm nat +.Ar nat_number .Cm config if .Ar nic .Cm redirect_port sctp .Ar ip_address [,addr_list] {[port | port-port] [,ports]} .Ek .Ed .Pp Most .Nm sctp nat configuration can be done in real-time through the .Xr sysctl 8 interface. All may be changed dynamically, though the hash_table size will only change for new .Nm nat instances. See -.Sx SYSCTL VARIABLES +.Sx SYSCTL VARIABLES for more info. -.Sh LOADER TUNABLES +.Sh LOADER TUNABLES Tunables can be set in .Xr loader 8 prompt, .Xr loader.conf 5 or .Xr kenv 1 before ipfw module gets loaded. .Bl -tag -width indent .It Va net.inet.ip.fw.default_to_accept: No 0 Defines ipfw last rule behavior. This value overrides .Cd "options IPFW_DEFAULT_TO_(ACCEPT|DENY)" from kernel configuration file. .It Va net.inet.ip.fw.tables_max: No 128 Defines number of tables available in ipfw. Number cannot exceed 65534. .El .Sh SYSCTL VARIABLES A set of .Xr sysctl 8 variables controls the behaviour of the firewall and associated modules .Pq Nm dummynet , bridge , sctp nat . These are shown below together with their default value (but always check with the .Xr sysctl 8 command what value is actually in use) and meaning: .Bl -tag -width indent .It Va net.inet.ip.alias.sctp.accept_global_ootb_addip: No 0 -Defines how the -.Nm nat +Defines how the +.Nm nat responds to receipt of global OOTB ASCONF-AddIP: .Bl -tag -width indent .It Cm 0 No response (unless a partially matching association exists - ports and vtags match but global address does not) .It Cm 1 -.Nm nat +.Nm nat will accept and process all OOTB global AddIP messages. .El .Pp Option 1 should never be selected as this forms a security risk. An attacker can establish multiple fake associations by sending AddIP messages. .It Va net.inet.ip.alias.sctp.chunk_proc_limit: No 5 Defines the maximum number of chunks in an SCTP packet that will be parsed for a packet that matches an existing association. -This value is enforced to be greater or equal than -.Cm net.inet.ip.alias.sctp.initialising_chunk_proc_limit . +This value is enforced to be greater or equal than +.Cm net.inet.ip.alias.sctp.initialising_chunk_proc_limit . A high value is a DoS risk yet setting too low a value may result in important control chunks in the packet not being located and parsed. .It Va net.inet.ip.alias.sctp.error_on_ootb: No 1 Defines when the -.Nm nat +.Nm nat responds to any Out-of-the-Blue (OOTB) packets with ErrorM packets. An OOTB packet is a packet that arrives with no existing association registered in the -.Nm nat +.Nm nat and is not an INIT or ASCONF-AddIP packet: .Bl -tag -width indent .It Cm 0 ErrorM is never sent in response to OOTB packets. .It Cm 1 ErrorM is only sent to OOTB packets received on the local side. .It Cm 2 ErrorM is sent to the local side and on the global side ONLY if there is a partial match (ports and vtags match but the source global IP does not). -This value is only useful if the -.Nm nat +This value is only useful if the +.Nm nat is tracking global IP addresses. .It Cm 3 ErrorM is sent in response to all OOTB packets on both the local and global side (DoS risk). .El .Pp At the moment the default is 0, since the ErrorM packet is not yet supported by most SCTP stacks. When it is supported, and if not tracking global addresses, we recommend setting this value to 1 to allow -multi-homed local hosts to function with the +multi-homed local hosts to function with the .Nm nat . To track global addresses, we recommend setting this value to 2 to allow global hosts to be informed when they need to (re)send an ASCONF-AddIP. Value 3 should never be chosen (except for debugging) as the -.Nm nat +.Nm nat will respond to all OOTB global packets (a DoS risk). .It Va net.inet.ip.alias.sctp.hashtable_size: No 2003 -Size of hash tables used for -.Nm nat +Size of hash tables used for +.Nm nat lookups (100 < prime_number > 1000001). -This value sets the -.Nm hash table -size for any future created +This value sets the +.Nm hash table +size for any future created .Nm nat -instance and therefore must be set prior to creating a -.Nm nat +instance and therefore must be set prior to creating a +.Nm nat instance. The table sizes may be changed to suit specific needs. If there will be few concurrent associations, and memory is scarce, you may make these smaller. If there will be many thousands (or millions) of concurrent associations, you should make these larger. A prime number is best for the table size. The sysctl update function will adjust your input value to the next highest prime number. .It Va net.inet.ip.alias.sctp.holddown_time: No 0 Hold association in table for this many seconds after receiving a SHUTDOWN-COMPLETE. This allows endpoints to correct shutdown gracefully if a shutdown_complete is lost and retransmissions are required. .It Va net.inet.ip.alias.sctp.init_timer: No 15 Timeout value while waiting for (INIT-ACK|AddIP-ACK). This value cannot be 0. .It Va net.inet.ip.alias.sctp.initialising_chunk_proc_limit: No 2 Defines the maximum number of chunks in an SCTP packet that will be parsed when no existing association exists that matches that packet. Ideally this packet will only be an INIT or ASCONF-AddIP packet. A higher value may become a DoS risk as malformed packets can consume processing resources. .It Va net.inet.ip.alias.sctp.param_proc_limit: No 25 Defines the maximum number of parameters within a chunk that will be parsed in a packet. As for other similar sysctl variables, larger values pose a DoS risk. -.It Va net.inet.ip.alias.sctp.log_level: No 0 +.It Va net.inet.ip.alias.sctp.log_level: No 0 Level of detail in the system log messages (0 \- minimal, 1 \- event, 2 \- info, 3 \- detail, 4 \- debug, 5 \- max debug). May be a good option in high loss environments. .It Va net.inet.ip.alias.sctp.shutdown_time: No 15 Timeout value while waiting for SHUTDOWN-COMPLETE. This value cannot be 0. .It Va net.inet.ip.alias.sctp.track_global_addresses: No 0 -Enables/disables global IP address tracking within the -.Nm nat +Enables/disables global IP address tracking within the +.Nm nat and places an upper limit on the number of addresses tracked for each association: .Bl -tag -width indent .It Cm 0 Global tracking is disabled .It Cm >1 Enables tracking, the maximum number of addresses tracked for each association is limited to this value .El .Pp This variable is fully dynamic, the new value will be adopted for all newly arriving associations, existing associations are treated as they were previously. -Global tracking will decrease the number of collisions within the -.Nm nat +Global tracking will decrease the number of collisions within the +.Nm nat at a cost -of increased processing load, memory usage, complexity, and possible -.Nm nat +of increased processing load, memory usage, complexity, and possible +.Nm nat state -problems in complex networks with multiple -.Nm nats . +problems in complex networks with multiple +.Nm nats . We recommend not tracking -global IP addresses, this will still result in a fully functional +global IP addresses, this will still result in a fully functional .Nm nat . .It Va net.inet.ip.alias.sctp.up_timer: No 300 Timeout value to keep an association up with no traffic. This value cannot be 0. .It Va net.inet.ip.dummynet.expire : No 1 Lazily delete dynamic pipes/queue once they have no pending traffic. You can disable this by setting the variable to 0, in which case the pipes/queues will only be deleted when the threshold is reached. .It Va net.inet.ip.dummynet.hash_size : No 64 Default size of the hash table used for dynamic pipes/queues. This value is used when no .Cm buckets option is specified when configuring a pipe/queue. .It Va net.inet.ip.dummynet.io_fast : No 0 If set to a non-zero value, the .Dq fast mode of .Nm dummynet operation (see above) is enabled. .It Va net.inet.ip.dummynet.io_pkt Number of packets passed to .Nm dummynet . .It Va net.inet.ip.dummynet.io_pkt_drop Number of packets dropped by .Nm dummynet . .It Va net.inet.ip.dummynet.io_pkt_fast Number of packets bypassed by the .Nm dummynet scheduler. .It Va net.inet.ip.dummynet.max_chain_len : No 16 Target value for the maximum number of pipes/queues in a hash bucket. The product .Cm max_chain_len*hash_size is used to determine the threshold over which empty pipes/queues will be expired even when .Cm net.inet.ip.dummynet.expire=0 . .It Va net.inet.ip.dummynet.red_lookup_depth : No 256 .It Va net.inet.ip.dummynet.red_avg_pkt_size : No 512 .It Va net.inet.ip.dummynet.red_max_pkt_size : No 1500 Parameters used in the computations of the drop probability for the RED algorithm. .It Va net.inet.ip.dummynet.pipe_byte_limit : No 1048576 .It Va net.inet.ip.dummynet.pipe_slot_limit : No 100 The maximum queue size that can be specified in bytes or packets. These limits prevent accidental exhaustion of resources such as mbufs. If you raise these limits, you should make sure the system is configured so that sufficient resources are available. .It Va net.inet.ip.fw.autoinc_step : No 100 Delta between rule numbers when auto-generating them. The value must be in the range 1..1000. .It Va net.inet.ip.fw.curr_dyn_buckets : Va net.inet.ip.fw.dyn_buckets The current number of buckets in the hash table for dynamic rules (readonly). .It Va net.inet.ip.fw.debug : No 1 Controls debugging messages produced by .Nm . .It Va net.inet.ip.fw.default_rule : No 65535 The default rule number (read-only). By the design of .Nm , the default rule is the last one, so its number can also serve as the highest number allowed for a rule. .It Va net.inet.ip.fw.dyn_buckets : No 256 The number of buckets in the hash table for dynamic rules. Must be a power of 2, up to 65536. It only takes effect when all dynamic rules have expired, so you are advised to use a .Cm flush command to make sure that the hash table is resized. .It Va net.inet.ip.fw.dyn_count : No 3 Current number of dynamic rules (read-only). .It Va net.inet.ip.fw.dyn_keepalive : No 1 Enables generation of keepalive packets for .Cm keep-state rules on TCP sessions. A keepalive is generated to both sides of the connection every 5 seconds for the last 20 seconds of the lifetime of the rule. .It Va net.inet.ip.fw.dyn_max : No 8192 Maximum number of dynamic rules. When you hit this limit, no more dynamic rules can be installed until old ones expire. .It Va net.inet.ip.fw.dyn_ack_lifetime : No 300 .It Va net.inet.ip.fw.dyn_syn_lifetime : No 20 .It Va net.inet.ip.fw.dyn_fin_lifetime : No 1 .It Va net.inet.ip.fw.dyn_rst_lifetime : No 1 .It Va net.inet.ip.fw.dyn_udp_lifetime : No 5 .It Va net.inet.ip.fw.dyn_short_lifetime : No 30 These variables control the lifetime, in seconds, of dynamic rules. Upon the initial SYN exchange the lifetime is kept short, then increased after both SYN have been seen, then decreased again during the final FIN exchange or when a RST is received. Both .Em dyn_fin_lifetime and .Em dyn_rst_lifetime must be strictly lower than 5 seconds, the period of repetition of keepalives. The firewall enforces that. .It Va net.inet.ip.fw.enable : No 1 Enables the firewall. Setting this variable to 0 lets you run your machine without firewall even if compiled in. .It Va net.inet6.ip6.fw.enable : No 1 provides the same functionality as above for the IPv6 case. .It Va net.inet.ip.fw.one_pass : No 1 When set, the packet exiting from the .Nm dummynet pipe or from .Xr ng_ipfw 4 node is not passed though the firewall again. Otherwise, after an action, the packet is reinjected into the firewall at the next rule. .It Va net.inet.ip.fw.tables_max : No 128 Maximum number of tables. .It Va net.inet.ip.fw.verbose : No 1 Enables verbose messages. .It Va net.inet.ip.fw.verbose_limit : No 0 Limits the number of messages produced by a verbose firewall. .It Va net.inet6.ip6.fw.deny_unknown_exthdrs : No 1 If enabled packets with unknown IPv6 Extension Headers will be denied. .It Va net.link.ether.ipfw : No 0 Controls whether layer-2 packets are passed to .Nm . Default is no. .It Va net.link.bridge.ipfw : No 0 Controls whether bridged packets are passed to .Nm . Default is no. .El .Pp .Sh EXAMPLES There are far too many possible uses of .Nm so this Section will only give a small set of examples. .Pp .Ss BASIC PACKET FILTERING This command adds an entry which denies all tcp packets from .Em cracker.evil.org to the telnet port of .Em wolf.tambov.su from being forwarded by the host: .Pp .Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" .Pp This one disallows any connection from the entire cracker's network to my host: .Pp .Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" .Pp A first and efficient way to limit access (not using dynamic rules) is the use of the following rules: .Pp .Dl "ipfw add allow tcp from any to any established" .Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" .Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" .Dl "..." .Dl "ipfw add deny tcp from any to any" .Pp The first rule will be a quick match for normal TCP packets, but it will not match the initial SYN packet, which will be matched by the .Cm setup rules only for selected source/destination pairs. All other SYN packets will be rejected by the final .Cm deny rule. .Pp If you administer one or more subnets, you can take advantage of the address sets and or-blocks and write extremely compact rulesets which selectively enable services to blocks of clients, as below: .Pp .Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" .Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" .Dl "" .Dl "ipfw add allow ip from ${goodguys} to any" .Dl "ipfw add deny ip from ${badguys} to any" .Dl "... normal policies ..." .Pp The .Cm verrevpath option could be used to do automated anti-spoofing by adding the following to the top of a ruleset: .Pp .Dl "ipfw add deny ip from any to any not verrevpath in" .Pp This rule drops all incoming packets that appear to be coming to the system on the wrong interface. For example, a packet with a source address belonging to a host on a protected internal network would be dropped if it tried to enter the system from an external interface. .Pp The .Cm antispoof option could be used to do similar but more restricted anti-spoofing by adding the following to the top of a ruleset: .Pp .Dl "ipfw add deny ip from any to any not antispoof in" .Pp This rule drops all incoming packets that appear to be coming from another directly connected system but on the wrong interface. For example, a packet with a source address of .Li 192.168.0.0/24 , configured on .Li fxp0 , but coming in on .Li fxp1 would be dropped. .Ss DYNAMIC RULES In order to protect a site from flood attacks involving fake TCP packets, it is safer to use dynamic rules: .Pp .Dl "ipfw add check-state" .Dl "ipfw add deny tcp from any to any established" .Dl "ipfw add allow tcp from my-net to any setup keep-state" .Pp This will let the firewall install dynamic rules only for those connection which start with a regular SYN packet coming from the inside of our network. Dynamic rules are checked when encountering the first .Cm check-state or .Cm keep-state rule. A .Cm check-state rule should usually be placed near the beginning of the ruleset to minimize the amount of work scanning the ruleset. Your mileage may vary. .Pp To limit the number of connections a user can open you can use the following type of rules: .Pp .Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" .Dl "ipfw add allow tcp from any to me setup limit src-addr 4" .Pp The former (assuming it runs on a gateway) will allow each host on a /24 network to open at most 10 TCP connections. The latter can be placed on a server to make sure that a single client does not use more than 4 simultaneous connections. .Pp .Em BEWARE : stateful rules can be subject to denial-of-service attacks by a SYN-flood which opens a huge number of dynamic rules. The effects of such attacks can be partially limited by acting on a set of .Xr sysctl 8 variables which control the operation of the firewall. .Pp Here is a good usage of the .Cm list command to see accounting records and timestamp information: .Pp .Dl ipfw -at list .Pp or in short form without timestamps: .Pp .Dl ipfw -a list .Pp which is equivalent to: .Pp .Dl ipfw show .Pp Next rule diverts all incoming packets from 192.168.2.0/24 to divert port 5000: .Pp .Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in .Pp .Ss TRAFFIC SHAPING The following rules show some of the applications of .Nm and .Nm dummynet for simulations and the like. .Pp This rule drops random incoming packets with a probability of 5%: .Pp .Dl "ipfw add prob 0.05 deny ip from any to any in" .Pp A similar effect can be achieved making use of .Nm dummynet pipes: .Pp .Dl "ipfw add pipe 10 ip from any to any" .Dl "ipfw pipe 10 config plr 0.05" .Pp We can use pipes to artificially limit bandwidth, e.g.\& on a machine acting as a router, if we want to limit traffic from local clients on 192.168.2.0/24 we do: .Pp .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" .Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" .Pp note that we use the .Cm out modifier so that the rule is not used twice. Remember in fact that .Nm rules are checked both on incoming and outgoing packets. .Pp Should we want to simulate a bidirectional link with bandwidth limitations, the correct way is the following: .Pp .Dl "ipfw add pipe 1 ip from any to any out" .Dl "ipfw add pipe 2 ip from any to any in" .Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" .Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" .Pp The above can be very useful, e.g.\& if you want to see how your fancy Web page will look for a residential user who is connected only through a slow link. You should not use only one pipe for both directions, unless you want to simulate a half-duplex medium (e.g.\& AppleTalk, Ethernet, IRDA). It is not necessary that both pipes have the same configuration, so we can also simulate asymmetric links. .Pp Should we want to verify network performance with the RED queue management algorithm: .Pp .Dl "ipfw add pipe 1 ip from any to any" .Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" .Pp Another typical application of the traffic shaper is to introduce some delay in the communication. This can significantly affect applications which do a lot of Remote Procedure Calls, and where the round-trip-time of the connection often becomes a limiting factor much more than bandwidth: .Pp .Dl "ipfw add pipe 1 ip from any to any out" .Dl "ipfw add pipe 2 ip from any to any in" .Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" .Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" .Pp Per-flow queueing can be useful for a variety of purposes. A very simple one is counting traffic: .Pp .Dl "ipfw add pipe 1 tcp from any to any" .Dl "ipfw add pipe 1 udp from any to any" .Dl "ipfw add pipe 1 ip from any to any" .Dl "ipfw pipe 1 config mask all" .Pp The above set of rules will create queues (and collect statistics) for all traffic. Because the pipes have no limitations, the only effect is collecting statistics. Note that we need 3 rules, not just the last one, because when .Nm tries to match IP packets it will not consider ports, so we would not see connections on separate ports as different ones. .Pp A more sophisticated example is limiting the outbound traffic on a net with per-host limits, rather than per-network limits: .Pp .Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" .Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" .Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" .Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" .Ss LOOKUP TABLES In the following example, we need to create several traffic bandwidth classes and we need different hosts/networks to fall into different classes. We create one pipe for each class and configure them accordingly. Then we create a single table and fill it with IP subnets and addresses. For each subnet/host we set the argument equal to the number of the pipe that it should use. Then we classify traffic using a single rule: .Pp .Dl "ipfw pipe 1 config bw 1000Kbyte/s" .Dl "ipfw pipe 4 config bw 4000Kbyte/s" .Dl "..." .Dl "ipfw table 1 add 192.168.2.0/24 1" .Dl "ipfw table 1 add 192.168.0.0/27 4" .Dl "ipfw table 1 add 192.168.0.2 1" .Dl "..." .Dl "ipfw add pipe tablearg ip from table(1) to any" .Pp Using the .Cm fwd action, the table entries may include hostnames and IP addresses. .Pp .Dl "ipfw table 1 add 192.168.2.0/24 10.23.2.1" .Dl "ipfw table 1 add 192.168.0.0/27 router1.dmz" .Dl "..." .Dl "ipfw add 100 fwd tablearg ip from any to table(1)" .Pp In the following example per-interface firewall is created: .Pp .Dl "ipfw table 10 add vlan20 12000" .Dl "ipfw table 10 add vlan30 13000" .Dl "ipfw table 20 add vlan20 22000" .Dl "ipfw table 20 add vlan30 23000" .Dl ".." .Dl "ipfw add 100 ipfw skipto tablearg ip from any to any recv 'table(10)' in" .Dl "ipfw add 200 ipfw skipto tablearg ip from any to any xmit 'table(10)' out" .Ss SETS OF RULES To add a set of rules atomically, e.g.\& set 18: .Pp .Dl "ipfw set disable 18" .Dl "ipfw add NN set 18 ... # repeat as needed" .Dl "ipfw set enable 18" .Pp To delete a set of rules atomically the command is simply: .Pp .Dl "ipfw delete set 18" .Pp To test a ruleset and disable it and regain control if something goes wrong: .Pp .Dl "ipfw set disable 18" .Dl "ipfw add NN set 18 ... # repeat as needed" .Dl "ipfw set enable 18; echo done; sleep 30 && ipfw set disable 18" .Pp Here if everything goes well, you press control-C before the "sleep" terminates, and your ruleset will be left active. Otherwise, e.g.\& if you cannot access your box, the ruleset will be disabled after the sleep terminates thus restoring the previous situation. .Pp To show rules of the specific set: .Pp .Dl "ipfw set 18 show" .Pp To show rules of the disabled set: .Pp .Dl "ipfw -S set 18 show" .Pp To clear a specific rule counters of the specific set: .Pp .Dl "ipfw set 18 zero NN" .Pp To delete a specific rule of the specific set: .Pp .Dl "ipfw set 18 delete NN" .Ss NAT, REDIRECT AND LSNAT First redirect all the traffic to nat instance 123: .Pp .Dl "ipfw add nat 123 all from any to any" .Pp Then to configure nat instance 123 to alias all the outgoing traffic with ip 192.168.0.123, blocking all incoming connections, trying to keep -same ports on both sides, clearing aliasing table on address change +same ports on both sides, clearing aliasing table on address change and keeping a log of traffic/link statistics: .Pp .Dl "ipfw nat 123 config ip 192.168.0.123 log deny_in reset same_ports" .Pp Or to change address of instance 123, aliasing table will be cleared (see reset option): .Pp .Dl "ipfw nat 123 config ip 10.0.0.1" .Pp To see configuration of nat instance 123: .Pp .Dl "ipfw nat 123 show config" .Pp To show logs of all the instances in range 111-999: .Pp .Dl "ipfw nat 111-999 show" .Pp To see configurations of all instances: .Pp .Dl "ipfw nat show config" .Pp Or a redirect rule with mixed modes could looks like: .Pp .Dl "ipfw nat 123 config redirect_addr 10.0.0.1 10.0.0.66" .Dl " redirect_port tcp 192.168.0.1:80 500" .Dl " redirect_proto udp 192.168.1.43 192.168.1.1" .Dl " redirect_addr 192.168.0.10,192.168.0.11" .Dl " 10.0.0.100 # LSNAT" -.Dl " redirect_port tcp 192.168.0.1:80,192.168.0.10:22" +.Dl " redirect_port tcp 192.168.0.1:80,192.168.0.10:22" .Dl " 500 # LSNAT" .Pp or it could be split in: .Pp .Dl "ipfw nat 1 config redirect_addr 10.0.0.1 10.0.0.66" .Dl "ipfw nat 2 config redirect_port tcp 192.168.0.1:80 500" .Dl "ipfw nat 3 config redirect_proto udp 192.168.1.43 192.168.1.1" -.Dl "ipfw nat 4 config redirect_addr 192.168.0.10,192.168.0.11,192.168.0.12" +.Dl "ipfw nat 4 config redirect_addr 192.168.0.10,192.168.0.11,192.168.0.12" .Dl " 10.0.0.100" .Dl "ipfw nat 5 config redirect_port tcp" .Dl " 192.168.0.1:80,192.168.0.10:22,192.168.0.20:25 500" .Pp .Sh SEE ALSO .Xr cpp 1 , .Xr m4 1 , .Xr altq 4 , .Xr divert 4 , .Xr dummynet 4 , .Xr if_bridge 4 , .Xr ip 4 , .Xr ipfirewall 4 , .Xr ng_ipfw 4 , .Xr protocols 5 , .Xr services 5 , .Xr init 8 , .Xr kldload 8 , .Xr reboot 8 , .Xr sysctl 8 , .Xr syslogd 8 .Sh HISTORY The .Nm utility first appeared in .Fx 2.0 . .Nm dummynet was introduced in .Fx 2.2.8 . Stateful extensions were introduced in .Fx 4.0 . .Nm ipfw2 was introduced in Summer 2002. .Sh AUTHORS .An Ugen J. S. Antsilevich , .An Poul-Henning Kamp , .An Alex Nash , .An Archie Cobbs , .An Luigi Rizzo . .Pp .An -nosplit API based upon code written by .An Daniel Boulet for BSDI. .Pp Dummynet has been introduced by Luigi Rizzo in 1997-1998. .Pp Some early work (1999-2000) on the .Nm dummynet traffic shaper supported by Akamba Corp. .Pp The ipfw core (ipfw2) has been completely redesigned and reimplemented by Luigi Rizzo in summer 2002. Further actions and options have been added by various developer over the years. .Pp .An -nosplit In-kernel NAT support written by .An Paolo Pisati Aq piso@FreeBSD.org as part of a Summer of Code 2005 project. .Pp SCTP .Nm nat support has been developed by .An The Centre for Advanced Internet Architectures (CAIA) Aq http://www.caia.swin.edu.au . The primary developers and maintainers are David Hayes and Jason But. For further information visit: .Aq http://www.caia.swin.edu.au/urp/SONATA .Pp Delay profiles have been developed by Alessandro Cerri and Luigi Rizzo, supported by the European Commission within Projects Onelab and Onelab2. .Sh BUGS The syntax has grown over the years and sometimes it might be confusing. Unfortunately, backward compatibility prevents cleaning up mistakes made in the definition of the syntax. .Pp .Em !!! WARNING !!! .Pp Misconfiguring the firewall can put your computer in an unusable state, possibly shutting down network services and requiring console access to regain control of it. .Pp Incoming packet fragments diverted by .Cm divert are reassembled before delivery to the socket. The action used on those packet is the one from the rule which matches the first fragment of the packet. .Pp Packets diverted to userland, and then reinserted by a userland process may lose various packet attributes. The packet source interface name will be preserved if it is shorter than 8 bytes and the userland process saves and reuses the sockaddr_in (as does .Xr natd 8 ) ; otherwise, it may be lost. If a packet is reinserted in this manner, later rules may be incorrectly applied, making the order of .Cm divert rules in the rule sequence very important. .Pp Dummynet drops all packets with IPv6 link-local addresses. .Pp Rules using .Cm uid or .Cm gid may not behave as expected. In particular, incoming SYN packets may have no uid or gid associated with them since they do not yet belong to a TCP connection, and the uid/gid associated with a packet may not be as expected if the associated process calls .Xr setuid 2 or similar system calls. .Pp Rule syntax is subject to the command line environment and some patterns may need to be escaped with the backslash character or quoted appropriately. .Pp -Due to the architecture of -.Xr libalias 3 , +Due to the architecture of +.Xr libalias 3 , ipfw nat is not compatible with the TCP segmentation offloading (TSO). Thus, to reliably nat your network traffic, please disable TSO on your NICs using .Xr ifconfig 8 . .Pp ICMP error messages are not implicitly matched by dynamic rules for the respective conversations. To avoid failures of network error detection and path MTU discovery, ICMP error messages may need to be allowed explicitly through static rules. .Pp Rules using .Cm call and .Cm return actions may lead to confusing behaviour if ruleset has mistakes, and/or interaction with other subsystems (netgraph, dummynet, etc.) is used. One possible case for this is packet leaving .Nm in subroutine on the input pass, while later on output encountering unpaired .Cm return first. As the call stack is kept intact after input pass, packet will suddenly return to the rule number used on input pass, not on output one. Order of processing should be checked carefully to avoid such mistakes. Index: stable/9/sbin/ipfw =================================================================== --- stable/9/sbin/ipfw (revision 237215) +++ stable/9/sbin/ipfw (revision 237216) Property changes on: stable/9/sbin/ipfw ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin/ipfw:r233648 Index: stable/9/sbin/mdmfs/mdmfs.8 =================================================================== --- stable/9/sbin/mdmfs/mdmfs.8 (revision 237215) +++ stable/9/sbin/mdmfs/mdmfs.8 (revision 237216) @@ -1,377 +1,377 @@ .\" .\" Copyright (c) 2001 Dima Dorfman. .\" 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. .\" .\" $FreeBSD$ .\" .Dd September 4, 2011 .Dt MDMFS 8 .Os .Sh NAME .Nm mdmfs , .Nm mount_mfs .Nd configure and mount an in-memory file system using the .Xr md 4 driver .Sh SYNOPSIS .Nm .Op Fl DLlMNPStUX .Op Fl a Ar maxcontig .Op Fl b Ar block-size .Op Fl c Ar blocks-per-cylinder-group -.Op Fl d Ar max-extent-size +.Op Fl d Ar max-extent-size .Op Fl E Ar path-mdconfig .Op Fl e Ar maxbpg .Op Fl F Ar file .Op Fl f Ar frag-size .Op Fl i Ar bytes .Op Fl m Ar percent-free .Op Fl n Ar rotational-positions .Op Fl O Ar optimization .Op Fl o Ar mount-options .Op Fl p Ar permissions .Op Fl s Ar size .Op Fl v Ar version .Op Fl w Ar user : Ns Ar group .Ar md-device .Ar mount-point .Sh DESCRIPTION The .Nm utility is designed to be a work-alike and look-alike of the deprecated .Xr mount_mfs 8 . The end result is essentially the same, but is accomplished in a completely different way. The .Nm utility configures an .Xr md 4 disk using .Xr mdconfig 8 , puts a UFS file system on it (unless .Fl P was specified) using .Xr newfs 8 , and mounts it using .Xr mount 8 . -It can handle -.Xr geom_uzip 4 +It can handle +.Xr geom_uzip 4 compressed disk images, as long as the kernel supports this GEOM class. All the command line options are passed to the appropriate program at the appropriate stage in order to achieve the desired effect. .Pp By default, .Nm creates a swap-based .Pq Dv MD_SWAP disk with soft-updates enabled and mounts it on .Ar mount-point . It uses the .Xr md 4 device specified by .Ar md-device . If .Ar md-device is .Ql md (no unit number), it will use .Xr md 4 Ns 's auto-unit feature to automatically select an unused device. Unless otherwise specified with one of the options below, it uses the default arguments to all the helper programs. .Pp The following options are available. Where possible, the option letter matches the one used by .Xr mount_mfs 8 for the same thing. .Bl -tag -width indent .It Fl a Ar maxcontig Specify the maximum number of contiguous blocks that will be laid out before forcing a rotational delay (see the .Fl d option). .It Fl b Ar block-size The block size of the file system, in bytes. .It Fl c Ar blocks-per-cylinder-group The number of blocks per cylinder group in the file system. .It Fl D If not using auto-unit, do not run .Xr mdconfig 8 to try to detach the unit before attaching it. .It Fl d Ar max-extent-size The file system may choose to store large files using extents. This parameter specifies the largest extent size that may be used. It is presently limited to its default value which is 16 times the file system blocksize. .It Fl E Ar path-mdconfig Use .Ar path-mdconfig as a location of the .Xr mdconfig 8 utility. .It Fl e Ar maxbpg Indicate the maximum number of blocks any single file can allocate out of a cylinder group before it is forced to begin allocating blocks from another cylinder group. .It Fl F Ar file Create a vnode-backed .Pq Dv MD_VNODE memory disk backed by .Ar file . .It Fl f Ar frag-size The fragment size of the file system in bytes. .It Fl i Ar bytes Number of bytes per inode. .It Fl l Enable multilabel MAC on the new file system. .It Fl L Show the output of the helper programs. By default, it is sent to .Pa /dev/null . .It Fl M Create a .Xr malloc 9 backed disk .Pq Dv MD_MALLOC instead of a swap-backed disk. .It Fl m Ar percent-free The percentage of space reserved for the superuser. .It Fl N Do not actually run the helper programs. This is most useful in conjunction with .Fl X . .It Fl n Ar rotational-positions The default number of rotational positions to distinguish. .It Fl O Ar optimization Select the optimization preference; valid choices are .Cm space and .Cm time , which will optimize for minimum space fragmentation and minimum time spent allocating blocks, respectively. .It Fl o Ar mount-options Specify the mount options with which to mount the file system. See .Xr mount 8 for more information. .It Fl P Preserve the existing file system; do not run .Xr newfs 8 . This only makes sense if .Fl F is specified to create a vnode-backed disk. .It Fl p Ar permissions Set the file (directory) permissions of the mount point .Ar mount-point to .Ar permissions . The .Ar permissions argument can be in any of the mode formats recognized by .Xr chmod 1 . If symbolic permissions are specified, the operation characters .Dq + and .Dq - are interpreted relative to the initial permissions of .Dq a=rwx . .It Fl S Do not enable soft-updates on the file system. .It Fl s Ar size Specify the size of the disk to create. This only makes sense if .Fl F is .Em not specified. That is, this will work for the default swap-backed .Pq Dv MD_SWAP disks, and the optional .Pq Fl M .Xr malloc 9 backed disks .Pq Dv MD_MALLOC . .It Fl t Turn on the TRIM enable flag for .Xr newfs 8 . The .Xr md 4 device supports the BIO_DELETE command, enabling the TRIM on created filesystem allows return of freed memory to the system pool. .It Fl U Enable soft-updates on the file system. This is the default, and is accepted only for compatibility. It is only really useful to negate the .Fl S flag, should such a need occur. .It Fl v Ar version Specify the UFS version number for use on the file system; it may be either .Dv 1 or .Dv 2 . The default is derived from the default of the .Xr newfs 8 command. .It Fl w Ar user : Ns Ar group Set the owner and group to .Ar user and .Ar group , respectively. The arguments have the same semantics as with .Xr chown 8 , but specifying just a .Ar user or just a .Ar group is not supported. .It Fl X Print what command will be run before running it, and other assorted debugging information. .El .Pp The .Fl F and .Fl s options are passed to .Xr mdconfig 8 as .Fl f and .Fl s , respectively. The .Fl a , b , c , d , e , f , i , m and .Fl n options are passed to .Xr newfs 8 with the same letter; the .Fl O option is passed to .Xr newfs 8 as .Fl o . The .Fl o option is passed to .Xr mount 8 with the same letter. See the programs that the options are passed to for more information on their semantics. .Sh EXAMPLES Create and mount a 32 megabyte swap-backed file system on .Pa /tmp : .Pp .Dl "mdmfs -s 32m md /tmp" .Pp The same file system created as an entry in .Pa /etc/fstab : .Pp .Dl "md /tmp mfs rw,-s32m 2 0" .Pp Create and mount a 16 megabyte malloc-backed file system on .Pa /tmp using the .Pa /dev/md1 device; furthermore, do not use soft-updates on it and mount it .Cm async : .Pp .Dl "mdmfs -M -S -o async -s 16m md1 /tmp" .Pp -Create and mount a +Create and mount a .Xr geom_uzip 4 based compressed disk image: .Pp .Dl "mdmfs -P -F foo.uzip -oro md.uzip /tmp/" .Pp Mount the same image, specifying the .Pa /dev/md1 device: .Pp .Dl "mdmfs -P -F foo.uzip -oro md1.uzip /tmp/" .Pp Configure a vnode-backed file system and mount its first partition, using automatic device numbering: .Pp .Dl "mdmfs -P -F foo.img mds1a /tmp/" .Sh COMPATIBILITY The .Nm utility, while designed to be compatible with .Xr mount_mfs 8 , can be useful by itself. Since .Xr mount_mfs 8 had some silly defaults, a .Dq compatibility mode is provided for the case where bug-to-bug compatibility is desired. .Pp Compatibility is enabled by starting .Nm with the name .Li mount_mfs or .Li mfs (as returned by .Xr getprogname 3 ) . In this mode, the following behavior, as done by .Xr mount_mfs 8 , is duplicated: .Bl -bullet -offset indent .It The file mode of .Ar mount-point is set by default to .Li 01777 as if .Fl p Ar 1777 was given on the command line. .El .Sh SEE ALSO .Xr md 4 , .Xr fstab 5 , .Xr mdconfig 8 , .Xr mount 8 , .Xr newfs 8 .Sh AUTHORS .An Dima Dorfman Index: stable/9/sbin/mdmfs =================================================================== --- stable/9/sbin/mdmfs (revision 237215) +++ stable/9/sbin/mdmfs (revision 237216) Property changes on: stable/9/sbin/mdmfs ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/quota64/sbin/mdmfs:r184125-207707 Merged /projects/largeSMP/sbin/mdmfs:r221273-222812,222815-223757 Merged /head/sbin/mdmfs:r2-3,227006,233648 Merged /user/piso/sbin/mdmfs:r186725 Merged /vendor/resolver/dist/sbin/mdmfs:r1540-186085 Index: stable/9/sbin/mount_unionfs/mount_unionfs.8 =================================================================== --- stable/9/sbin/mount_unionfs/mount_unionfs.8 (revision 237215) +++ stable/9/sbin/mount_unionfs/mount_unionfs.8 (revision 237216) @@ -1,395 +1,395 @@ .\" Copyright (c) 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software donated to Berkeley by .\" Jan-Simon Pendry. .\" .\" 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. .\" 4. 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. .\" .\" @(#)mount_union.8 8.6 (Berkeley) 3/27/94 .\" $FreeBSD$ .\" .Dd November 30, 2006 .Dt MOUNT_UNIONFS 8 .Os .Sh NAME .Nm mount_unionfs .Nd mount union file systems .Sh SYNOPSIS .Nm .Op Fl b .Op Fl o Ar options .Ar directory .Ar uniondir .Sh DESCRIPTION The .Nm utility attaches .Ar directory above .Ar uniondir in such a way that the contents of both directory trees remain visible. By default, .Ar directory becomes the .Em upper layer and .Ar uniondir becomes the .Em lower layer. .Pp The options are as follows: .Bl -tag -width indent .It Fl b Deprecated. Use .Fl o Cm below instead. .It Fl o Options are specified with the .Fl o flag followed by an option. The following options are available: .Bl -tag -width indent .It Cm below Inverts the default position, so that .Ar directory becomes the lower layer and .Ar uniondir becomes the upper layer. However, .Ar uniondir remains the mount point. .It Sm Cm copymode No = Cm traditional | transparent | masquerade Sm Specifies the way to create a file or a directory in the upper layer automatically when needed. The .Cm traditional mode uses the same way as the old unionfs for backward compatibility, and .Cm transparent duplicates the file and directory mode bits and the ownership in the lower layer to the created file in the upper layer. For behavior of the .Cm masquerade mode, see .Sx MASQUERADE MODE below. .It Sm Cm whiteout No = Cm always | whenneeded Sm Specifies whether whiteouts should always be made in the upper layer when removing a file or directory or only when it already exists in the lower layer. .It Cm udir Ns = Ns Ar mode Specifies directory mode bits in octal for .Cm masquerade mode. .It Cm ufile Ns = Ns Ar mode Specifies file mode bits in octal for .Cm masquerade mode. .It Cm gid Ns = Ns Ar gid Specifies group for .Cm masquerade mode. .It Cm uid Ns = Ns Ar uid Specifies user for .Cm masquerade mode. .El .El .Pp To enforce file system security, the user mounting a file system must be superuser or else have write permission on the mounted-on directory. In addition, the .Va vfs.usermount .Xr sysctl 8 variable must be set to 1 to permit file system mounting by ordinary users. However, note that .Cm transparent and .Cm masquerade modes require .Va vfs.usermount to be set to 0 because this functionality can only be used by superusers. .Pp Filenames are looked up in the upper layer and then in the lower layer. If a directory is found in the lower layer, and there is no entry in the upper layer, then a .Em shadow directory will be created in the upper layer. The ownership and the mode bits are set depending on the .Cm copymode option. In .Cm traditional mode, it will be owned by the user who originally did the union mount, with mode 0777 .Pq Dq Li rwxrwxrwx modified by the umask in effect at that time. .Pp If a file exists in the upper layer then there is no way to access a file with the same name in the lower layer. If necessary, a combination of loopback and union mounts can be made which will still allow the lower files to be accessed by a different pathname. .Pp Except in the case of a directory, access to an object is granted via the normal file system access checks. For directories, the current user must have access to both the upper and lower directories (should they both exist). .Pp Requests to create or modify objects in .Ar uniondir are passed to the upper layer with the exception of a few special cases. An attempt to open for writing a file which exists in the lower layer causes a copy of the .Em entire file to be made to the upper layer, and then for the upper layer copy to be opened. Similarly, an attempt to truncate a lower layer file to zero length causes an empty file to be created in the upper layer. Any other operation which would ultimately require modification to the lower layer fails with .Er EROFS . .Pp The union file system manipulates the namespace, rather than individual file systems. The union operation applies recursively down the directory tree now rooted at .Ar uniondir . Thus any file systems which are mounted under .Ar uniondir will take part in the union operation. This differs from the .Cm union option to .Xr mount 8 which only applies the union operation to the mount point itself, and then only for lookups. .Sh MASQUERADE MODE When a file (or a directory) is created in the upper layer, the .Cm masquerade mode sets it the fixed access mode bits given in .Cm ufile (for files) or .Cm udir (for directories) option and the owner given in .Cm udir and .Cm gid options, instead of ones in the lower layer. Note that in the .Cm masquerade mode and when owner of the file or directory matches one specified in .Cm uid option, only mode bits for the owner will be modified. More specifically, the file mode bits in the upper layer will be (mode in the lower layer) OR (mode given in .Cm ufile AND 0700), and the ownership will be the same as one in the lower layer. .Pp The default values for .Cm ufile , udir , uid , and .Cm gid are as follow: .Pp .Bl -bullet -compact .It If none of .Cm ufile and .Cm udir were specified, access mode bits in the mount point will be used. .It If none of .Cm uid and .Cm gid were specified, ownership in the mount point will be used. .It If one of .Cm udir or .Cm ufile is not specified, the value of the other option will be used. .It If one of .Cm uid or .Cm gid is not specified, the value of the other option will be used. .El .Sh EXAMPLES The commands .Bd -literal -offset indent mount -t cd9660 -o ro /dev/cd0 /usr/src mount -t unionfs -o noatime /var/obj /usr/src .Ed .Pp mount the CD-ROM drive .Pa /dev/cd0 on .Pa /usr/src and then attaches .Pa /var/obj on top. For most purposes the effect of this is to make the source tree appear writable even though it is stored on a CD-ROM. The .Fl o Cm noatime option is useful to avoid unnecessary copying from the lower to the upper layer. .Pp The commands .Bd -literal -offset indent mount -t cd9660 -o ro /dev/cd0 /usr/src chown 2020 /usr/src mount -t unionfs -o noatime -o copymode=masquerade -o uid=builder \\ -o udir=755 -o ufile=644 /var/obj /usr/src .Ed .Pp also mount the CD-ROM drive .Pa /dev/cd0 on .Pa /usr/src and then attaches .Pa /var/obj on top. Furthermore, the owner of all files and directories in .Pa /usr/src is a regular user with UID 2020 when seen from the upper layer. Note that for the access mode bits, ones in the lower layer (on the CD-ROM, in this example) are still used without change. Thus, write privilege to the upper layer can be controlled independently from access mode bits and ownership in the lower layer. If a user does not have read privilege from the lower layer, one cannot still read even when the upper layer is mounted by using .Cm masquerade mode. .Pp The command .Bd -literal -offset indent mount -t unionfs -o noatime -o below /sys $HOME/sys .Ed .Pp attaches the system source tree below the .Pa sys directory in the user's home directory. This allows individual users to make private changes to the source, and build new kernels, without those changes becoming visible to other users. Note that the files in the lower layer remain accessible via .Pa /sys . .Sh SEE ALSO .Xr intro 2 , .Xr mount 2 , .Xr unmount 2 , .Xr fstab 5 , .Xr mount 8 , .Xr mount_nullfs 8 .Sh HISTORY The .Nm utility first appeared in .Bx 4.4 . .Pp The .Fl r option for hiding the lower layer completely was removed in .Fx 7.0 because this is identical to using .Xr mount_nullfs 8 . .Sh AUTHORS .An -nosplit In .Fx 7.0 , .An Masanori OZAWA Aq ozawa@ongs.co.jp reimplemented handling of locking, whiteout, and file mode bits, and .An Hiroki Sato Aq hrs@FreeBSD.org wrote about the changes in this manual page. .Sh BUGS THIS FILE SYSTEM TYPE IS NOT YET FULLY SUPPORTED (READ: IT DOESN'T WORK) AND USING IT MAY, IN FACT, DESTROY DATA ON YOUR SYSTEM. USE AT YOUR OWN RISK. BEWARE OF DOG. SLIPPERY WHEN WET. BATTERIES NOT INCLUDED. .Pp This code also needs an owner in order to be less dangerous - serious hackers can apply by sending mail to .Aq freebsd-fs@FreeBSD.org and announcing their intent to take it over. .Pp Without whiteout support from the file system backing the upper layer, there is no way that delete and rename operations on lower layer objects can be done. .Er EOPNOTSUPP is returned for this kind of operations as generated by VOP_WHITEOUT() -along with any others which would make modifications to the lower +along with any others which would make modifications to the lower layer, such as .Xr chmod 1 . .Pp Running .Xr find 1 over a union tree has the side-effect of creating a tree of shadow directories in the upper layer. .Pp The current implementation does not support copying extended attributes for .Xr acl 9 , .Xr mac 9 , or so on to the upper layer. Note that this may be a security issue. .Pp A shadow directory, which is one automatically created in the upper layer when it exists in the lower layer and does not exist in the upper layer, is always created with the superuser privilege. However, a file copied from the lower layer in the same way is created by the user who accessed it. Because of this, if the user is not the superuser, even in .Cm transparent mode the access mode bits in the copied file in the upper layer will not always be the same as ones in the lower layer. This behavior should be fixed. Index: stable/9/sbin/mount_unionfs =================================================================== --- stable/9/sbin/mount_unionfs (revision 237215) +++ stable/9/sbin/mount_unionfs (revision 237216) Property changes on: stable/9/sbin/mount_unionfs ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/largeSMP/sbin/mount_unionfs:r221273-222812,222815-223757 Merged /vendor/resolver/dist/sbin/mount_unionfs:r1540-186085 Merged /projects/quota64/sbin/mount_unionfs:r184125-207707 Merged /head/sbin/mount_unionfs:r2-3,227006,233648 Merged /user/piso/sbin/mount_unionfs:r186725 Index: stable/9/sbin/ping6/ping6.8 =================================================================== --- stable/9/sbin/ping6/ping6.8 (revision 237215) +++ stable/9/sbin/ping6/ping6.8 (revision 237216) @@ -1,532 +1,532 @@ .\" $KAME: ping6.8,v 1.58 2003/06/20 12:00:22 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. .\" 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 project 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 PROJECT 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 PROJECT 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 20, 2010 .Dt PING6 8 .Os .Sh NAME .Nm ping6 .Nd send .Tn ICMPv6 ECHO_REQUEST packets to network hosts .Sh SYNOPSIS .Nm .\" without ipsec, or new ipsec .Op Fl DdfHmnNoqrRtvwW .\" old ipsec .\" .Op Fl ADdEfmnNqRtvwW .Bk -words .Op Fl a Ar addrtype .Ek .Bk -words .Op Fl b Ar bufsiz .Ek .Bk -words .Op Fl c Ar count .Ek .Bk -words .Op Fl g Ar gateway .Ek .Bk -words .Op Fl h Ar hoplimit .Ek .Bk -words .Op Fl I Ar interface .Ek .Bk -words .Op Fl i Ar wait .Ek .Bk -words .Op Fl l Ar preload .Ek .Bk -words .\" new ipsec .Op Fl P Ar policy .Ek .Bk -words .Op Fl p Ar pattern .Ek .Bk -words .Op Fl S Ar sourceaddr .Ek .Bk -words .Op Fl s Ar packetsize .Ek .Bk -words .Op Ar hops ... .Ek .Bk -words .Ar host .Ek .Sh DESCRIPTION The .Nm utility uses the .Tn ICMPv6 protocol's mandatory .Tn ICMP6_ECHO_REQUEST datagram to elicit an .Tn ICMP6_ECHO_REPLY from a host or gateway. .Tn ICMP6_ECHO_REQUEST datagrams (``pings'') have an IPv6 header, and .Tn ICMPv6 header formatted as documented in RFC2463. The options are as follows: .Bl -tag -width Ds .\" old ipsec .\" .It Fl A .\" Enables transport-mode IPsec authentication header .\" (experimental). .It Fl a Ar addrtype Generate ICMPv6 Node Information Node Addresses query, rather than echo-request. .Ar addrtype must be a string constructed of the following characters. .Bl -tag -width Ds -compact .It Ic a requests unicast addresses from all of the responder's interfaces. If the character is omitted, only those addresses which belong to the interface which has the responder's address are requests. .It Ic c requests responder's IPv4-compatible and IPv4-mapped addresses. .It Ic g requests responder's global-scope addresses. .It Ic s requests responder's site-local addresses. .It Ic l requests responder's link-local addresses. .It Ic A requests responder's anycast addresses. Without this character, the responder will return unicast addresses only. With this character, the responder will return anycast addresses only. Note that the specification does not specify how to get responder's anycast addresses. This is an experimental option. .El .It Fl b Ar bufsiz Set socket buffer size. .It Fl c Ar count Stop after sending (and receiving) .Ar count .Tn ECHO_RESPONSE packets. .It Fl D Disable IPv6 fragmentation. .It Fl d Set the .Dv SO_DEBUG option on the socket being used. .\" .It Fl E .\" Enables transport-mode IPsec encapsulated security payload .\" (experimental). .It Fl f Flood ping. Outputs packets as fast as they come back or one hundred times per second, whichever is more. For every .Tn ECHO_REQUEST sent a period .Dq \&. is printed, while for every .Tn ECHO_REPLY received a backspace is printed. This provides a rapid display of how many packets are being dropped. Only the super-user may use this option. .Bf -emphasis This can be very hard on a network and should be used with caution. .Ef .It Fl g Ar gateway Specifies to use .Ar gateway as the next hop to the destination. The gateway must be a neighbor of the sending node. .It Fl H Specifies to try reverse-lookup of IPv6 addresses. The .Nm utility does not try reverse-lookup unless the option is specified. .It Fl h Ar hoplimit Set the IPv6 hoplimit. .It Fl I Ar interface Source packets with the given interface address. This flag applies if the ping destination is a multicast address, or link-local/site-local unicast address. .It Fl i Ar wait Wait .Ar wait seconds .Em between sending each packet . The default is to wait for one second between each packet. This option is incompatible with the .Fl f option. .It Fl l Ar preload If .Ar preload is specified, .Nm sends that many packets as fast as possible before falling into its normal mode of behavior. Only the super-user may use this option. .It Fl m By default, .Nm asks the kernel to fragment packets to fit into the minimum IPv6 MTU. The .Fl m option will suppress the behavior in the following two levels: when the option is specified once, the behavior will be disabled for unicast packets. When the option is more than once, it will be disabled for both unicast and multicast packets. .It Fl n Numeric output only. No attempt will be made to lookup symbolic names from addresses in the reply. .It Fl N Probe node information multicast group .Pq Li ff02::2:xxxx:xxxx . .Ar host must be string hostname of the target (must not be a numeric IPv6 address). Node information multicast group will be computed based on given .Ar host , and will be used as the final destination. Since node information multicast group is a link-local multicast group, outgoing interface needs to be specified by .Fl I option. .It Fl o Exit successfully after receiving one reply packet. .It Fl p Ar pattern You may specify up to 16 .Dq pad bytes to fill out the packet you send. This is useful for diagnosing data-dependent problems in a network. For example, .Dq Li \-p ff will cause the sent packet to be filled with all ones. .\" new ipsec .It Fl P Ar policy .Ar policy specifies IPsec policy to be used for the probe. .It Fl q Quiet output. Nothing is displayed except the summary lines at startup time and when finished. .It Fl r Audible. Include a bell .Tn ( ASCII 0x07) character in the output when any packet is received. .It Fl R Audible. Output a bell .Tn ( ASCII 0x07) character when no packet is received before the next packet is transmitted. To cater for round-trip times that are longer than the interval between transmissions, further missing packets cause a bell only if the maximum number of unreceived packets has increased. .It Fl S Ar sourceaddr Specifies the source address of request packets. The source address must be one of the unicast addresses of the sending node, and must be numeric. .It Fl s Ar packetsize Specifies the number of data bytes to be sent. The default is 56, which translates into 64 .Tn ICMP data bytes when combined with the 8 bytes of .Tn ICMP header data. You may need to specify .Fl b as well to extend socket buffer size. .It Fl t Generate ICMPv6 Node Information supported query types query, rather than echo-request. .Fl s has no effect if .Fl t is specified. .It Fl v Verbose output. .Tn ICMP packets other than .Tn ECHO_RESPONSE that are received are listed. .It Fl w Generate ICMPv6 Node Information DNS Name query, rather than echo-request. .Fl s has no effect if .Fl w is specified. .It Fl W Same as .Fl w , but with old packet format based on 03 draft. This option is present for backward compatibility. .Fl s has no effect if .Fl w is specified. .It Ar hops IPv6 addresses for intermediate nodes, which will be put into type 0 routing header. .It Ar host IPv6 address of the final destination node. .El .Pp When using .Nm for fault isolation, it should first be run on the local host, to verify that the local network interface is up and running. Then, hosts and gateways further and further away should be .Dq pinged . Round-trip times and packet loss statistics are computed. If duplicate packets are received, they are not included in the packet loss calculation, although the round trip time of these packets is used in calculating the round-trip time statistics. When the specified number of packets have been sent (and received) or if the program is terminated with a .Dv SIGINT , a brief summary is displayed, showing the number of packets sent and received, and the minimum, mean, maximum, and standard deviation of the round-trip times. .Pp If .Nm receives a .Dv SIGINFO (see the .Cm status argument for .Xr stty 1 ) signal, the current number of packets sent and received, and the minimum, mean, maximum, and standard deviation of the round-trip times will be written to the standard output in the same format as the standard completion message. .Pp This program is intended for use in network testing, measurement and management. Because of the load it can impose on the network, it is unwise to use .Nm during normal operations or from automated scripts. .\" .Sh ICMP PACKET DETAILS .\" An IP header without options is 20 bytes. .\" An .\" .Tn ICMP .\" .Tn ECHO_REQUEST .\" packet contains an additional 8 bytes worth of .\" .Tn ICMP .\" header followed by an arbitrary amount of data. .\" When a .\" .Ar packetsize .\" is given, this indicated the size of this extra piece of data .\" (the default is 56). .\" Thus the amount of data received inside of an IP packet of type .\" .Tn ICMP .\" .Tn ECHO_REPLY .\" will always be 8 bytes more than the requested data space .\" (the .\" .Tn ICMP .\" header). .\" .Pp .\" If the data space is at least eight bytes large, .\" .Nm .\" uses the first eight bytes of this space to include a timestamp which .\" it uses in the computation of round trip times. .\" If less than eight bytes of pad are specified, no round trip times are .\" given. .Sh DUPLICATE AND DAMAGED PACKETS The .Nm utility will report duplicate and damaged packets. Duplicate packets should never occur when pinging a unicast address, and seem to be caused by inappropriate link-level retransmissions. Duplicates may occur in many situations and are rarely (if ever) a good sign, although the presence of low levels of duplicates may not always be cause for alarm. Duplicates are expected when pinging a broadcast or multicast address, since they are not really duplicates but replies from different hosts to the same request. .Pp Damaged packets are obviously serious cause for alarm and often indicate broken hardware somewhere in the .Nm packet's path (in the network or in the hosts). .Sh TRYING DIFFERENT DATA PATTERNS The (inter)network layer should never treat packets differently depending on the data contained in the data portion. Unfortunately, data-dependent problems have been known to sneak into networks and remain undetected for long periods of time. In many cases the particular pattern that will have problems is something that does not have sufficient .Dq transitions , such as all ones or all zeros, or a pattern right at the edge, such as almost all zeros. It is not necessarily enough to specify a data pattern of all zeros (for example) on the command line because the pattern that is of interest is at the data link level, and the relationship between what you type and what the controllers transmit can be complicated. .Pp This means that if you have a data-dependent problem you will probably have to do a lot of testing to find it. If you are lucky, you may manage to find a file that either cannot be sent across your network or that takes much longer to transfer than other similar length files. You can then examine this file for repeated patterns that you can test using the .Fl p option of .Nm . .Sh EXIT STATUS The .Nm utility returns 0 on success (the host is alive), 2 if the transmission was successful but no responses were received, -any other non-zero value if the arguments are incorrect or -another error has occurred. +any other non-zero value if the arguments are incorrect or +another error has occurred. .Sh EXAMPLES Normally, .Nm works just like .Xr ping 8 would work; the following will send ICMPv6 echo request to .Li dst.foo.com . .Bd -literal -offset indent ping6 -n dst.foo.com .Ed .Pp The following will probe hostnames for all nodes on the network link attached to .Li wi0 interface. The address .Li ff02::1 is named the link-local all-node multicast address, and the packet would reach every node on the network link. .Bd -literal -offset indent ping6 -w ff02::1%wi0 .Ed .Pp The following will probe addresses assigned to the destination node, .Li dst.foo.com . .Bd -literal -offset indent ping6 -a agl dst.foo.com .Ed .Sh SEE ALSO .Xr netstat 1 , .Xr icmp6 4 , .Xr inet6 4 , .Xr ip6 4 , .Xr ifconfig 8 , .Xr ping 8 , .Xr routed 8 , .Xr traceroute 8 , .Xr traceroute6 8 .Rs .%A A. Conta .%A S. Deering .%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification" .%N RFC2463 .%D December 1998 .Re .Rs .%A Matt Crawford .%T "IPv6 Node Information Queries" .%N draft-ietf-ipngwg-icmp-name-lookups-09.txt .%D May 2002 .%O work in progress material .Re .Sh HISTORY The .Xr ping 8 utility appeared in .Bx 4.3 . The .Nm utility with IPv6 support first appeared in the WIDE Hydrangea IPv6 protocol stack kit. .Pp IPv6 and IPsec support based on the KAME Project .Pq Pa http://www.kame.net/ stack was initially integrated into .Fx 4.0 . .Sh BUGS The .Nm utility is intentionally separate from .Xr ping 8 . .Pp There have been many discussions on why we separate .Nm and .Xr ping 8 . Some people argued that it would be more convenient to uniform the ping command for both IPv4 and IPv6. The followings are an answer to the request. .Pp From a developer's point of view: since the underling raw sockets API is totally different between IPv4 and IPv6, we would end up having two types of code base. There would actually be less benefit to uniform the two commands into a single command from the developer's standpoint. .Pp From an operator's point of view: unlike ordinary network applications like remote login tools, we are usually aware of address family when using network management tools. We do not just want to know the reachability to the host, but want to know the reachability to the host via a particular network protocol such as IPv6. Thus, even if we had a unified .Xr ping 8 command for both IPv4 and IPv6, we would usually type a .Fl 6 or .Fl 4 option (or something like those) to specify the particular address family. This essentially means that we have two different commands. Index: stable/9/sbin/ping6 =================================================================== --- stable/9/sbin/ping6 (revision 237215) +++ stable/9/sbin/ping6 (revision 237216) Property changes on: stable/9/sbin/ping6 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sbin/ping6:r233648 Index: stable/9/sbin/quotacheck/quotacheck.8 =================================================================== --- stable/9/sbin/quotacheck/quotacheck.8 (revision 237215) +++ stable/9/sbin/quotacheck/quotacheck.8 (revision 237216) @@ -1,203 +1,203 @@ .\" Copyright (c) 1983, 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Robert Elz at The University of Melbourne. .\" .\" 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. .\" 4. 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. .\" .\" @(#)quotacheck.8 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd January 25, 2007 .Dt QUOTACHECK 8 .Os .Sh NAME .Nm quotacheck .Nd file system quota consistency checker .Sh SYNOPSIS .Nm .Op Fl guv .Op Fl c Ar 32 | 64 .Op Fl l Ar maxrun .Fl a .Nm .Op Fl guv .Op Fl c Ar 32 | 64 .Ar filesystem ... .Sh DESCRIPTION The .Nm utility examines each file system, builds a table of current disk usage, and compares this table against that recorded in the disk quota file for the file system. If any inconsistencies are detected, both the quota file and the current system copy of the incorrect quotas are updated (the latter only occurs if an active file system is checked). By default both user and group quotas are checked. .Pp The following options are available: .Bl -tag -width indent .It Fl a If supplied in place of any file system names, .Nm will check all the file systems indicated in .Pa /etc/fstab to be read-write with disk quotas. By default only the types of quotas listed in .Pa /etc/fstab are checked. .It Fl c Ar 32 | 64 Before performing its checks, .Nm will convert the quota file to the specified word size. A conversion size of 64 is given to request conversion to the new 64-bit quota file format. A conversion size of 32 is given to request conversion back to the old 32-bit quota file format. The original quota file is left unchanged and moved aside with an underscore and its format size plus a .Pa .orig extension added to its name. Thus, the original 32-bit .Pa quota.user quota file converted to the 64-bit format quota file will be renamed to .Pa quota.user_32.orig . .It Fl g Only group quotas listed in .Pa /etc/fstab are to be checked. .It Fl l Ar maxrun Specifies the maximum number of concurrent file systems to check in parallel. If this option is omitted, or if .Ar maxrun is zero, parallel passes are run as per .Xr fsck 8 . This option is deprecated and parallel passes are always run as per .Xr fsck 8 . .It Fl u Only user quotas listed in .Pa /etc/fstab are to be checked. .It Fl v Report discrepancies between the calculated and recorded disk quotas and other additional diagnostic messages. .El .Pp Specifying both .Fl g and .Fl u is equivalent to the default. Parallel passes are run on the file systems required, using the pass numbers in .Pa /etc/fstab in an identical fashion to .Xr fsck 8 . .Pp Normally, .Nm operates silently. .Pp The .Nm utility expects each file system to be checked to have a quota files named .Pa quota.user and .Pa quota.group which are located at the root of the associated file system. These defaults may be overridden in .Pa /etc/fstab . If a file is not present, .Nm will create it. These files should be edited with the .Xr edquota 8 utility. .Pp The .Nm utility is normally run at boot time from the .Pa /etc/rc file. The rc startup procedure is controlled by the .Pa /etc/rc.conf variable .Ar check_quotas . Note that to enable this functionality in .Pa /etc/rc you also need to enable startup quota procedures with the variable .Ar enable_quotas in .Pa /etc/rc.conf . -The kernel must also be built with +The kernel must also be built with .Cd "options QUOTA" . .Pp The .Nm utility accesses the raw device in calculating the actual disk usage for each user. Thus, the file systems checked should be quiescent while .Nm is running. .Sh FILES .Bl -tag -width quota.group -compact .It Pa quota.user at the file system root with user quotas .It Pa quota.group at the file system root with group quotas .It Pa /etc/fstab default file systems .El .Sh SEE ALSO .Xr quota 1 , .Xr quotactl 2 , .Xr fstab 5 , .Xr rc.conf 5 , .Xr edquota 8 , .Xr fsck 8 , .Xr quotaon 8 , .Xr repquota 8 .Sh HISTORY The .Nm utility appeared in .Bx 4.2 . .Sh BUGS The quota system will ignore UIDs or GIDs that would be negative when evaluated as a signed value. Typically those types of ids can appear in the file system from NFS mounts or archive files from other operating systems. Extremely large UIDs or GIDs will cause .Nm to run for an unreasonable amount of time and also produce extremely large quota data files. Index: stable/9/sbin/quotacheck =================================================================== --- stable/9/sbin/quotacheck (revision 237215) +++ stable/9/sbin/quotacheck (revision 237216) Property changes on: stable/9/sbin/quotacheck ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /user/piso/sbin/quotacheck:r186725 Merged /vendor/resolver/dist/sbin/quotacheck:r1540-186085 Merged /projects/largeSMP/sbin/quotacheck:r221273-222812,222815-223757 Merged /projects/quota64/sbin/quotacheck:r184125-207707 Merged /head/sbin/quotacheck:r2-3,227006,233648 Index: stable/9/sbin/rcorder/rcorder.8 =================================================================== --- stable/9/sbin/rcorder/rcorder.8 (revision 237215) +++ stable/9/sbin/rcorder/rcorder.8 (revision 237216) @@ -1,189 +1,189 @@ .\" $NetBSD: rcorder.8,v 1.3 2000/07/17 14:16:22 mrg Exp $ .\" .\" Copyright (c) 1998 .\" Perry E. Metzger. 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgment: .\" This product includes software developed for the NetBSD Project .\" by Perry E. Metzger. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 August 5, 2011 .Dt RCORDER 8 .Os .Sh NAME .Nm rcorder .Nd print a dependency ordering of interdependent files .Sh SYNOPSIS .Nm .Op Fl k Ar keep .Op Fl s Ar skip .Ar .Sh DESCRIPTION The .Nm utility is designed to print out a dependency ordering of a set of interdependent files. Typically it is used to find an execution sequence for a set of shell scripts in which certain files must be executed before others. .Pp Each file passed to .Nm must be annotated with special lines (which look like comments to the shell) which indicate the dependencies the files have upon certain points in the sequence, known as .Dq conditions , and which indicate, for each file, which .Dq conditions may be expected to be filled by that file. .Pp Within each file, a block containing a series of .Dq Li REQUIRE , .Dq Li PROVIDE , .Dq Li BEFORE and .Dq Li KEYWORD lines must appear. The format of the lines is rigid. Each line must begin with a single .Ql # , followed by a single space, followed by .Dq Li PROVIDE: , .Dq Li REQUIRE: , .Dq Li BEFORE: , or .Dq Li KEYWORD: . No deviation is permitted. Each dependency line is then followed by a series of conditions, separated by whitespace. Multiple .Dq Li PROVIDE , .Dq Li REQUIRE , .Dq Li BEFORE and .Dq Li KEYWORD lines may appear, but all such lines must appear in a sequence without any intervening lines, as once a line that does not follow the format is reached, parsing stops. .\" Note that for historical reasons REQUIRES, PROVIDES, and KEYWORDS .\" are also accepted in addition to the above, but not documented so .\" that they can be deprecated at some point in the future. .Pp The options are as follows: .Bl -tag -width indent .It Fl k Add the specified keyword to the .Dq "keep list" . If any .Fl k option is given, only those files containing the matching keyword are listed. .It Fl s Add the specified keyword to the .Dq "skip list" . If any .Fl s option is given, files containing the matching keyword are not listed. .El .Pp An example block follows: .Bd -literal -offset indent # REQUIRE: networking syslog # REQUIRE: usr # PROVIDE: dns nscd .Ed .Pp This block states that the file in which it appears depends upon the .Dq Li networking , .Dq Li syslog , and .Dq Li usr conditions, and provides the .Dq Li dns and .Dq Li nscd conditions. .Pp A file may contain zero .Dq Li PROVIDE lines, in which case it provides no conditions, and may contain zero .Dq Li REQUIRE lines, in which case it has no dependencies. There must be at least one file with no dependencies in the set of arguments passed to .Nm in order for it to find a starting place in the dependency ordering. .Sh DIAGNOSTICS The .Nm utility may print one of the following error messages and exit with a non-zero status if it encounters an error while processing the file list. .Bl -diag .It "Requirement %s has no providers, aborting." No file has a .Dq Li PROVIDE line corresponding to a condition present in a .Dq Li REQUIRE line in another file. .It "Circular dependency on provision %s, aborting." A set of files has a circular dependency which was detected while processing the stated condition. .It "Circular dependency on file %s, aborting." A set of files has a circular dependency which was detected while processing the stated file. .El .Sh SEE ALSO .Xr rc 8 .Sh HISTORY The .Nm utility first appeared in .Nx 1.5 . .Sh AUTHORS .An -nosplit Written by .An Perry E. Metzger Aq perry@piermont.com and .An Matthew R. Green Aq mrg@eterna.com.au . .Sh BUGS The .Dq Li REQUIRE keyword is misleading: It doesn't describe which daemons have to be running before a script will be started. It describes which scripts must be placed before it in the dependency ordering. For example, if your script has a .Dq Li REQUIRE on .Dq Li named , -it means the script must be placed after the +it means the script must be placed after the .Dq Li named script in the dependency ordering, not necessarily that it requires .Xr named 8 to be started or enabled. Index: stable/9/sbin/rcorder =================================================================== --- stable/9/sbin/rcorder (revision 237215) +++ stable/9/sbin/rcorder (revision 237216) Property changes on: stable/9/sbin/rcorder ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /head/sbin/rcorder:r2-3,227006,233648 Merged /projects/largeSMP/sbin/rcorder:r221273-222812,222815-223757 Merged /user/piso/sbin/rcorder:r186725 Merged /vendor/resolver/dist/sbin/rcorder:r1540-186085 Merged /projects/quota64/sbin/rcorder:r184125-207707 Index: stable/9/share/man/man3/pthread_attr_affinity_np.3 =================================================================== --- stable/9/share/man/man3/pthread_attr_affinity_np.3 (revision 237215) +++ stable/9/share/man/man3/pthread_attr_affinity_np.3 (revision 237216) @@ -1,162 +1,162 @@ .\"- .\" Copyright (c) 2010 Xin LI .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 8, 2010 .Dt PTHREAD_ATTR_AFFINITY_NP 3 .Os .Sh NAME .Nm pthread_attr_getaffinity_np , .Nm pthread_attr_setaffinity_np .Nd manage CPU affinity in thread attribute objects .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS .In pthread_np.h .Ft int .Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp" .Ft int .Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp" .Sh DESCRIPTION The .Fn pthread_attr_getaffinity_np and .Fn pthread_attr_setaffinity_np functions allow the manipulation of sets of CPUs available to the specified thread attribute object. .Pp Masks of type .Ft cpuset_t are composed using the .Xr CPU_SET 3 macros. The kernel tolerates large sets as long as all CPUs specified in the set exist. Sets smaller than the kernel uses generate an error on calls to .Fn pthread_attr_getaffinity_np even if the result set would fit within the user supplied set. Calls to .Fn pthread_attr_setaffinity_np tolerate small sets with no restrictions. .Pp The supplied mask should have a size of .Fa cpusetsize bytes. This size is usually provided by calling .Li sizeof(cpuset_t) which is ultimately determined by the value of .Dv CPU_SETSIZE as defined in .In sys/cpuset.h . .Pp .Fn pthread_attr_getaffinity_np retrieves the mask from the thread attribute object specified by .Fa pattr , and stores it in the space provided by .Fa cpusetp . .Pp .Fn pthread_attr_setaffinity_np sets the mask for the thread attribute object specified by .Fa pattr to the value in .Fa cpusetp . .Sh RETURN VALUES If successful, the .Fn pthread_attr_getaffinity_np and .Fn pthread_attr_setaffinity_np functions will return zero. Otherwise an error number will be returned to indicate the error. .Sh ERRORS The .Fn pthread_attr_getaffinity_np functions will fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa pattr or the attribute specified by it is .Dv NULL . .It Bq Er ERANGE The .Fa cpusetsize is too small. .El .Pp The .Fn pthread_attr_setaffinity_np function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa pattr or the attribute specified by it is .Dv NULL . .It Bq Er EINVAL The .Fa cpusetp -specified a CPU that was outside the set supported by the kernel. +specified a CPU that was outside the set supported by the kernel. .It Bq Er ERANGE The .Fa cpusetsize is too small. .It Bq Er ENOMEM Insufficient memory exists to store the cpuset mask. .El .Sh SEE ALSO .Xr cpuset 1 , .Xr cpuset 2 , .Xr cpuset_getid 2 , .Xr cpuset_setid 2 , .Xr CPU_SET 3 , .Xr pthread_get_affinity_np 3 , .Xr pthread_set_affinity_np 3 .Sh STANDARDS The .Nm pthread_attr_getaffinity_np and .Nm pthread_attr_setaffinity_np functions are non-standard .Fx extensions and may be not available on other operating systems. .Sh HISTORY The .Nm pthread_attr_getaffinity_np and .Nm pthread_attr_setaffinity_np functions first appeared in .Fx 7.2 . .Sh AUTHORS .An -nosplit The .Nm pthread_attr_getaffinity_np and .Nm pthread_attr_setaffinity_np functions were written by .An David Xu Aq davidxu@FreeBSD.org , and this manpage was written by .An Xin LI Aq delphij@FreeBSD.org . Index: stable/9/share/man/man3/pthread_cond_timedwait.3 =================================================================== --- stable/9/share/man/man3/pthread_cond_timedwait.3 (revision 237215) +++ stable/9/share/man/man3/pthread_cond_timedwait.3 (revision 237216) @@ -1,101 +1,101 @@ .\" Copyright (c) 1997 Brian Cully .\" 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 author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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. .\" .\" $FreeBSD$ .\" .Dd May 9, 2010 .Dt PTHREAD_COND_TIMEDWAIT 3 .Os .Sh NAME .Nm pthread_cond_timedwait .Nd "wait on a condition variable for a specific amount of time" .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS .In pthread.h .Ft int .Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" .Sh DESCRIPTION The .Fn pthread_cond_timedwait function atomically blocks the current thread waiting on the condition variable specified by .Fa cond , and releases the mutex specified by .Fa mutex . The waiting thread unblocks only after another thread calls .Xr pthread_cond_signal 3 , or .Xr pthread_cond_broadcast 3 with the same condition variable, or if the system time reaches the time specified in .Fa abstime , and the current thread reacquires the lock on .Fa mutex . .Pp The clock used to measure .Fa abstime can be specified during creation of the condition variable using .Xr pthread_condattr_setclock 3 . .Sh RETURN VALUES If successful, the .Fn pthread_cond_timedwait function will return zero. Otherwise an error number will be returned to indicate the error. .Sh ERRORS The .Fn pthread_cond_timedwait function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The value specified by .Fa cond , .Fa mutex or .Fa abstime is invalid. .It Bq Er ETIMEDOUT The system time has reached or exceeded the time specified in .Fa abstime . .It Bq Er EPERM -The specified -.Fa mutex +The specified +.Fa mutex was not locked by the calling thread. .El .Sh SEE ALSO .Xr pthread_cond_broadcast 3 , .Xr pthread_cond_destroy 3 , .Xr pthread_cond_init 3 , .Xr pthread_cond_signal 3 , .Xr pthread_cond_wait 3 , .Xr pthread_condattr_setclock 3 .Sh STANDARDS The .Fn pthread_cond_timedwait function conforms to .St -p1003.1-96 . Index: stable/9/share/man/man3/pthread_cond_wait.3 =================================================================== --- stable/9/share/man/man3/pthread_cond_wait.3 (revision 237215) +++ stable/9/share/man/man3/pthread_cond_wait.3 (revision 237216) @@ -1,89 +1,89 @@ .\" Copyright (c) 1997 Brian Cully .\" 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 author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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. .\" .\" $FreeBSD$ .\" .Dd February 16, 2006 .Dt PTHREAD_COND_WAIT 3 .Os .Sh NAME .Nm pthread_cond_wait .Nd wait on a condition variable .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS .In pthread.h .Ft int .Fn pthread_cond_wait "pthread_cond_t *cond" "pthread_mutex_t *mutex" .Sh DESCRIPTION The .Fn pthread_cond_wait function atomically blocks the current thread waiting on the condition variable specified by .Fa cond , and releases the mutex specified by .Fa mutex . The waiting thread unblocks only after another thread calls .Xr pthread_cond_signal 3 , or .Xr pthread_cond_broadcast 3 with the same condition variable, and the current thread reacquires the lock on .Fa mutex . .Sh RETURN VALUES If successful, the .Fn pthread_cond_wait function will return zero. Otherwise an error number will be returned to indicate the error. .Sh ERRORS The .Fn pthread_cond_wait function will fail if: .Bl -tag -width Er .It Bq Er EINVAL The value specified by .Fa cond or the value specified by .Fa mutex is invalid. .It Bq Er EPERM -The specified -.Fa mutex +The specified +.Fa mutex was not locked by the calling thread. .El .Sh SEE ALSO .Xr pthread_cond_broadcast 3 , .Xr pthread_cond_destroy 3 , .Xr pthread_cond_init 3 , .Xr pthread_cond_signal 3 , .Xr pthread_cond_timedwait 3 .Sh STANDARDS The .Fn pthread_cond_wait function conforms to .St -p1003.1-96 . Index: stable/9/share/man/man3 =================================================================== --- stable/9/share/man/man3 (revision 237215) +++ stable/9/share/man/man3 (revision 237216) Property changes on: stable/9/share/man/man3 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man3:r233648 Index: stable/9/share/man/man4/acpi_hp.4 =================================================================== --- stable/9/share/man/man4/acpi_hp.4 (revision 237215) +++ stable/9/share/man/man4/acpi_hp.4 (revision 237216) @@ -1,288 +1,288 @@ .\" Copyright (c) 2009 Michael Gmelin .\" 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. .\" .\" $FreeBSD$ .\" .Dd February 8, 2010 .Dt ACPI_HP 4 .Os .Sh NAME .Nm acpi_hp .Nd "ACPI extras driver for HP laptops" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device acpi_hp" .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 acpi_hp_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for ACPI-controlled features found on HP laptops that use a WMI enabled BIOS (e.g. HP Compaq 8510p and 6510p). .Pp The main purpose of this driver is to provide an interface, accessible via .Xr sysctl 8 , .Xr devd 8 and .Xr devfs 8 , through which applications can determine and change the status of various laptop components and BIOS settings. .Pp .Ss Xr devd 8 Ss Events Devd events received by .Xr devd 8 provide the following information: .Pp .Bl -tag -width "subsystem" -offset indent -compact .It system .Qq Li ACPI .It subsystem .Qq Li HP .It type The source of the event in the ACPI namespace. The value depends on the model. .It notify Event code (see below). .El .Pp Event codes: .Pp .Bl -tag -width "0xc0" -offset indent -compact .It Li 0xc0 WLAN on air status changed to 0 (not on air) .It Li 0xc1 WLAN on air status changed to 1 (on air) .It Li 0xd0 Bluetooth on air status changed to 0 (not on air) .It Li 0xd1 Bluetooth on air status changed to 1 (on air) .It Li 0xe0 WWAN on air status changed to 0 (not on air) .It Li 0xe1 WWAN on air status changed to 1 (on air) .El .Ss Xr devfs 8 Ss Device You can read /dev/hpcmi to see your current BIOS settings. -The detail level can be adjusted by setting the sysctl +The detail level can be adjusted by setting the sysctl .Va cmi_detail as described below. .Sh SYSCTL VARIABLES The following sysctls are currently implemented: .Ss WLAN: .Bl -tag -width indent .It Va dev.acpi_hp.0.wlan_enabled -Toggle WLAN chip activity. +Toggle WLAN chip activity. .It Va dev.acpi_hp.0.wlan_radio (read-only) WLAN radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.wlan_on_air (read-only) WLAN on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.wlan_enabled_if_radio_on If set to 1, the WLAN chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.wlan_disable_if_radio_off If set to 1, the WLAN chip will be disabled if the radio is turned off .El .Ss Bluetooth: .Bl -tag -width indent .It Va dev.acpi_hp.0.bt_enabled -Toggle Bluetooth chip activity. +Toggle Bluetooth chip activity. .It Va dev.acpi_hp.0.bt_radio (read-only) Bluetooth radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.bt_on_air (read-only) Bluetooth on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.bt_enabled_if_radio_on If set to 1, the Bluetooth chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.bt_disable_if_radio_off If set to 1, the Bluetooth chip will be disabled if the radio is turned off .El .Ss WWAN: .Bl -tag -width indent .It Va dev.acpi_hp.0.wwan_enabled -Toggle WWAN chip activity. +Toggle WWAN chip activity. .It Va dev.acpi_hp.0.wwan_radio (read-only) WWAN radio status (controlled by hardware switch) .It Va dev.acpi_hp.0.wwan_on_air (read-only) WWAN on air (chip enabled, hardware switch enabled + enabled in BIOS) .It Va dev.acpi_hp.0.wwan_enabled_if_radio_on If set to 1, the WWAN chip will be enabled if the radio is turned on .It Va dev.acpi_hp.0.wwan_disable_if_radio_off If set to 1, the WWAN chip will be disabled if the radio is turned off .El .Ss Misc: .Bl -tag -width indent .It Va dev.acpi_hp.0.als_enabled Toggle ambient light sensor (ALS) .It Va dev.acpi_hp.0.display (read-only) Display status (bitmask) .It Va dev.acpi_hp.0.hdd_temperature (read-only) HDD temperature .It Va dev.acpi_hp.0.is_docked (read-only) Docking station status (1 if docked) .It Va dev.acpi_hp.0.cmi_detail Bitmask to control detail level in /dev/hpcmi output (values can be ORed). .Bl -tag -width "0x01" -offset indent -compact .It Li 0x01 Show path component of BIOS setting .It Li 0x02 Show a list of valid options for the BIOS setting .It Li 0x04 Show additional flags of BIOS setting (ReadOnly etc.) .It Li 0x08 Query highest BIOS entry instance. This is broken on many HP models and therefore disabled by default. .El .It Va dev.acpi_hp.0.verbose (read-only) Set verbosity level .El .Pp Defaults for these sysctls can be set in .Xr sysctl.conf 5 . .Sh HARDWARE The .Nm driver has been reported to support the following hardware: .Pp .Bl -bullet -compact .It HP Compaq 8510p .It HP Compaq nx7300 .El .Pp It should work on most HP laptops that feature a WMI enabled BIOS. .Sh FILES .Bl -tag -width ".Pa /dev/hpcmi" .It Pa /dev/hpcmi Interface to read BIOS settings .El .Sh EXAMPLES The following can be added to .Xr devd.conf 5 in order disable the LAN interface when WLAN on air and reenable if it's not: .Bd -literal -offset indent notify 0 { match "system" "ACPI"; match "subsystem" "HP"; match "notify" "0xc0"; action "ifconfig em0 up"; }; notify 0 { match "system" "ACPI"; match "subsystem" "HP"; match "notify" "0xc1"; action "ifconfig em0 down"; }; .Ed .Pp Enable the ambient light sensor: .Bd -literal -offset indent sysctl dev.acpi_hp.0.als_enabled=1 .Ed .Pp Enable Bluetooth: .Bd -literal -offset indent sysctl dev.acpi_hp.0.bt_enabled=1 .Ed .Pp Get BIOS settings: .Bd -literal -offset indent cat /dev/hpcmi -Serial Port Disable -Infrared Port Enable -Parallel Port Disable -Flash Media Reader Disable -USB Ports including Express Card slot Enable -1394 Port Enable -Cardbus Slot Disable -Express Card Slot Disable +Serial Port Disable +Infrared Port Enable +Parallel Port Disable +Flash Media Reader Disable +USB Ports including Express Card slot Enable +1394 Port Enable +Cardbus Slot Disable +Express Card Slot Disable (...) .Ed .Pp Set maximum detail level for /dev/hpcmi output: .Bd -literal -offset indent sysctl dev.acpi_hp.0.cmi_detail=7 .Ed .Pp .Sh SEE ALSO .Xr acpi 4 , .Xr acpi_wmi 4 , .Xr sysctl.conf 5 , .Xr devd 8 , .Xr devfs 8 , .Xr sysctl 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Michael Gmelin Aq freebsd@grem.de . .Pp It has been inspired by hp-wmi driver, which implements a subset of these features (hotkeys) on Linux. .Bl -tag -width indent .It HP CMI whitepaper: http://h20331.www2.hp.com/Hpsub/downloads/cmi_whitepaper.pdf .It wmi-hp for Linux: http://www.kernel.org .It WMI and ACPI: http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx .El .Pp This manual page was written by .An Michael Gmelin Aq freebsd@grem.de . .Sh BUGS This driver is experimental and has only been tested on i386 on an HP Compaq 8510p which featured all supported wireless devices (WWAN/BT/WLAN). Expect undefined results when operating on different hardware. .Pp Loading the driver is slow. Reading from /dev/hpcmi is even slower. .Pp Additional features like HP specific sensor readings or writing BIOS settings are not supported. Index: stable/9/share/man/man4/acpi_wmi.4 =================================================================== --- stable/9/share/man/man4/acpi_wmi.4 (revision 237215) +++ stable/9/share/man/man4/acpi_wmi.4 (revision 237216) @@ -1,96 +1,96 @@ .\" Copyright (c) 2009 Michael Gmelin .\" 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. .\" .\" $FreeBSD$ .\" .Dd November 22, 2011 .Dt ACPI_WMI 4 .Os .Sh NAME .Nm acpi_wmi .Nd "ACPI to WMI mapping driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device acpi_wmi" .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 acpi_wmi_load="YES" .Ed .Sh DESCRIPTION The .Nm -driver provides an interface for vendor specific WMI implementations +driver provides an interface for vendor specific WMI implementations (e.g. HP and Acer laptops). It creates /dev/wmistat%d, which can be read to get information about GUIDs found in the system. .Sh FILES .Bl -tag -width /dev/wmistat%d -compact .It Pa /dev/wmistat%d WMI status device. .El .Sh EXAMPLES .Bd -literal # cat /dev/wmistat0 GUID INST EXPE METH STR EVENT OID {5FB7F034-2C63-45E9-BE91-3D44E2C707E4} 1 NO WMAA NO NO AA {95F24279-4D7B-4334-9387-ACCDC67EF61C} 1 NO NO NO 0x80+ - {2B814318-4BE8-4707-9D84-A190A859B5D0} 1 NO NO NO 0xA0 - {05901221-D566-11D1-B2F0-00A0C9062910} 1 NO NO NO NO AB {1F4C91EB-DC5C-460B-951D-C7CB9B4B8D5E} 1 NO WMBA NO NO BA {2D114B49-2DFB-4130-B8FE-4A3C09E75133} 57 NO NO NO NO BC {988D08E3-68F4-4C35-AF3E-6A1B8106F83C} 20 NO NO NO NO BD {14EA9746-CE1F-4098-A0E0-7045CB4DA745} 1 NO NO NO NO BE {322F2028-0F84-4901-988E-015176049E2D} 2 NO NO NO NO BF {8232DE3D-663D-4327-A8F4-E293ADB9BF05} 0 NO NO NO NO BG {8F1F6436-9F42-42C8-BADC-0E9424F20C9A} 0 NO NO NO NO BH {8F1F6435-9F42-42C8-BADC-0E9424F20C9A} 0 NO NO NO NO BI .Ed .Sh SEE ALSO .Xr acpi 4 , .Sh HISTORY The .Nm device driver first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Michael Gmelin Aq freebsd@grem.de . .Pp Work has been inspired by the Linux acpi-wmi driver written by Carlos Corbacho. .Pp See http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx for the specification of ACPI-WMI. .Pp This manual page was written by .An Michael Gmelin Aq freebsd@grem.de . Index: stable/9/share/man/man4/carp.4 =================================================================== --- stable/9/share/man/man4/carp.4 (revision 237215) +++ stable/9/share/man/man4/carp.4 (revision 237216) @@ -1,305 +1,305 @@ .\" $OpenBSD: carp.4,v 1.16 2004/12/07 23:41:35 jmc Exp $ .\" .\" Copyright (c) 2003, Ryan McBride. 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 PROJECT 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 PROJECT 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 August 15, 2011 .Dt CARP 4 .Os .Sh NAME .Nm carp .Nd Common Address Redundancy Protocol .Sh SYNOPSIS .Cd "device carp" .Sh DESCRIPTION The .Nm interface is a pseudo-device that implements and controls the CARP protocol. CARP allows multiple hosts on the same local network to share a set of IP addresses. Its primary purpose is to ensure that these addresses are always available, but in some configurations .Nm can also provide load balancing functionality. .Pp A .Nm interface can be created at runtime using the .Nm ifconfig Li carp Ns Ar N Cm create command or by configuring it via .Va cloned_interfaces in the .Pa /etc/rc.conf file. .Pp To use .Nm , the administrator needs to configure at minimum a common virtual host ID (VHID) and virtual host IP address on each machine which is to take part in the virtual group. Additional parameters can also be set on a per-interface basis: .Cm advbase and .Cm advskew , which are used to control how frequently the host sends advertisements when it is the master for a virtual host, and .Cm pass which is used to authenticate .Nm advertisements. The .Cm advbase parameter stands for .Dq "advertisement base" . It is measured in seconds and specifies the base of the advertisement interval. The .Cm advskew parameter stands for .Dq "advertisement skew" . It is measured in 1/256 of seconds. It is added to the base advertisement interval to make one host advertise a bit slower that the other does. Both .Cm advbase and .Cm advskew are put inside CARP advertisements. These configurations can be done using .Xr ifconfig 8 , or through the .Dv SIOCSVH .Xr ioctl 2 . .Pp Additionally, there are a number of global parameters which can be set using .Xr sysctl 8 : .Bl -tag -width ".Va net.inet.carp.arpbalance" .It Va net.inet.carp.allow Accept incoming .Nm packets. Enabled by default. .It Va net.inet.carp.preempt Allow virtual hosts to preempt each other. It is also used to failover .Nm interfaces as a group. When the option is enabled and one of the .Nm enabled physical interfaces goes down, .Cm advskew is changed to 240 on all .Nm interfaces. See also the first example. Disabled by default. .It Va net.inet.carp.log Value of 0 disables any logging. Value of 1 enables logging state changes of .Nm interfaces. Values above 1 enable logging of bad .Nm packets. Default value is 1. .It Va net.inet.carp.arpbalance Balance local traffic using ARP (see below). Disabled by default. .It Va net.inet.carp.suppress_preempt A read only value showing the status of preemption suppression. Preemption can be suppressed if link on an interface is down or when .Xr pfsync 4 interface is not synchronized. Value of 0 means that preemption is not suppressed, since no problems are detected. Every problem increments suppression counter. .El .Sh ARP level load balancing The .Nm has limited abilities for load balancing the incoming connections between hosts in Ethernet network. For load balancing operation, one needs several CARP interfaces that are configured to the same IP address, but to a different VHIDs. Once an ARP request is received, the CARP protocol will use a hashing function against the source IP address in the ARP request to determine which VHID should this request belong to. If the corresponding CARP interface is in master state, the ARP request will be replied, otherwise it will be ignored. See the .Sx EXAMPLES section for a practical example of load balancing. .Pp The ARP load balancing has some limitations. First, ARP balancing only works on the local network segment. It cannot balance traffic that crosses a router, because the router itself will always be balanced to the same virtual host. Second, ARP load balancing can lead to asymmetric routing of incoming and outgoing traffic, and thus combining it with .Xr pfsync 4 is dangerous, because this creates a race condition between balanced routers and a host they are serving. Imagine an incoming packet creating state on the first router, being forwarded to its destination, and destination replying faster than the state information is packed and synced with the second router. If the reply would be load balanced to second router, it will be dropped due to no state. .Sh STATE CHANGE NOTIFICATIONS Sometimes it is useful to get notified about .Nm status change events. This can be accomplished by using .Xr devd 8 hooks. Master/slave events are signalled as .Nm interface .Dv LINK_UP or .Dv LINK_DOWN event. Please see .Xr devd.conf 5 -and +and .Sx EXAMPLES section for more information. .Sh EXAMPLES For firewalls and routers with multiple interfaces, it is desirable to failover all of the .Nm interfaces together, when one of the physical interfaces goes down. This is achieved by the preempt option. Enable it on both host A and B: .Pp .Dl sysctl net.inet.carp.preempt=1 .Pp Assume that host A is the preferred master and 192.168.1.x/24 is configured on one physical interface and 192.168.2.y/24 on another. This is the setup for host A: .Bd -literal -offset indent ifconfig carp0 create ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.1/24 ifconfig carp1 create ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.2.1/24 .Ed .Pp The setup for host B is identical, but it has a higher .Cm advskew : .Bd -literal -offset indent ifconfig carp0 create ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.1/24 ifconfig carp1 create ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.2.1/24 .Ed .Pp Because of the preempt option, when one of the physical interfaces of host A fails, .Cm advskew is adjusted to 240 on all its .Nm interfaces. This will cause host B to preempt on both interfaces instead of just the failed one. .Pp In order to set up an ARP balanced virtual host, it is necessary to configure one virtual host for each physical host which would respond to ARP requests and thus handle the traffic. In the following example, two virtual hosts are configured on two hosts to provide balancing and failover for the IP address 192.168.1.10. .Pp First the .Nm interfaces on host A are configured. The .Cm advskew of 100 on the second virtual host means that its advertisements will be sent out slightly less frequently. .Bd -literal -offset indent ifconfig carp0 create ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10/24 ifconfig carp1 create ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.1.10/24 .Ed .Pp The configuration for host B is identical, except the .Cm advskew is on virtual host 1 rather than virtual host 2. .Bd -literal -offset indent ifconfig carp0 create ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.10/24 ifconfig carp1 create ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10/24 .Ed .Pp Finally, the ARP balancing feature must be enabled on both hosts: .Pp .Dl sysctl net.inet.carp.arpbalance=1 .Pp When the hosts receive an ARP request for 192.168.1.10, the source IP address of the request is used to compute which virtual host should answer the request. The host which is master of the selected virtual host will reply to the request, the other(s) will ignore it. .Pp This way, locally connected systems will receive different ARP replies and subsequent IP traffic will be balanced among the hosts. If one of the hosts fails, the other will take over the virtual MAC address, and begin answering ARP requests on its behalf. .Pp Processing of .Nm status change events can be set up by using the following devd.conf rules: .Bd -literal -offset indent notify 0 { match "system" "IFNET"; match "type" "LINK_UP"; match "subsystem" "carp*"; action "/root/carpcontrol.sh $type $subsystem"; }; notify 0 { match "system" "IFNET"; match "type" "LINK_DOWN"; match "subsystem" "carp*"; action "/root/carpcontrol.sh $type $subsystem"; }; .Ed .Sh SEE ALSO .Xr inet 4 , .Xr pfsync 4 , .Xr rc.conf 5 , .Xr devd.conf 5 , .Xr ifconfig 8 , .Xr sysctl 8 .Sh HISTORY The .Nm device first appeared in .Ox 3.5 . The .Nm device was imported into .Fx 5.4 . Index: stable/9/share/man/man4/ipmi.4 =================================================================== --- stable/9/share/man/man4/ipmi.4 (revision 237215) +++ stable/9/share/man/man4/ipmi.4 (revision 237216) @@ -1,201 +1,201 @@ .\" .\" Copyright (c) 2006 Tom Rhodes .\" 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. .\" .\" $FreeBSD$ .\" .Dd July 10, 2007 .Dt IPMI 4 .Os .Sh NAME .Nm ipmi .Nd "OpenIPMI compatible IPMI interface driver" .Sh SYNOPSIS .Cd "device ipmi" .Pp To manually specify I/O attachment in .Pa /boot/device.hints : .Cd hint.ipmi.0.at="isa" .Cd hint.ipmi.0.port="0xCA2" .Cd hint.ipmi.0.spacing="8" .Cd hint.ipmi.0.mode="KCS" .Pp To manually specify memory attachment in .Pa /boot/device.hints : .Cd hint.ipmi.0.at="isa" .Cd hint.ipmi.0.maddr="0xf0000000" .Cd hint.ipmi.0.spacing="8" .Cd hint.ipmi.0.mode="SMIC" .Pp Meaning of .Ar spacing : .Bl -tag -offset indent -compact -width 0x0 .It 8 8 bit alignment .It 16 16 bit alignment .It 32 32 bit alignment .El .Pp If the .Ar port and .Ar spacing -are not specified the interface type default will be used. Only specify +are not specified the interface type default will be used. Only specify either the .Ar port for I/O access or .Ar maddr for memory access. .Sh DESCRIPTION The .Tn IPMI (Intelligent Platform Management Interface) is a standard for monitoring system hardware by permitting generic code to detect and monitor the sensors in a system. The .Tn IPMI standard offers watchdog support, an FRU database, and other support extensions. It is currently being adopted by the makers of many single board and embedded system manufacturers. .Pp The .Nm driver in .Fx is heavily adopted from the standard and .Tn Linux driver; however, not all features described in the standard are supported. .Sh IOCTLS Sending and receiving messages through the .Nm driver requires the use of .Xr ioctl 2 . The ioctls are used due to the complexity of data sent to and from the device. The .Xr ioctl 2 command codes below are defined in .In sys/ipmi.h . The third argument to .Xr ioctl 2 should be a pointer to the type indicated. .Pp Currently the following ioctls are supported: .Bl -tag -width indent .It Dv IPMICTL_RECEIVE_MSG Pq Vt "struct ipmi_recv" Receive a message. Possible error values: .Bl -tag -width Er .It Bq Er EAGAIN No messages are in the process queue. .It Bq Er EFAULT An address supplied was invalid. .It Bq Er EMSGSIZE The address could not fit in the message buffer and will remain in the buffer. .El .It Dv IPMICTL_RECEIVE_MSG_TRUNC Pq Vt "struct ipmi_recv" Like .Dv IPMICTL_RECEIVE_MSG but if the message cannot fit into the buffer, it will truncate the contents instead of leaving the data in the buffer. .It Dv IPMICTL_SEND_COMMAND Pq Vt "struct ipmi_req" Send a message to the interface. Possible error values: .Bl -tag -width Er .It Bq Er EFAULT An address supplied was invalid. .It Bq Er ENOMEM Buffers could not be allowed for the command, out of memory. .El .It Dv IPMICTL_SET_MY_ADDRESS_CMD Pq Vt "unsigned int" Set the slave address for source messages. .It Dv IPMICTL_GET_MY_ADDRESS_CMD Pq Vt "unsigned int" Get the slave address for source messages. .It Dv IPMICTL_SET_MY_LUN_CMD Pq Vt "unsigned int" Set the slave LUN for source messages. .It Dv IPMICTL_GET_MY_LUN_CMD Pq Vt "unsigned int" Get the slave LUN for source messages. .El .Ss Unimplemented Ioctls .Bl -tag -width indent .It Dv IPMICTL_REGISTER_FOR_CMD Pq Vt "struct ipmi_cmdspec" Register to receive a specific command. Possible error values: .Bl -tag -width Er .It Bq Er EFAULT An supplied address was invalid. .It Bq Er EBUSY The network function/command is already in use. .It Bq Er ENOMEM Could not allocate memory. .El .It Dv IPMICTL_UNREGISTER_FOR_CMD Pq Vt "struct ipmi_cmdspec" Unregister to receive a specific command. Possible error values: .Bl -tag -width Er .It Bq Er EFAULT An address supplied was invalid. .It Bq Er ENOENT The network function/command was not found. .El .El .Ss Stub Only Ioctl .Bl -tag -width indent .It Dv IPMICTL_SET_GETS_EVENTS_CMD Pq Vt int Set whether this interface receives events. Possible error values: .Bl -tag -width Er .It Bq Er EFAULT An address supplied was invalid. .El .El .Sh SEE ALSO .Xr ioctl 2 , .Xr watchdog 4 , .Xr watchdog 8 , .Xr watchdogd 8 , .Xr watchdog 9 .Sh HISTORY The .Nm driver first appeared in .Fx 6.2 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Doug Ambrisko Aq ambrisko@FreeBSD.org . This manual page was written by .An Tom Rhodes Aq trhodes@FreeBSD.org . .Sh BUGS Not all features of the MontaVista driver are supported. .Pp Currently, IPMB and BT modes are not implemented. Index: stable/9/share/man/man4/iwn.4 =================================================================== --- stable/9/share/man/man4/iwn.4 (revision 237215) +++ stable/9/share/man/man4/iwn.4 (revision 237216) @@ -1,182 +1,182 @@ .\" Copyright (c) 2004-2006 .\" Damien Bergamini . 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 unmodified, 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. .\" .\" $FreeBSD$ .\" .Dd March 27, 2012 .Dt IWN 4 .Os .Sh NAME .Nm iwn .Nd Intel IEEE 802.11n wireless network driver .Sh SYNOPSIS To compile this driver into the kernel, include the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iwn" .Cd "device pci" .Cd "device wlan" .Cd "device firmware" .Ed .Pp You also need to select a firmware for your device. Choose one from: .Bd -ragged -offset indent .Cd "device iwn4965fw" .Cd "device iwn1000fw" .Cd "device iwn5000fw" .Cd "device iwn5150fw" .Cd "device iwn6000fw" .Cd "device iwn6000g2afw" .Cd "device iwn6000g2bfw" .Cd "device iwn6050fw" .Ed .Pp Or you can use .Bd -ragged -offset indent .Cd "device iwnfw" .Ed .Pp to include them all. .Pp Alternatively, to load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent if_iwn_load="YES" iwn4965fw_load="YES" iwn1000fw_load="YES" iwn5000fw_load="YES" iwn5150fw_load="YES" iwn6000fw_load="YES" iwn6000g2afw_load="YES" iwn6000g2bfw_load="YES" iwn6050fw_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for: .Pp .Bl -tag -width Ds -offset indent -compact .It Intel Centrino Advanced-N 6200 .It Intel Centrino Advanced-N 6205 .It Intel Centrino Advanced-N 6230 .It Intel Centrino Advanced-N + WiMAX 6250 .It Intel Centrino Ultimate-N 6300 .It Intel Centrino Wireless-N 130 .It Intel Centrino Wireless-N 1000 .It Intel Centrino Wireless-N 1030 .It Intel Centrino Wireless-N + WiMAX 6150 .It Intel Ultimate N WiFi Link 5300 .It Intel Wireless WiFi Link 4965 .It Intel WiFi Link 5100 .It Intel WiMAX/WiFi Link 5150 .It Intel WiMAX/WiFi Link 5350 .El .Pp .Nm supports .Cm station , .Cm adhoc , and .Cm monitor mode operation. Only one virtual interface may be configured at any time. For more information on configuring this device, see .Xr ifconfig 8 . .Pp This driver requires the firmware built with the .Nm iwnfw module to work. .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan create wlandev iwn0 inet 192.168.0.20 \e netmask 0xffffff00 .Ed .Pp Join a specific BSS network with network name .Dq Li my_net : .Pp .Dl "ifconfig wlan create wlandev iwn0 ssid my_net up" .Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev iwn0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Pp Join a specific BSS network with 128-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev iwn0 wlanmode adhoc ssid my_net \e wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 .Ed .Sh DIAGNOSTICS .Bl -diag .It "iwn%d: device timeout" The driver will reset the hardware. This should not happen. .It "iwn%d: firmware error" The onboard microcontroller crashed for some reason. The driver will reset the hardware. This should not happen. .It "iwn%d: timeout waiting for firmware initialization to complete" The onboard microcontroller failed to initialize in time. This should not happen. .It "iwn%d: could not load firmware image '%s'" The driver failed to load the firmware image using the .Xr firmware 9 subsystem. -Verify the +Verify the .Xr iwnfw 4 firmware module is present. .It "iwn%d: could not load boot firmware" An attempt to upload the boot firmware image to the onboard microcontroller failed. This should not happen. .It "iwn%d: could not load microcode" An attempt to upload the microcode image to the onboard microcontroller failed. This should not happen. .It "iwn%d: could not load main firmware" An attempt to upload the main firmware image to the onboard microcontroller failed. This should not happen. .El .Sh SEE ALSO .Xr iwnfw 4 , .Xr pci 4 , .Xr wlan 4 , .Xr wlan_ccmp 4 , .Xr wlan_tkip 4 , .Xr wlan_wep 4 , .Xr ifconfig 8 , .Xr wpa_supplicant 8 .Sh AUTHORS The original .Nm driver was written by .An Damien Bergamini Aq damien.bergamini@free.fr . Index: stable/9/share/man/man4/iwnfw.4 =================================================================== --- stable/9/share/man/man4/iwnfw.4 (revision 237215) +++ stable/9/share/man/man4/iwnfw.4 (revision 237216) @@ -1,74 +1,74 @@ .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 April 20, 2011 .Dt IWNFW 4 .Os .Sh NAME .Nm iwnfw .Nd "Firmware Module for Intel Wireless driver" .Sh SYNOPSIS To compile this module into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device iwnfw" .Ed .Pp This will include three firmware images inside the kernel. If you want to pick only the firmware image for your network adapter choose one of the following: .Bd -ragged -offset indent .Cd "device iwn4965fw" .Cd "device iwn1000fw" .Cd "device iwn5000fw" .Cd "device iwn5150fw" .Cd "device iwn6000fw" .Cd "device iwn6000g2afw" .Cd "device iwn6000g2bfw" .Cd "device iwn6050fw" .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 iwn4965fw_load="YES" iwn1000fw_load="YES" iwn5000fw_load="YES" iwn5150fw_load="YES" iwn6000fw_load="YES" iwn6000g2afw_load="YES" iwn6000g2bfw_load="YES" iwn6050fw_load="YES" .Ed .Sh DESCRIPTION This module provides access to firmware sets for the -Intel Wireless WiFi Link 4965, 1000, 5000 and 6000 series of +Intel Wireless WiFi Link 4965, 1000, 5000 and 6000 series of IEEE 802.11n adapters. It may be statically linked into the kernel, or loaded as a module. .Sh SEE ALSO .Xr iwn 4 , .Xr firmware 9 Index: stable/9/share/man/man4/ktr.4 =================================================================== --- stable/9/share/man/man4/ktr.4 (revision 237215) +++ stable/9/share/man/man4/ktr.4 (revision 237216) @@ -1,206 +1,206 @@ .\" Copyright (c) 2001 John H. Baldwin .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 25, 2005 .Dt KTR 4 .Os .Sh NAME .Nm ktr .Nd kernel tracing facility .Sh SYNOPSIS .Cd options KTR .Cd options ALQ .Cd options KTR_ALQ .Cd options KTR_COMPILE=(KTR_LOCK|KTR_INTR|KTR_PROC) .Cd options KTR_CPUMASK=0x3 .Cd options KTR_ENTRIES=8192 .Cd options KTR_MASK=(KTR_INTR|KTR_PROC) .Cd options KTR_VERBOSE .Sh DESCRIPTION The .Nm facility allows kernel events to be logged while the kernel executes so that they can be examined later when debugging. The only mandatory option to enable .Nm is .Dq Li options KTR . .Pp The .Dv KTR_ENTRIES option sets the size of the buffer of events. It must be a power of two. The size of the buffer in the currently running kernel can be found via the read-only sysctl .Va debug.ktr.entries . By default the buffer contains 1024 entries. .Ss Event Masking Event levels can be enabled or disabled to trim excessive and overly verbose logging. First, a mask of events is specified at compile time via the .Dv KTR_COMPILE option to limit which events are actually compiled into the kernel. The default value for this option is for all events to be enabled. .Pp Secondly, the actual events logged while the kernel runs can be further masked via the run time event mask. The .Dv KTR_MASK option sets the default value of the run time event mask. The runtime event mask can also be set by the .Xr loader 8 via the .Va debug.ktr.mask environment variable. It can also be examined and set after booting via the .Va debug.ktr.mask sysctl. By default the run time mask is set to log only .Dv KTR_GEN events. The definitions of the event mask bits can be found in .In sys/ktr.h . .Pp Furthermore, there is a CPU event mask whose default value can be changed via the .Dv KTR_CPUMASK option. A CPU must have the bit corresponding to its logical id set in this bitmask for events that occur on it to be logged. This mask can be set by the .Xr loader 8 via the .Va debug.ktr.cpumask environment variable. It can also be examined and set after booting via the .Va debug.ktr.cpumask sysctl. By default events on all CPUs are enabled. .Ss Verbose Mode By default, events are only logged to the internal buffer for examination later, but if the verbose flag is set then they are dumped to the kernel console as well. This flag can also be set from the loader via the .Va debug.ktr.verbose environment variable, or it can be examined and set after booting via the .Va debug.ktr.verbose sysctl. If the flag is set to zero, which is the default, then verbose output is disabled. If the flag is set to one, then the contents of the log message and the CPU number are printed to the kernel console. If the flag is greater than one, then the filename and line number of the event are output to the console in addition to the log message and the CPU number. The .Dv KTR_VERBOSE option sets the flag to one. .Ss Examining the Events The KTR buffer can be examined from within .Xr ddb 4 via the .Ic show ktr Op Cm /vV command. This command displays the contents of the trace buffer one page at a time. At the .Dq Li --more-- prompt, the Enter key displays one more entry and prompts again. The spacebar displays another page of entries. Any other key quits. By default the timestamp, filename, and line number are not displayed with each log entry. If the .Cm /v modifier is specified, then they are displayed in addition to the normal output. If the .Cm /V modifier is specified, then just the timestamp is displayed in addition to the normal output. Note that the events are displayed in reverse chronological order. That is, the most recent events are displayed first. .Ss Logging ktr to Disk The .Dv KTR_ALQ option can be used to log .Nm entries to disk for post analysis using the .Xr ktrdump 8 utility. This option depends on the .Dv ALQ option. Due to the potentially high volume of trace messages the trace mask should be selected carefully. This feature is configured through a group of sysctls. .Bl -tag -width ".Va debug.ktr.alq_enable" .It Va debug.ktr.alq_file displays or sets the file that .Nm will log to. By default its value is .Pa /tmp/ktr.out . If the file name is changed while .Nm is enabled it will not take effect until the next invocation. .It Va debug.ktr.alq_enable enables logging of .Nm entries to disk if it is set to one. -Setting this to 0 will terminate logging to disk and revert to +Setting this to 0 will terminate logging to disk and revert to logging to the normal ktr ring buffer. Data is not sent to the ring buffer while logging to disk. .It Va debug.ktr.alq_max is the maximum number of entries that will be recorded to disk, or 0 for infinite. This is helpful for limiting the number of particularly high frequency entries that are recorded. .It Va debug.ktr.alq_depth determines the number of entries in the write buffer. This is the buffer that holds entries before they are written to disk and defaults to the value of the .Dv KTR_ENTRIES option. .It Va debug.ktr.alq_failed records the number of times we failed to write an entry due to overflowing the write buffer. This may happen if the frequency of the logged .Nm messages outpaces the depth of the queue. .It Va debug.ktr.alq_cnt records the number of entries that have currently been written to disk. .El .Sh SEE ALSO .Xr ktrdump 8 , .Xr alq 9 , .Xr ktr 9 .Sh HISTORY The KTR kernel tracing facility first appeared in .Bsx 3.0 and was imported into .Fx 5.0 . Index: stable/9/share/man/man4/man4.powerpc/abtn.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/abtn.4 (revision 237215) +++ stable/9/share/man/man4/man4.powerpc/abtn.4 (revision 237216) @@ -1,115 +1,115 @@ .\"- .\" Copyright (c) 2011 Justin Hibbits .\" Copyright (c) 2009 Nathan Whitehorn .\" 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 ``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 October 16, 2011 .Dt ABTN 4 .Os .Sh NAME .Nm abtn .Nd ADB Keyboard Special Keys 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 adb" .Ed .Sh DESCRIPTION The .Nm driver provides support for the extended Fn keys on Apple notebooks with an ADB interface. .Sh HARDWARE The .Nm driver supports extended keyboard keys (special F-keys) on the following devices: .Pp .Bl -bullet -compact .It Apple iBook Keyboard .It Apple PowerBook Keyboard .El .Sh EVENTS The .Nm driver sends events to .Xr devd 8 -for the following events under the +for the following events under the .Cd PMU system, and .Cd keys subsystem: .Pp .Bl -bullet -compact .It .Cd brightness - Generates .Cd up and .Cd down notify types matching the pressed key. .It .Cd mute .It .Cd volume - Generates .Cd up and .Cd down notify types matching the pressed key. .It .Cd eject .El .Pp Examples are included in /etc/devd/apple.conf. .Sh SEE ALSO .Xr adb 4 , .Xr akbd 4 , .Xr cuda 4 , .Xr pmu 4, .Xr devd 8 .Sh HISTORY The .Nm device driver first appeared in .Nx 5.0 and was ported to .Fx 10.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Tsubai Masanari for .Nx and ported to .Fx by .An Justin Hibbits . Index: stable/9/share/man/man4/man4.powerpc/akbd.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/akbd.4 (revision 237215) +++ stable/9/share/man/man4/man4.powerpc/akbd.4 (revision 237216) @@ -1,105 +1,105 @@ .\"- .\" Copyright (c) 2009 Nathan Whitehorn .\" 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 ``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 December 3, 2009 .Dt AKBD 4 .Os .Sh NAME .Nm akbd .Nd ADB Keyboard 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 adb" .Ed .Sh DESCRIPTION The .Nm driver provides support for all keyboards attached to the Apple Desktop Bus (ADB). .Sh HARDWARE Devices supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple Extended Keyboard .It Apple Keyboard II .It Apple iBook Keyboard .It Apple PowerBook Keyboard .El .Sh EVENTS The .Nm driver sends events to .Xr devd 8 -for the following events under the +for the following events under the .Cd PMU system: .Pp .Bl -bullet -compact .It -Power button - +Power button - .Cd "Button" -subsystem, +subsystem, .Cd "pressed" type. .El .Sh SYSCTL VARIABLES The .Nm driver supports the following sysctl variable for configuring the Fn keys: .Bl -tag -width indent .It Va dev.akbd.%d.fn_keys_function_as_primary -Set the Fn keys to be their F-key type as default. A value of 0 causes the +Set the Fn keys to be their F-key type as default. A value of 0 causes the F-keys keys to work as special keys by default ( .Xr abtn 4 ) and a value of 1 sets them to behave as F-keys by default. .El .Sh SEE ALSO .Xr abtn 4 , .Xr adb 4 , .Xr cuda 4 , .Xr pmu 4 .Sh HISTORY The .Nm device driver appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Nathan Whitehorn .Aq nwhitehorn@FreeBSD.org . Index: stable/9/share/man/man4/man4.powerpc/bm.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/bm.4 (revision 237215) +++ stable/9/share/man/man4/man4.powerpc/bm.4 (revision 237216) @@ -1,89 +1,89 @@ .\"- .\" Copyright (c) 2008 Nathan Whitehorn .\" 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 ``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 July 3, 2008 .Dt BM 4 .Os .Sh NAME .Nm bm .Nd BMAC Ethernet device 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 miibus" .Cd "device bm" .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_bm_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for the BMac ethernet hardware found mostly in -G3-based Apple hardware. -It is a close relative of the Sun HME controller found in contemporary +G3-based Apple hardware. +It is a close relative of the Sun HME controller found in contemporary Sun workstations. .Sh HARDWARE .Pp Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple BMAC Onboard Ethernet .It Apple BMAC+ Onboard Ethernet .El .Pp .Sh SEE ALSO .Xr altq 4 , .Xr hme 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver appeared in .Fx 7.1 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Nathan Whitehorn .Aq nwhitehorn@FreeBSD.org based on work by .An Peter Grehan .Aq grehan@FreeBSD.org . Index: stable/9/share/man/man4/man4.powerpc/cuda.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/cuda.4 (revision 237215) +++ stable/9/share/man/man4/man4.powerpc/cuda.4 (revision 237216) @@ -1,79 +1,79 @@ .\"- .\" Copyright (c) 2009 Nathan Whitehorn .\" 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 ``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 December 3, 2009 .Dt CUDA 4 .Os .Sh NAME .Nm cuda .Nd Apple CUDA I/O Controller 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 adb" .Cd "device cuda" .Ed .Sh DESCRIPTION The .Nm driver provides support for the CUDA VIA (Versatile Interface Attachment) chip found in pre-Core99 Apple hardware, such as the Power Macintosh G3. .Pp The Apple CUDA controller is a multi-purpose ASIC that provides power -control and an +control and an .Xr adb 4 interface. .Sh HARDWARE Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple CUDA I/O Controller .El .Sh SEE ALSO .Xr adb 4 .Sh HISTORY The .Nm device driver appeared in .Nx 4.0 , and then in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Michael Lorenz .Aq macallan@NetBSD.org and ported to FreeBSD by .An Nathan Whitehorn .Aq nwhitehorn@FreeBSD.org . Index: stable/9/share/man/man4/man4.powerpc/smu.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/smu.4 (revision 237215) +++ stable/9/share/man/man4/man4.powerpc/smu.4 (revision 237216) @@ -1,125 +1,125 @@ .\"- .\" Copyright (c) 2010 Nathan Whitehorn .\" 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 ``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 22, 2010 .Dt SMU 4 .Os .Sh NAME .Nm smu .Nd Apple System Management Unit 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 smu" .Ed .Sh DESCRIPTION The .Nm driver provides support for the System Management Unit (SMU) found in many Apple G5 systems. This includes most Power Macintosh G5 and all iMac G5 systems. .Pp The Apple SMU controller provides software power management and thermal control functionality, and is responsible for managing system cooling devices. .Sh HARDWARE Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple System Management Unit .El .Sh THERMAL MANAGEMENT The .Nm driver provides basic automatic thermal management. Without a userspace daemon providing more advanced control, the driver will attempt to maintain system temperatures in a conservative range through coarse-grained control of system cooling devices (see below). Automatic kernel-level thermal control will take over if more than 3 seconds elapses between userspace cooling setting adjustments. .Sh SYSCTL VARIABLES The .Nm driver provides power management services and thermal readout through a sysctl interface. The following sysctls can be used to control the power management behavior and to examine current system power and thermal conditions. .Bl -tag -width indent .It Va dev.smu.%d.server_mode Restart after power failure behavior (1 causes system to reboot after power cut, 0 causes system to remain off). .It Va dev.smu.%d.target_temp Target system temperature, in degrees Celsius. The .Nm driver will attempt to adjust fans to maintain the temperature of the warmest component in the system at or below this level. .It Va dev.smu.%d.critical_temp System critical temperature, in degrees Celsius. If any component in the system exceeds this temperature, the machine will be shut down within 500 ms. .It Va dev.smu.%d.fans.%s.minrpm Minimum allowed speed for this fan. .It Va dev.smu.%d.fans.%s.maxrpm Maximum allowed speed for this fan. .It Va dev.smu.%d.fans.%s.rpm Current speed for this fan. The fan speed can be adjusted by changing this sysctl. If more than 3 seconds elapses between fan speed adjustments, the kernel will resume automatic control of the fan. .It Va dev.smu.%d.sensors.%s Current reading from this sensor. Four sensor types are supported. Temperature sensors are in units of degrees Celsius, current sensors in milliamps, voltage sensors in millivolts, and power sensors in milliwatts. .El .Sh LED INTERFACE The .Nm -driver provides an +driver provides an .Xr led 4 annunciator interface at .Pa /dev/led/sleepled . .Sh SEE ALSO .Xr acpi 4 , .Xr pmu 4 , .Xr led 4 .Sh HISTORY The .Nm device driver appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Nathan Whitehorn .Aq nwhitehorn@FreeBSD.org . Index: stable/9/share/man/man4/man4.powerpc/snd_ai2s.4 =================================================================== --- stable/9/share/man/man4/man4.powerpc/snd_ai2s.4 (revision 237215) +++ stable/9/share/man/man4/man4.powerpc/snd_ai2s.4 (revision 237216) @@ -1,90 +1,90 @@ .\"- .\" Copyright (c) 2009 Nathan Whitehorn .\" 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 ``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 January 20, 2009 .Dt SND_AI2S 4 .Os .Sh NAME .Nm snd_ai2s .Nd "Apple I2S audio device 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 sound" .Cd "device snd_ai2s" .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 snd_ai2s_load="YES" .Ed .Sh DESCRIPTION The .Nm -driver provides support for the Apple I2S audio controllers found +driver provides support for the Apple I2S audio controllers found predominantly in G4 and G5 machines, along with the snapper and tumbler codecs. Some machines (e.g. the Mac Mini) do not have configurable codecs and so lack hardware volume control. .Sh HARDWARE .Pp Chips supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Apple Tumbler Audio .It Apple Snapper Audio .El .Pp .Sh SEE ALSO .Xr sound 4 , .Xr snd_davbus 4 .Sh HISTORY The .Nm device driver appeared in .Nx 2.0 and then in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Tsubai Masanari .Aq tsubai@netbsd.org , and ported to FreeBSD by .An Marco Trillo .Aq marcotrillo@gmail.com . .Sh BUGS Recording and operation with non-44.1 Khz audio are not currently supported. Index: stable/9/share/man/man4/md.4 =================================================================== --- stable/9/share/man/man4/md.4 (revision 237215) +++ stable/9/share/man/man4/md.4 (revision 237216) @@ -1,114 +1,114 @@ .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" .\" $FreeBSD$ .\" .Dd October 30, 2007 .Dt MD 4 .Os .Sh NAME .Nm md .Nd memory disk .Sh SYNOPSIS .Cd device md .Sh DESCRIPTION The .Nm driver provides support for four kinds of memory backed virtual disks: .Bl -tag -width preload .It Cm malloc Backing store is allocated using .Xr malloc 9 . Only one malloc-bucket is used, which means that all .Nm devices with .Cm malloc backing must share the malloc-per-bucket-quota. The exact size of this quota varies, in particular with the amount of RAM in the system. The exact value can be determined with .Xr vmstat 8 . .It Cm preload A file loaded by .Xr loader 8 with type .Sq md_image is used for backing store. For backwards compatibility the type .Sq mfs_root is also recognized. If the kernel is created with option .Dv MD_ROOT the first preloaded image found will become the root file system. .It Cm vnode A regular file is used as backing store. This allows for mounting ISO images without the tedious detour over actual physical media. .It Cm swap Backing store is allocated from buffer memory. Pages get pushed out to the swap when the system is under memory pressure, otherwise they stay in the operating memory. Using .Cm swap backing is generally preferable over .Cm malloc backing. .El .Pp For more information, please see .Xr mdconfig 8 . .Sh EXAMPLES To create a kernel with a ramdisk or MD file system, your kernel config needs the following options: .Bd -literal -offset indent options MD_ROOT # MD is a potential root device options MD_ROOT_SIZE=8192 # 8MB ram disk makeoptions MFS_IMAGE=/h/foo/ARM-MD options ROOTDEVNAME=\\"ufs:md0\\" .Ed .Pp The image in .Pa /h/foo/ARM-MD will be loaded as the initial image each boot. To create the image to use, please follow the steps to create a file-backed -disk found in the +disk found in the .Xr mdconfig 8 man page. Other tools will also create these images, such as NanoBSD. .Sh SEE ALSO .Xr disklabel 8 , .Xr fdisk 8 , .Xr loader 8 , .Xr mdconfig 8 , .Xr mdmfs 8 , .Xr newfs 8 , .Xr vmstat 8 .Sh HISTORY The .Nm driver first appeared in .Fx 4.0 as a cleaner replacement for the MFS functionality previously used in .Tn PicoBSD and in the .Fx installation process. .Pp The .Nm driver did a hostile takeover of the .Xr vn 4 driver in .Fx 5.0 . .Sh AUTHORS The .Nm driver was written by .An Poul-Henning Kamp .Aq phk@FreeBSD.org . Index: stable/9/share/man/man4/mos.4 =================================================================== --- stable/9/share/man/man4/mos.4 (revision 237215) +++ stable/9/share/man/man4/mos.4 (revision 237216) @@ -1,97 +1,97 @@ .\" .\" Copyright (c) 2011 Rick van der Zwet .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd February 14, 2011 .Dt MOS 4 .Os .Sh NAME .Nm mos .Nd Moschip MCS7730/MCS7840 USB Ethernet 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 uhci" .Cd "device ohci" .Cd "device ehci" .Cd "device usb" .Cd "device miibus" .Cd "device mos" .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_mos_load="YES" .Ed .Sh DESCRIPTION The .Nm -driver provides support for USB Ethernet adapters based on the +driver provides support for USB Ethernet adapters based on the Moschip MCS7730/MCS7830 chipset. .Pp The adapters that contain the Moschip MCS7730/MCS7830 chipset will operate at 100Base-TX and full-duplex. .Pp The Moschip contains a 10/100 Ethernet MAC with MII interface and is designed to work with both Ethernet and HomePNA transceivers. Although designed to interface with 100Mbps peripherals, this only works with USB 2.0. The existing USB 1.0 standard specifies a maximum transfer speed of 12Mbps. USB 1.0 Users should therefore not expect to actually achieve 100Mbps speeds with these devices. .Pp The Moschip supports a 64-bit multicast hash table, single perfect filter entry for the station address and promiscuous mode. Packets are received and transmitted over separate USB bulk transfer endpoints. .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE Adapters supported by the .Nm driver include: .Pp .Bl -bullet -compact .It Sitecom LN030 .El .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr ifconfig 8 .Rs .%T ADMtek AN986 data sheet .%O http://www.moschip.com/data/products/MCS7830/Data%20Sheet_7830.pdf .Re .Sh HISTORY The .Nm device driver first appeared in .Fx 8.2 . .Sh AUTHORS The .Nm driver was written by .An Rick van der Zwet info@rickvanderzwet.nl . Index: stable/9/share/man/man4/mps.4 =================================================================== --- stable/9/share/man/man4/mps.4 (revision 237215) +++ stable/9/share/man/man4/mps.4 (revision 237216) @@ -1,216 +1,216 @@ -.\" +.\" .\" Copyright (c) 2010 Spectra Logic Corporation .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. -.\" +.\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. -.\" +.\" .\" mps driver man page. .\" .\" Author: Ken Merry .\" .\" $Id: //depot/SpectraBSD/head/share/man/man4/mps.4#6 $ .\" $FreeBSD$ .\" .Dd February 7, 2012 .Dt MPS 4 .Os .Sh NAME .Nm mps .Nd LSI Fusion-MPT 2 Serial Attached SCSI driver .Sh SYNOPSIS To compile this driver into your kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device scbus" .Cd "device mps" .Ed .Pp Or, to load the driver as a module at boot, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent mps_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for LSI Logic Fusion-MPT 2 .Tn SAS controllers and WarpDrive solid state storage cards. .Sh HARDWARE The .Nm driver supports the following controllers: .Pp .Bl -bullet -compact .It LSI Logic SAS2004 (4 Port .Tn SAS ) .It LSI Logic SAS2008 (8 Port .Tn SAS ) .It LSI Logic SAS2108 (8 Port .Tn SAS ) .It LSI Logic SAS2116 (16 Port .Tn SAS ) .It LSI Logic SAS2208 (8 Port .Tn SAS ) .El .Sh CONFIGURATION To disable MSI interrupts for all .Nm driver instances, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.disable_msi=1 .Ed .Pp To disable MSI interrupts for a specific .Nm driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.disable_msi=1 .Ed .Pp where X is the adapter number. .Pp To disable MSI-X interrupts for all .Nm driver instances, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.disable_msix=1 .Ed .Pp To disable MSI-X interrupts for a specific .Nm driver instance, set the following tunable value in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.disable_msix=1 .Ed .Pp To set the maximum number of DMA chains allocated for all adapters, -set the following variable in +set the following variable in .Xr loader.conf 5 : .Bd -literal -offset indent hw.mps.max_chains=NNNN .Ed .Pp To set the maximum number of DMA chains allocated for a specific adapter, set the following variable in .Xr loader.conf 5 : .Bd -literal -offset indent dev.mps.X.max_chains=NNNN .Ed .Pp This variable may also be viewed via .Xr sysctl 8 to see the maximum set for a given adapter. .Pp The current number of free chain frames may be seen via the dev.mps.X.chain_free .Xr sysctl 8 variable. .Pp The lowest number of free chain frames may be seen via the dev.mps.X.chain_free_lowwater .Xr sysctl 8 variable. .Pp The current number of active I/O commands is shown in the dev.mps.X.io_cmds_active .Xr sysctl 8 variable. .Pp The maximum number of active I/O command seen since boot is shown in the dev.mps.X.io_cmds_highwater .Xr sysctl 8 variable. .Sh DEBUGGING To enable debugging prints from the .Nm driver, set the .Bd -literal -offset indent hw.mps.X.debug_level .Ed .Pp variable, where X is the adapter number, either in .Xr loader.conf 5 or via .Xr sysctl 8 . The following bits have the described effects: .Bl -tag -offset indent .It 0x01 Enable informational prints. .It 0x02 Enable tracing prints. .It 0x04 Enable prints for driver faults. .It 0x08 Enable prints for controller events. .El .Sh SEE ALSO .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr mpt 4 , .Xr pci 4 , .Xr sa 4 , .Xr scsi 4 , .Xr targ 4 , .Xr loader.conf 5 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit The .Nm driver was originally written by .An Scott Long Aq scottl@FreeBSD.org . It has been improved and tested by LSI Logic Corporation. This man page was written by .An Ken Merry Aq ken@FreeBSD.org . .Sh BUGS This driver has a couple of known shortcomings: .Bl -bullet -compact .It Not endian safe. It only works on little endian machines (e.g. amd64 and i386). -.It +.It No userland utility available (e.g. .Xr mptutil 8 ) . .It The driver probes devices sequentially. If your system has a large number of devices, the probe will take a while. .El Index: stable/9/share/man/man4/netmap.4 =================================================================== --- stable/9/share/man/man4/netmap.4 (revision 237215) +++ stable/9/share/man/man4/netmap.4 (revision 237216) @@ -1,299 +1,299 @@ .\" Copyright (c) 2011 Matteo Landi, Luigi Rizzo, Universita` di Pisa .\" 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. -.\" +.\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .\" $FreeBSD$ .\" $Id: netmap.4 9662 2011-11-16 13:18:06Z luigi $: stable/8/share/man/man4/bpf.4 181694 2008-08-13 17:45:06Z ed $ .\" .Dd November 16, 2011 .Dt NETMAP 4 .Os .Sh NAME .Nm netmap .Nd a framework for fast packet I/O .Sh SYNOPSIS .Cd device netmap .Sh DESCRIPTION .Nm is a framework for fast and safe access to network devices (reaching 14.88 Mpps at less than 1 GHz). .Nm uses memory mapped buffers and metadata (buffer indexes and lengths) to communicate with the kernel, -which is in charge of validating information through +which is in charge of validating information through .Pa ioctl() and .Pa select()/poll() . .Nm can exploit the parallelism in multiqueue devices and multicore systems. .Pp .Pp .Nm requires explicit support in device drivers. For a list of supported devices, see the end of this manual page. .Sh OPERATION .Nm clients must first open the .Pa open("/dev/netmap") , and then issue an .Pa ioctl(...,NIOCREGIF,...) to bind the file descriptor to a network device. .Pp When a device is put in .Nm mode, its data path is disconnected from the host stack. -The processes owning the file descriptor +The processes owning the file descriptor can exchange packets with the device, or with the host stack, through an mmapped memory region that contains pre-allocated buffers and metadata. .Pp Non blocking I/O is done with special .Pa ioctl()'s , whereas the file descriptor can be passed to .Pa select()/poll() to be notified about incoming packet or available transmit buffers. .Ss Data structures All data structures for all devices in .Nm mode are in a memory region shared by the kernel and all processes who open .Pa /dev/netmap (NOTE: visibility may be restricted in future implementations). All references between the shared data structure are relative (offsets or indexes). Some macros help converting them into actual pointers. .Pp The data structures in shared memory are the following: .Pp .Bl -tag -width XXX .It Dv struct netmap_if (one per interface) indicates the number of rings supported by an interface, their sizes, and the offsets of the .Pa netmap_rings associated to the interface. The offset of a .Pa struct netmap_if in the shared memory region is indicated by the .Pa nr_offset field in the structure returned by the .Pa NIOCREGIF (see below). .Bd -literal struct netmap_if { char ni_name[IFNAMSIZ]; /* name of the interface. */ const u_int ni_num_queues; /* number of hw ring pairs */ const ssize_t ring_ofs[]; /* offset of tx and rx rings */ }; .Ed .It Dv struct netmap_ring (one per ring) contains the index of the current read or write slot (cur), the number of slots available for reception or transmission (avail), and an array of .Pa slots describing the buffers. There is one ring pair for each of the N hardware ring pairs supported by the card (numbered 0..N-1), plus one ring pair (numbered N) for packets from/to the host stack. .Bd -literal struct netmap_ring { const ssize_t buf_ofs; const uint32_t num_slots; /* number of slots in the ring. */ uint32_t avail; /* number of usable slots */ uint32_t cur; /* 'current' index for the user side */ const uint16_t nr_buf_size; uint16_t flags; struct netmap_slot slot[0]; /* array of slots. */ } .Ed .It Dv struct netmap_slot (one per packet) contains the metadata for a packet: a buffer index (buf_idx), a buffer length (len), and some flags. .Bd -literal struct netmap_slot { uint32_t buf_idx; /* buffer index */ uint16_t len; /* packet length */ uint16_t flags; /* buf changed, etc. */ #define NS_BUF_CHANGED 0x0001 /* must resync, buffer changed */ #define NS_REPORT 0x0002 /* tell hw to report results * e.g. by generating an interrupt */ }; .Ed .It Dv packet buffers are fixed size (approximately 2k) buffers allocated by the kernel that contain packet data. Buffers addresses are computed through macros. .El .Pp Some macros support the access to objects in the shared memory region. In particular: .Bd -literal struct netmap_if *nifp; struct netmap_ring *txring = NETMAP_TXRING(nifp, i); struct netmap_ring *rxring = NETMAP_RXRING(nifp, i); int i = txring->slot[txring->cur].buf_idx; char *buf = NETMAP_BUF(txring, i); .Ed .Ss IOCTLS .Pp .Nm supports some ioctl() to synchronize the state of the rings between the kernel and the user processes, plus some to query and configure the interface. The former do not require any argument, whereas the latter use a .Pa struct netmap_req defined as follows: .Bd -literal struct nmreq { char nr_name[IFNAMSIZ]; uint32_t nr_offset; /* nifp offset in the shared region */ uint32_t nr_memsize; /* size of the shared region */ uint32_t nr_numdescs; /* descriptors per queue */ uint16_t nr_numqueues; uint16_t nr_ringid; /* ring(s) we care about */ #define NETMAP_HW_RING 0x4000 /* low bits indicate one hw ring */ #define NETMAP_SW_RING 0x2000 /* we process the sw ring */ #define NETMAP_NO_TX_POLL 0x1000 /* no gratuitous txsync on poll */ #define NETMAP_RING_MASK 0xfff /* the actual ring number */ }; .Ed A device descriptor obtained through .Pa /dev/netmap also supports the ioctl supported by network devices. .Pp The netmap-specific .Xr ioctl 2 command codes below are defined in .In net/netmap.h and are: .Bl -tag -width XXXX .It Dv NIOCGINFO returns information about the interface named in nr_name. On return, nr_memsize indicates the size of the shared netmap memory region (this is device-independent), nr_numslots indicates how many buffers are in a ring, nr_numrings indicates the number of rings supported by the hardware. .Pp If the device does not support netmap, the ioctl returns EINVAL. .It Dv NIOCREGIF puts the interface named in nr_name into netmap mode, disconnecting it from the host stack, and/or defines which rings are controlled through this file descriptor. On return, it gives the same info as NIOCGINFO, and nr_ringid indicates the identity of the rings controlled through the file descriptor. .Pp Possible values for nr_ringid are .Bl -tag -width XXXXX .It 0 default, all hardware rings .It NETMAP_SW_RING the ``host rings'' connecting to the host stack .It NETMAP_HW_RING + i the i-th hardware ring .El By default, a .Nm poll or .Nm select call pushes out any pending packets on the transmit ring, even if no write events are specified. The feature can be disabled by or-ing .Nm NETMAP_NO_TX_SYNC to nr_ringid. But normally you should keep this feature unless you are using separate file descriptors for the send and receive rings, because otherwise packets are pushed out only if NETMAP_TXSYNC is called, or the send queue is full. .Pp .Pa NIOCREGIF can be used multiple times to change the association of a file descriptor to a ring pair, always within the same device. .It Dv NIOCUNREGIF brings an interface back to normal mode. .It Dv NIOCTXSYNC tells the hardware of new packets to transmit, and updates the number of slots available for transmission. .It Dv NIOCRXSYNC tells the hardware of consumed packets, and asks for newly available packets. .El .Ss SYSTEM CALLS .Nm uses .Nm select and .Nm poll to wake up processes when significant events occur. .Sh EXAMPLES The following code implements a traffic generator .Pp .Bd -literal -compact #include #include struct netmap_if *nifp; struct netmap_ring *ring; struct netmap_request nmr; fd = open("/dev/netmap", O_RDWR); bzero(&nmr, sizeof(nmr)); strcpy(nmr.nm_name, "ix0"); ioctl(fd, NIOCREG, &nmr); p = mmap(0, nmr.memsize, fd); nifp = NETMAP_IF(p, nmr.offset); ring = NETMAP_TXRING(nifp, 0); fds.fd = fd; fds.events = POLLOUT; for (;;) { poll(list, 1, -1); while (ring->avail-- > 0) { i = ring->cur; buf = NETMAP_BUF(ring, ring->slot[i].buf_index); ... prepare packet in buf ... ring->slot[i].len = ... packet length ... ring->cur = NETMAP_RING_NEXT(ring, i); } } .Ed .Sh SUPPORTED INTERFACES .Nm supports the following interfaces: .Xr em 4 , .Xr ixgbe 4 , .Xr re 4 , .Sh AUTHORS The .Nm framework has been designed and implemented by .An Luigi Rizzo and .An Matteo Landi in 2011 at the Universita` di Pisa. Index: stable/9/share/man/man4/ng_patch.4 =================================================================== --- stable/9/share/man/man4/ng_patch.4 (revision 237215) +++ stable/9/share/man/man4/ng_patch.4 (revision 237216) @@ -1,235 +1,235 @@ .\" Copyright (c) 2010 Maxim Ignatenko .\" Copyright (c) 2010 Vadim Goncharov .\" 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. .\" .\" $FreeBSD$ .\" .Dd March 5, 2012 .Dt NG_PATCH 4 .Os .Sh NAME .Nm ng_patch .Nd "trivial mbuf data modifying netgraph node type" .Sh SYNOPSIS .In netgraph/ng_patch.h .Sh DESCRIPTION The .Nm patch node performs data modification of packets passing through it. Modifications are restricted to a subset of C language operations on unsigned integers of 8, 16, 32 or 64 bit size. These are: set to new value (=), addition (+=), subtraction (-=), multiplication (*=), division (/=), negation (= -), bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=), shift left (<<=), shift right (>>=). A negation operation is the one exception: integer is treated as signed and second operand (the .Va value ) is not used. There may be several modification operations, they are all applied to a packet sequentially in order they were specified by user. Data payload of packet is viewed as array of bytes, with zero offset corresponding to the very first byte of packet headers, and .Va length bytes beginning from .Va offset are taken as a single integer in network byte order. .Sh HOOKS This node type has two hooks: .Bl -tag -width indent .It Va in Packets received on this hook are modified according to rules specified in config and then forwarded to .Ar out hook, if it exists and connected. Otherwise they are reflected back to the .Ar in hook. .It Va out Packets received on this hook are forwarded to .Ar in hook without any changes. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width indent .It Dv NGM_PATCH_SETCONFIG Pq Li setconfig This command sets the sequence of modify operations that will be applied to incoming data on a hook. The following .Vt "struct ng_patch_config" must be supplied as an argument: .Bd -literal -offset 4n struct ng_patch_op { uint64_t value; uint32_t offset; uint16_t length; /* 1,2,4 or 8 bytes */ uint16_t mode; }; /* Patching modes */ #define NG_PATCH_MODE_SET 1 #define NG_PATCH_MODE_ADD 2 #define NG_PATCH_MODE_SUB 3 #define NG_PATCH_MODE_MUL 4 #define NG_PATCH_MODE_DIV 5 #define NG_PATCH_MODE_NEG 6 #define NG_PATCH_MODE_AND 7 #define NG_PATCH_MODE_OR 8 #define NG_PATCH_MODE_XOR 9 #define NG_PATCH_MODE_SHL 10 #define NG_PATCH_MODE_SHR 11 struct ng_patch_config { uint32_t count; uint32_t csum_flags; struct ng_patch_op ops[]; }; .Ed .Pp The .Va csum_flags can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_SCTP and CSUM_UDP (other values are ignored) for instructing the IP stack to recalculate the corresponding checksum before transmitting packet on output interface. The .Nm node does not do any checksum correction by itself. .It Dv NGM_PATCH_GETCONFIG Pq Li getconfig This control message obtains current set of modify operations, returned as .Vt "struct ng_patch_config" . .It Dv NGM_PATCH_GET_STATS Pq Li getstats Returns node statistics as a .Vt "struct ng_patch_stats" . .It Dv NGM_PATCH_CLR_STATS Pq Li clrstats Clear node statistics. .It Dv NGM_PATCH_GETCLR_STATS Pq Li getclrstats This command is identical to .Dv NGM_PATCH_GET_STATS , except that the statistics are also atomically cleared. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLES The .Nm node allows to modify TTL and TOS/DSCP fields in IP packets. Suppose you have two adjacent simplex links to remote network (e.g.\& satellite), so that the packets expiring in between will generate unwanted ICMP-replies which have to go forth, not back. Thus you need to raise TTL of every packet entering link by 2 to ensure the TTL will not reach zero there. So you setup .Xr ipfw 8 rule with .Cm netgraph action to inject packets going to other end of simplex link by the following .Xr ngctl 8 script: .Bd -literal -offset 4n /usr/sbin/ngctl -f- <<-SEQ mkpeer ipfw: patch 200 in name ipfw:200 ttl_add msg ttl_add: setconfig { count=1 csum_flags=1 ops=[ \e { mode=2 value=3 length=1 offset=8 } ] } SEQ /sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net .Ed .Pp Here .Dq Li ttl_add node of type .Nm -configured to add (mode +configured to add (mode .Dv NG_PATCH_MODE_ADD ) a .Va value of 3 to a one-byte TTL field, which is 9th byte of IP packet header. .Pp Another example would be two consecutive modifications of packet TOS field: say, you need to clear the .Dv IPTOS_THROUGHPUT bit and set the .Dv IPTOS_MINCOST bit. So you do: .Bd -literal -offset 4n /usr/sbin/ngctl -f- <<-SEQ mkpeer ipfw: patch 300 in name ipfw:300 tos_chg msg tos_chg: setconfig { count=2 csum_flags=1 ops=[ \e { mode=7 value=0xf7 length=1 offset=1 } \e { mode=8 value=0x02 length=1 offset=1 } ] } SEQ /sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80 .Ed .Pp This first does .Dv NG_PATCH_MODE_AND clearing the fourth bit and then .Dv NG_PATCH_MODE_OR setting the third bit. .Pp In both examples the .Va csum_flags field indicates that IP checksum (but not TCP or UDP checksum) should be recalculated before transmit. .Pp Note: one should ensure that packets are returned to ipfw after processing inside .Xr netgraph 4 , by setting appropriate .Xr sysctl 8 variable: .Bd -literal -offset 4n sysctl net.inet.ip.fw.one_pass=0 .Ed .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ipfw 4 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 8.1 . .Sh AUTHORS .An "Maxim Ignatenko" Aq gelraen.ua@gmail.com . This manual page was written by .An "Vadim Goncharov" Aq vadimnuclight@tpu.ru . .Sh BUGS Node blindly tries to apply every patching operation to each packet (except those which offset if greater than length of the packet), so be sure that you supply only the right packets to it (e.g. changing bytes in the ARP packets meant to be in IP header could corrupt them and make your machine unreachable from the network). .Pp .Em !!! WARNING !!! .Pp Output path of the IP stack assumes correct fields and lengths in the packets - changing them by mistake to incorrect values can cause unpredictable results including kernel panics. Index: stable/9/share/man/man4/nvram2env.4 =================================================================== --- stable/9/share/man/man4/nvram2env.4 (revision 237215) +++ stable/9/share/man/man4/nvram2env.4 (revision 237216) @@ -1,119 +1,119 @@ .\" Copyright (c) 2011 Aleksandr Rybalko .\" 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. .\" .\" $FreeBSD$ .\" .Dd April 3, 2011 .Dt NVRAM2ENV 4 .Os .Sh NAME .Nm nvram2env .Nd "copy nvram-like data into kernel environment" .Sh SYNOPSIS .Cd "device nvram2env" .Sh DESCRIPTION .Nm implements a simple method of reading the NVRAM-like data and information stored in flash and storing it in the kernel environment. It can then be used by various device drivers at boot-time. .Pp The NVRAM-like data is an array of zero terminated strings. Each string contains the string name, "=" delimiter and the string value. .Pp .Nm copies the environment values into kernel environment using the kernel setenv call. .Pp -Configuration of +Configuration of .Nm is done in .Xr device.hints 5 defining the NVRAM base address, fallback base address, maxsize and flags. .Pp .Nm is currently MIPS-specific. .Ss base base - physical address where data block is stored. .Ss fallbackbase fallbackbase - physical address where data block is stored, but only if not found at base. .Ss maxsize maxsize - maximum size of data block. .Ss flags flags - control flags, used to select nvram type and enable/disable CRC check. .Bl -tag -width indent .It Fa 0x0001 Avoid CRC checking. Currently CRC checking is not implemented, so to be future compatible, please set it to "1". .It Fa 0x0002 Use format "Generic", skip uint32_t field, then zero terminating array of strings. .It Fa 0x0004 -Use Broadcom CFE format. uint32_t signature "FLSH", uint32_t size, +Use Broadcom CFE format. uint32_t signature "FLSH", uint32_t size, three unused fields uint32_t, then data. .It Fa 0x0008 Use U-Boot format, uint32_t crc, then zero terminating array of strings. .El .Sh EXAMPLES Usage in U-Boot case: .Bd -literal -offset indent hint.nvram.0.base=0x1f030000 hint.nvram.0.maxsize=0x2000 hint.nvram.0.flags=3 # 1 = No check, 2 = Format Generic hint.nvram.1.base=0x1f032000 hint.nvram.1.maxsize=0x4000 hint.nvram.1.flags=3 # 1 = No check, 2 = Format Generic .Ed .Pp CFE nvram with fallback: .Bd -literal -offset indent hint.nvram.0.base=0x1fff8000 hint.nvram.0.fallbackbase=0x1fc00400 hint.nvram.0.flags=4 # 4 = Format Broadcom .Ed .Pp but seems for CFE nvram preferred to read both blocks: .Pp NVRAM partition: Static, CFE internal .Bd -literal -offset indent hint.nvram.0.flags=0x05 # Broadcom + nocheck hint.nvram.0.base=0x1fc00400 .Ed .Pp Dynamic, editable form CFE, override values from first .Pp .Bd -literal -offset indent hint.nvram.1.flags=0x05 # Broadcom + nocheck hint.nvram.1.base=0x1cff8000 .Ed .Sh SEE ALSO .Xr kenv 1 , .Xr kenv 2 . .Sh HISTORY .Nm first appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit .Nm .An Aleksandr Rybalko Aq ray@ddteam.net . Index: stable/9/share/man/man4/nxge.4 =================================================================== --- stable/9/share/man/man4/nxge.4 (revision 237215) +++ stable/9/share/man/man4/nxge.4 (revision 237216) @@ -1,97 +1,97 @@ .\" Copyright (c) 2007, Neterion Inc .\" 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 as .\" the first lines of this file unmodified. .\" 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 ``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 October 16, 2007 .Dt NXGE 4 .Os .Sh NAME .Nm nxge .Nd "Neterion Xframe 10GbE Server/Storage adapter driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device nxge" .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_nxge_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for Neterion Xframe-I and Xframe-II adapters. -The driver supports TCP Segmentation Offload (TSO/LSO), -Large Receive Offload (LRO), Jumbo Frames (5 buffer mode), +The driver supports TCP Segmentation Offload (TSO/LSO), +Large Receive Offload (LRO), Jumbo Frames (5 buffer mode), Header Separation (Rx 2 buffer mode), VLAN, and Promiscuous mode. .Pp For general information and support, please visit the Neterion support page .Pa http://www.neterion.com/support/support.html . .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 transmit and receive Jumbo Frames. Xframe adapters support Jumbo Frames up to 9600 bytes. .Pp For Jumbo Frames, the driver will try to allocate physically contiguous buffers. Failures to do so may degrade the performance. To resolve such problems, please visit .Pa http://www.neterion.com where additional information and a kernel patch can be found. .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE The .Nm driver supports Neterion Xframe 10 Gigabit Ethernet adapters listed in .Pa http://www.neterion.com/how/pricing.html . .Sh SUPPORT For troubleshooting tips and FAQs, please visit .Pa http://trac.neterion.com/cgi-bin/trac.cgi/wiki/TitleIndex?anonymous . .Pp For any issues please send an email to .Aq support@neterion.com . .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 7.0 . .Sh AUTHORS The .Nm driver was written by .An Neterion .Aq support@neterion.com . Index: stable/9/share/man/man4/ufoma.4 =================================================================== --- stable/9/share/man/man4/ufoma.4 (revision 237215) +++ stable/9/share/man/man4/ufoma.4 (revision 237216) @@ -1,139 +1,139 @@ .\" Copyright (c) 2006 Takanori Watanabe. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Lennart Augustsson. .\" .\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 November 22, 2006 .Dt UFOMA 4 .Os .Sh NAME .Nm ufoma .Nd USB mobile phone support .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ufoma" .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 ufoma_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for USB mobile phone terminals in the subset of the Mobile Computing Promotion Consortium USB Implementation Guideline, which is adopted by FOMA, the NTT DoCoMo 3G system, terminal. These are partly like CDC ACM model based modems, which are supported by .Xr umodem 4 , but the .Nm driver recognizes a specific USB descriptor that describes its role and interface structure, and it will negotiate its role when the device is open. They support a regular AT command set and the commands can either be multiplexed with the data stream or handled through separate pipes. In the latter case the AT commands have to be given on a device separate from the data device. .Pp The device is accessed through the .Xr ucom 4 driver which makes it behave like a .Xr tty 4 . .Sh SYSCTLS These devices often have a few interface sets and these interfaces have their role, sometimes multiplexed. These roles are identified with the following sysctl MIBs: .Bl -tag -width indent .It Va dev.ucom.%d.supportmode The modes which are supported by the interface. .It Va dev.ucom.%d.currentmode Current mode of the interface. .It Va dev.ucom.%d.openmode Mode to transit when the device is open next. .El The modes are as follows: .Bl -tag -width indent .It Li modem Accepts AT commands and go and pass packet communication data. .It Li handsfree Accepts AT commands but it does not pass data. .It Li obex Accepts OBEX frame which is used to exchange telephone book, etc. .It Li vendor1 , vendor2 Vendor specific data may be passed. .It Li deactivated When an interface is recognized by the system but not used, the interface will be set to this mode. .It Li unlinked When an interface is not yet negotiated, the interface is in this mode. -.El +.El .Sh HARDWARE Devices supported by the .Nm driver include: .Pp .Bl -bullet -compact .It SHARP FOMA SH902i .It KYOCERA PHS AH-K3001V (a.k.a Kyopon) .It SANYO Vodafone3G V801SA .El .Sh SEE ALSO Specification can be found at: .Pp .Bl -item -compact .It .Pa http://www.nttdocomo.co.jp/corporate/technology/document/foma/index.html .It .Pa http://www.mcpc-jp.org/doclist.htm .El .Pp .Xr tty 4 , .Xr ucom 4 , .Xr umodem 4 , .Xr usb 4 .Sh HISTORY The .Nm driver appeared in .Fx 7.0 , partly derived from the .Xr umodem 4 code. .Sh BUGS Interfaces with multiplexed commands and data and interfaces with commands only are supported. Index: stable/9/share/man/man4/upgt.4 =================================================================== --- stable/9/share/man/man4/upgt.4 (revision 237215) +++ stable/9/share/man/man4/upgt.4 (revision 237216) @@ -1,222 +1,222 @@ .\" $OpenBSD: upgt.4,v 1.6 2008/04/17 14:01:22 jmc Exp $ .\" $FreeBSD$ .\" .\" Copyright (c) 2007 Marcus Glocker .\" Copyright (c) 2005-2007 .\" Damien Bergamini .\" .\" 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. .\" .\" .\" .\" Copyright (c) 2006 Theo de Raadt. .\" Copyright (c) 2006 The DragonFly Project. 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 DragonFly Project 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 COPYRIGHT HOLDERS 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 .\" COPYRIGHT HOLDERS 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 April 17, 2008 .Dt UPGT 4 .Os .Sh NAME .Nm upgt .Nd Conexant/Intersil PrismGT SoftMAC USB IEEE 802.11b/g wireless network device .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device ehci" .Cd "device uhci" .Cd "device ohci" .Cd "device usb" .Cd "device upgt" .Cd "device wlan" .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_upgt_load="YES" .Ed .Sh DESCRIPTION The .Nm driver supports the USB 2.0 Conexant/Intersil PrismGT series wireless adapters based on the GW3887 chipset. .Pp These are the modes the .Nm driver can operate in: .Bl -tag -width "IBSS-masterXX" .It BSS mode Also known as .Em infrastructure mode, this is used when associating with an access point, through which all traffic passes. This mode is the default. .\" .It IBSS mode .\" Also known as .\" .Em IEEE ad-hoc .\" mode or .\" .Em peer-to-peer .\" mode. .\" This is the standardized method of operating without an access point. .\" Stations associate with a service set. .\" However, actual connections between stations are peer-to-peer. .\" .It Host AP .\" In this mode the driver acts as an access point (base station) .\" for other cards. .It monitor mode In this mode the driver is able to receive packets without associating with an access point. This disables the internal receive filter and enables the card to capture packets from networks which it wouldn't normally have access to, or to scan for access points. .El .Pp .Nm supports software WEP. Wired Equivalent Privacy (WEP) is the de facto encryption standard for wireless networks. It can be typically configured in one of three modes: no encryption; 40-bit encryption; or 104-bit encryption. Unfortunately, due to serious weaknesses in WEP protocol it is strongly recommended that it not be used as the sole mechanism to secure wireless communication. WEP is not enabled by default. .\".Pp .\"The transmit speed is user-selectable or can be adapted automatically by the .\"driver depending on the received signal strength and on the number of hardware .\"transmission retries. .Pp The .Nm driver can be configured at runtime with .Xr ifconfig 8 . .Sh FILES .\".Pp .\"These firmware files are not free because Conexant/Intersil refuses .\"to grant distribution rights. .\"As a result, even though .\".Ox .\"includes the driver, the firmware files cannot be included and .\"users have to download these files on their own. This driver requires the .Nm upgtfw firmware to be installed before it will work. The firmware files are not publicly available. A package of the firmware which can be installed via .Xr pkg_add 1 is available: .Bd -literal -offset indent http://weongyo.org/project/upgt/upgt-firmware-2.13.1.0.tar.gz .Ed .Sh HARDWARE The .Nm driver supports USB 2.0 Conexant/Intersil PrismGT series wireless adapters based on the GW3887 chipset, among them: .Pp .Bl -bullet -compact .It Belkin F5D7050 (version 1000) .It Cohiba Proto Board .It D-Link DWL-G120 Cohiba .It FSC Connect2Air E-5400 USB D1700 .It Gigaset USB Adapter 54 .It Inventel UR045G .It SMC EZ ConnectG SMC2862W-G .It Sagem XG703A .It Spinnaker DUT .It Spinnaker Proto Board .El .Sh EXAMPLES Join an existing BSS network (i.e., connect to an access point): .Bd -literal -offset indent ifconfig wlan create wlandev upgt0 inet 192.168.0.20 \e netmask 0xffffff00 -.Ed -.Pp +.Ed +.Pp Join a specific BSS network with network name -.Dq Li my_net : -.Pp +.Dq Li my_net : +.Pp .Dl "ifconfig wlan create wlandev upgt0 ssid my_net up" -.Pp +.Pp Join a specific BSS network with 64-bit WEP encryption: .Bd -literal -offset indent ifconfig wlan create wlandev upgt0 ssid my_net \e wepmode on wepkey 0x1234567890 weptxkey 1 up .Ed .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr usb 4 , .Xr wlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm driver first appeared in .Ox 4.3 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Marcus Glocker Aq mglocker@openbsd.org . .Pp The hardware specification was reverse engineered by the people at .Pa http://www.prism54.org . .Sh CAVEATS The .Nm driver just supports the USB 2.0 devices (GW3887 chipset) but not the USB 1.0 devices containing the NET2280, ISL3880, and ISL3886 chipsets. Some further efforts would be necessary to add USB 1.0 support to the driver. Index: stable/9/share/man/man4/wbwd.4 =================================================================== --- stable/9/share/man/man4/wbwd.4 (revision 237215) +++ stable/9/share/man/man4/wbwd.4 (revision 237216) @@ -1,117 +1,117 @@ .\"- .\" Copyright (c) 2012 Bjoern A. Zeeb .\" 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. .\" .\" $FreeBSD$ .\" .Dd March 6, 2012 .Dt wbwd 4 .Os .Sh NAME .Nm wbwd .Nd device driver for watchdog timer found on Winbond Super I/O chips .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device wbwd" .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 wbwd_load="YES" .Ed .Pp In .Pa /boot/device.hints : .Cd hint.wbwd.0.at="isa" .Sh DESCRIPTION The .Nm driver provides .Xr watchdog 4 support for the watchdog interrupt timer present on at least the following Winbond Super I/O chips: .Pp .Bl -bullet -compact .It 83627HF/F/HG/G Rev. G .It 83627HF/F/HG/G Rev. J .It 83627HF/F/HG/G Rev. UD-A .It 83627DHG IC ver. 5 .El .Sh SYSCTL VARIABLES The .Nm driver provides the following options as .Xr sysctl 8 variables. -.Bl -tag -width "xxxxxx" +.Bl -tag -width "xxxxxx" .It Va dev.wbwd.0.timeout_override This variable allows to program the timer to a value independent on the one provided by the .Xr watchdog 4 framework while still relying on the regular updates from e.g. .Xr watchdogd 8 . This is particularly useful if your system provides multiple watchdogs and you want them to fire in a special sequence to trigger an NMI after a shorter period than the reset timeout for example. The value set must not be lower than the sleep time of .Xr watchdogd 8 . A value of 0 disables this feature and the timeout value provided by .Xr watchdog 4 will be used. .It Va dev.wbwd.0.debug_verbose If set this sysctl will tell the driver to log its current state before and after the timer reset on each invocation from .Xr watchdog 9 to the kernel message buffer for debugging. .It Va dev.wbwd.0.debug This read-only value gives the state of some registers on last update. .El .Pp The .Nm driver also provides further sysctl options that are hidden by default. See the source code for more information. .Sh SEE ALSO .Xr watchdog 4 , .Xr device.hints 5 , .Xr watchdog 8 , .Xr watchdogd 8 , .Xr watchdog 9 .Sh HISTORY The .Nm driver first appeared in .Fx 10.0 . .Sh AUTHORS .An -nosplit This manual page was written by .An Bjoern A. Zeeb Aq bz@FreeBSD.org . Index: stable/9/share/man/man4/xen.4 =================================================================== --- stable/9/share/man/man4/xen.4 (revision 237215) +++ stable/9/share/man/man4/xen.4 (revision 237216) @@ -1,185 +1,185 @@ .\" Copyright (c) 2010 Robert N. M. Watson .\" All rights reserved. .\" -.\" This software was developed by SRI International and the University of +.\" This software was developed by SRI International and the University of .\" Cambridge Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 .\" ("CTSRD"), as part of the DARPA CRASH research program. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd December 17, 2010 .Dt XEN 4 .Os .Sh NAME -.Nm xen +.Nm xen .Nd Xen Hypervisor Guest (DomU) Support .Sh SYNOPSIS To compile para-virtualized (PV) Xen guest support into an i386 kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "options PAE" .Cd "options XEN" .Cd "nooptions NATIVE" .Ed .Pp To compile hardware-assisted virtualization (HVM) Xen guest support with para-virtualized drivers into an amd64 kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "options XENHVM" .Cd "device xenpci" .Ed .Sh DESCRIPTION The Xen Hypervisor allows multiple virtual machines to be run on a single computer system. When first released, Xen required that i386 kernels be compiled "para-virtualized" as the x86 instruction set was not fully virtualizable. Primarily, para-virtualization modifies the virtual memory system to use hypervisor calls (hypercalls) rather than direct hardware instructions to modify the TLB, although para-virtualized device drivers were also required to access resources such as virtual network interfaces and disk devices. .Pp With later instruction set extensions from AMD and Intel to support fully virtualizable instructions, unmodified virtual memory systems can also be supported; this is referred to as hardware-assisted virtualization (HVM). HVM configurations may either rely on transparently emulated hardware peripherals, or para-virtualized drivers, which are aware of virtualization, and hence able to optimize certain behaviors to improve performance or semantics. .Pp .Fx supports a fully para-virtualized (PV) kernel on the i386 architecture using .Cd "options XEN" and .Cd "nooptions NATIVE" ; currently, this requires use of a PAE kernel, enabled via .Cd "options PAE" . .Pp .Fx supports hardware-assisted virtualization (HVM) on both the i386 and amd64 kernels; however, PV device drivers with an HVM kernel are only supported on the amd64 architecture, and require .Cd "options XENHVM" and .Cd "device xenpci" . .Pp Para-virtualized device drivers are required in order to support certain functionality, such as processing management requests, returning idle physical memory pages to the hypervisor, etc. .Ss Xen DomU device drivers Xen para-virtualized drivers are automatically added to the kernel if a PV kernel is compiled using .Cd "options XEN" ; for HVM environments, .Cd "options XENHVM" and .Cd "device xenpci" are required. The follow drivers are supported: .Bl -hang -offset indent -width blkfront .It Nm balloon Allow physical memory pages to be returned to the hypervisor as a result of manual tuning or automatic policy. .It Nm blkback Exports local block devices or files to other Xen domains where they can then be imported via .Nm blkfront . .It Nm blkfront Import block devices from other Xen domains as local block devices, to be used for file systems, swap, etc. .It Nm console Export the low-level system console via the Xen console service. .It Nm control Process management operations from Domain 0, including power off, reboot, suspend, crash, and halt requests. .It Nm evtchn Expose Xen events via the .Pa /dev/xen/evtchn special device. .It Nm netback Export local network interfaces to other Xen domains where they can be imported via .Nm netfront . .It Nm netfront Import network interfaces from other Xen domains as local network interfaces, which may be used for IPv4, IPv6, etc. .It Nm pcifront Allow physical PCI devices to be passed through into a PV domain. .It Nm xenpci Represents the Xen PCI device, an emulated PCI device that is exposed to HVM domains. This device allows detection of the Xen hypervisor, and provides interrupt and shared memory services required to interact with the hypervisor. .El .Ss Performance considerations In general, PV drivers will perform better than emulated hardware, and are the recommended configuration for HVM installations. .Pp Using a hypervisor introduces a second layer of scheduling that may limit the effectiveness of certain .Fx scheduling optimisations. Among these is adaptive locking, which is no longer able to determine whether a thread holding a lock is in execution. It is recommended that adaptive locking be disabled when using Xen: .Bd -unfilled -offset indent .Cd "options NO_ADAPTIVE_MUTEXES" .Cd "options NO_ADAPTIVE_RWLOCKS" .Cd "options NO_ADAPTIVE_SX" .Ed .Sh SEE ALSO .Xr pae 4 .Sh HISTORY Support for .Nm first appeared in .Fx 8.1 . .Sh AUTHORS .An -nosplit .Fx support for Xen was first added by .An Kip Macy Aq kmacy@FreeBSD.org and .An Doug Rabson Aq dfr@FreeBSD.org . Further refinements were made by .An Justin Gibbs Aq gibbs@FreeBSD.org , .An Adrian Chadd Aq adrian@FreeBSD.org , and .An Colin Percival Aq cperciva@FreeBSD.org . This manual page was written by .An Robert Watson Aq rwatson@FreeBSD.org . .Sh BUGS .Fx is only able to run as a Xen guest (DomU) and not as a Xen host (Dom0). .Pp A fully para-virtualized (PV) kernel is only supported on i386, and not amd64. .Pp Para-virtualized drivers under hardware-assisted virtualization (HVM) kernel are only supported on amd64, not i386. .Pp As of this release, Xen PV DomU support is not heavily tested; instability has been reported during VM migration of PV kernels. .Pp Certain PV driver features, such as the balloon driver, are under-exercised. Index: stable/9/share/man/man5/ar.5 =================================================================== --- stable/9/share/man/man5/ar.5 (revision 237215) +++ stable/9/share/man/man5/ar.5 (revision 237216) @@ -1,327 +1,327 @@ .\" Copyright (c) 2010 Joseph Koshy. 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. .\" .\" $FreeBSD$ .\" .Dd November 28, 2010 .Os .Dt AR 5 .Sh NAME .Nm ar .Nd archive file format for .Xr ar 1 and .Xr ranlib 1 .Sh SYNOPSIS .In ar.h .Sh DESCRIPTION .Xr ar 1 archives are created and managed by the .Xr ar 1 and .Xr ranlib 1 utilities. These archives are typically used during program development to hold libraries of program objects. An .Xr ar 1 archive is contained in a single operating system file. .Pp This manual page documents two variants of the .Xr ar 1 archive format: the BSD archive format, and the SVR4/GNU archive format. .Pp In both variants the archive file starts with an identifying byte sequence of the seven ASCII characters .Sq Li "!" followed by a ASCII linefeed character .Po see the constant .Dq ARMAG in the header file .In ar.h .Pc . .Pp Archive members follow the initial identifying byte sequence. Each archive member is prefixed by a fixed size header describing the file attributes associated with the member. .Ss "Archive Headers" An archive header describes the file attributes for the archive member that follows it. The .Xr ar 5 format only supports a limited number of attributes: the file name, the file creation time stamp, the uid and gid of the creator, the file mode and the file size. .Pp Archive headers are placed at an even byte offset in the archive file. If the data for an archive member ends at an odd byte offset, then a padding byte with value 0x0A is used to position the next archive header on an even byte offset. .Pp An archive header comprises the following fixed sized fields: .Bl -tag -width "Li ar_name" .It Ar ar_name (16 bytes) The file name of the archive member. The format of this field varies between the BSD and SVR4/GNU formats and is described in more detail in the section .Sx "Representing File Names" below. .It Ar ar_date (12 bytes) The file modification time for the member in seconds since the epoch, encoded as a decimal number. .It Ar ar_uid (6 bytes) The uid associated with the archive member, encoded as a decimal number. .It Ar ar_gid (6 bytes) The gid associated with the archive member, encoded as a decimal number. .It Ar ar_mode (8 bytes) The file mode for the archive member, encoded as an octal number. .It Ar ar_size (10 bytes) In the SVR4/GNU archive format this field holds the size in bytes of the archive member, encoded as a decimal number. In the BSD archive format, for short file names, this field holds the size in bytes of the archive member, encoded as a decimal number. For long file names .Po see .Sx "Representing File Names" below .Pc , the field contains the combined size of the archive member and its file name, encoded as a decimal number. .It Ar ar_fmag (2 bytes) This field holds 2 bytes with values 0x96 and 0x0A respectively, marking the end of the header. .El .Pp Unused bytes in the fields of an archive header are set to the value 0x20. .Ss "Representing File Names" The BSD and SVR4/GNU variants use different schemes for encoding file names for members. .Bl -tag -width "SVR4/GNU" .It "BSD" File names that are upto 16 bytes long and which do not contain embedded spaces are stored directly in the .Ar ar_name field of the archive header. File names that are either longer than 16 bytes or which contain embedded spaces are stored immediately after the archive header and the .Ar ar_name field of the archive header is set to the string .Dq "#1/" followed by a decimal representation of the number of bytes needed for the file name. In addition, the .Ar ar_size field of the archive header is set to the decimal representation of the combined sizes of the archive member and the file name. The file contents of the member follows the file name without further padding. .Pp As an example, if the file name for a member was .Dq "A B" and its contents was the string .Dq "C D" , then the .Ar ar_name field of the header would contain .Dq Li "#1/3" , the .Ar ar_size field of the header would contain .Dq Li 6 , and the bytes immediately following the header would be 0x41, 0x20, 0x42, 0x43, 0x20 and 0x44 .Po ASCII .Dq "A BC D" .Pc . .It "SVR4/GNU" File names that are upto 15 characters long are stored directly in the .Ar ar_name field of the header, terminated by a .Dq Li / character. .Pp If the file name is larger than would fit in space for the .Ar ar_name field, then the actual file name is kept in the archive string table .Po see .Sx "Archive String Tables" below .Pc , and the decimal offset of the file name in the string table is stored in the .Ar ar_name field, prefixed by a .Dq Li / character. .Pp As an example, if the real file name has been stored at offset 768 in the archive string table, the .Ar ar_name field of the header will contain the string .Dq /768 . .El .Ss "Special Archive Members" The following archive members are special. .Bl -tag -width indent .It Dq Li / In the SVR4/GNU variant of the archive format, the archive member with name .Dq Li / denotes an archive symbol table. If present, this member will be the very first member in the archive. .It Dq Li // In the SVR4/GNU variant of the archive format, the archive member with name .Dq Li // denotes the archive string table. This special member is used to hold filenames that do not fit in the file name field of the header .Po see .Sx "Representing File Names" above .Pc . If present, this member immediately follows the archive symbol table if an archive symbol table is present, or is the first member otherwise. .It Dq Li "__.SYMDEF" This special member contains the archive symbol table in the BSD variant of the archive format. If present, this member will be the very first member in the archive. .El .Ss "Archive String Tables" An archive string table is used in the SVR4/GNU archive format to hold file names that are too large to fit into the constraints of the .Ar ar_name field of the archive header. An archive string table contains a sequence of file names. Each file name in the archive string table is terminated by the byte sequence 0x2F, 0x0A .Po the ASCII string .Dq "/\en" .Pc . No padding is used to separate adjacent file names. .Ss "Archive Symbol Tables" Archive symbol tables are used to speed up link editing by providing a -mapping between the program symbols defined in the archive +mapping between the program symbols defined in the archive and the corresponding archive members. Archive symbol tables are managed by the .Xr ranlib 1 utility. .Pp The format of archive symbol tables is as follows: .Bl -tag -width "SVR4/GNU" .It BSD In the BSD archive format, the archive symbol table comprises of two parts: a part containing an array of .Vt "struct ranlib" descriptors, followed by a part containing a symbol string table. The sizes and layout of the structures that make up a BSD format archive symbol table are machine dependent. .Pp The part containing .Vt "struct ranlib" descriptors begins with a field containing the size in bytes of the array of .Vt "struct ranlib" descriptors encoded as a C .Vt long value. .Pp The array of .Vt "struct ranlib" descriptors follows the size field. Each .Vt "struct ranlib" descriptor describes one symbol. .Pp A .Vt "struct ranlib" descriptor comprises two fields: .Bl -tag -width "Ar ran_strx" -compact .It Ar ran_strx .Pq C Vt long This field contains the zero-based offset of the symbol name in the symbol string table. .It Ar ran_off .Pq C Vt long This field is the file offset to the archive header for the archive member defining the symbol. .El .Pp The part containing the symbol string table begins with a field containing the size in bytes of the string table, encoded as a C .Vt long value. This string table follows the size field, and contains NUL-terminated strings for the symbols in the symbol table. .It SVR4/GNU In the SVR4/GNU archive format, the archive symbol table starts with a 4-byte binary value containing the number of entries contained in the archive symbol table. This count of entries is stored most significant byte first. .Pp Next, there are .Ar count 4-byte numbers, each stored most significant byte first. Each number is a binary offset to the archive header for the member in the archive file for the corresponding symbol table entry. .Pp After the binary offset values, there are .Ar count NUL-terminated strings in sequence, holding the symbol names for the corresponding symbol table entries. .El .Sh STANDARDS COMPLIANCE The .Xr ar 1 archive format is not currently specified by a standard. .Pp This manual page documents the .Xr ar 1 archive formats used by the .Bx 4.4 and .Ux SVR4 operating system releases. .Sh SEE ALSO .Xr ar 1 , .Xr ld 1 , .Xr ranlib 1 , .Xr elf 3 , .Xr elf_getarsym 3 , .Xr elf_rand 3 Index: stable/9/share/man/man5/fdescfs.5 =================================================================== --- stable/9/share/man/man5/fdescfs.5 (revision 237215) +++ stable/9/share/man/man5/fdescfs.5 (revision 237216) @@ -1,130 +1,130 @@ .\" Copyright (c) 1996 .\" Mike Pritchard . All rights reserved. .\" .\" Copyright (c) 1992, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" All rights reserved. .\" .\" This code is derived from software donated to Berkeley by .\" Jan-Simon Pendry. .\" .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd September 18, 2010 .Dt FDESCFS 5 .Os .Sh NAME .Nm fdescfs .Nd file-descriptor file system .Sh SYNOPSIS .Bd -literal fdescfs /dev/fd fdescfs rw 0 0 .Ed .Sh DESCRIPTION The file-descriptor file system, or .Nm , provides access to the per-process file descriptor namespace in the global file system namespace. The conventional mount point is .Pa /dev/fd . .Pp The file system's contents appear as a list of numbered files which correspond to the open files of the process reading the directory. The files .Pa /dev/fd/0 through .Pa /dev/fd/# refer to file descriptors which can be accessed through the file system. If the file descriptor is open and the mode the file is being opened with is a subset of the mode of the existing descriptor, the call: .Bd -literal -offset indent fd = open("/dev/fd/0", mode); .Ed .Pp and the call: .Bd -literal -offset indent fd = fcntl(0, F_DUPFD, 0); .Ed .Pp are equivalent. .Pp Flags to the .Xr open 2 call other than .Dv O_RDONLY , .Dv O_WRONLY and .Dv O_RDWR are ignored. .Pp .Em "Note:" .Pa /dev/fd/0 , .Pa /dev/fd/1 and .Pa /dev/fd/2 files are created by default when devfs alone is mounted. .Nm creates entries for all file descriptors opened by the process. .Sh FILES .Bl -tag -width /dev/stderr -compact .It Pa /dev/fd/# .El .Sh EXAMPLES -To mount a +To mount a .Nm volume located on .Pa /dev/fd : .Pp .Dl "mount -t fdescfs null /dev/fd" .Sh SEE ALSO .Xr devfs 5 , .Xr mount 8 .Sh HISTORY The .Nm file system first appeared in .Bx 4.4 . The .Nm manual page first appeared in .Fx 2.2 . .Sh AUTHORS .An -nosplit The .Nm manual page was written by .An Mike Pritchard Aq mpp@FreeBSD.org , and was based on the manual page written by .An Jan-Simon Pendry . Index: stable/9/share/man/man5/fs.5 =================================================================== --- stable/9/share/man/man5/fs.5 (revision 237215) +++ stable/9/share/man/man5/fs.5 (revision 237216) @@ -1,450 +1,450 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" @(#)fs.5 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd October 31, 2006 .Dt FS 5 .Os .Sh NAME .Nm fs , .Nm inode .Nd format of file system volume .Sh SYNOPSIS .In sys/param.h .In ufs/ffs/fs.h .Pp .In sys/types.h .In sys/lock.h .In sys/extattr.h .In sys/acl.h .In ufs/ufs/quota.h .In ufs/ufs/dinode.h .In ufs/ufs/extattr.h .Sh DESCRIPTION The files .In fs.h and .In inode.h declare several structures, defined variables and macros which are used to create and manage the underlying format of file system objects on random access devices (disks). .Pp The block size and number of blocks which comprise a file system are parameters of the file system. Sectors beginning at .Dv BBLOCK and continuing for .Dv BBSIZE are used for a disklabel and for some hardware primary and secondary bootstrapping programs. .Pp The actual file system begins at sector .Dv SBLOCK with the .Em super-block that is of size .Dv SBLOCKSIZE . The following structure describes the super-block and is from the file .In ufs/ffs/fs.h : .Bd -literal /* * Super block for an FFS filesystem. */ struct fs { int32_t fs_firstfield; /* historic filesystem linked list, */ int32_t fs_unused_1; /* used for incore super blocks */ int32_t fs_sblkno; /* offset of super-block in filesys */ int32_t fs_cblkno; /* offset of cyl-block in filesys */ int32_t fs_iblkno; /* offset of inode-blocks in filesys */ int32_t fs_dblkno; /* offset of first data after cg */ int32_t fs_old_cgoffset; /* cylinder group offset in cylinder */ int32_t fs_old_cgmask; /* used to calc mod fs_ntrak */ int32_t fs_old_time; /* last time written */ int32_t fs_old_size; /* number of blocks in fs */ int32_t fs_old_dsize; /* number of data blocks in fs */ int32_t fs_ncg; /* number of cylinder groups */ int32_t fs_bsize; /* size of basic blocks in fs */ int32_t fs_fsize; /* size of frag blocks in fs */ int32_t fs_frag; /* number of frags in a block in fs */ /* these are configuration parameters */ int32_t fs_minfree; /* minimum percentage of free blocks */ int32_t fs_old_rotdelay; /* num of ms for optimal next block */ int32_t fs_old_rps; /* disk revolutions per second */ /* these fields can be computed from the others */ int32_t fs_bmask; /* ``blkoff'' calc of blk offsets */ int32_t fs_fmask; /* ``fragoff'' calc of frag offsets */ int32_t fs_bshift; /* ``lblkno'' calc of logical blkno */ int32_t fs_fshift; /* ``numfrags'' calc number of frags */ /* these are configuration parameters */ int32_t fs_maxcontig; /* max number of contiguous blks */ int32_t fs_maxbpg; /* max number of blks per cyl group */ /* these fields can be computed from the others */ int32_t fs_fragshift; /* block to frag shift */ int32_t fs_fsbtodb; /* fsbtodb and dbtofsb shift constant */ int32_t fs_sbsize; /* actual size of super block */ int32_t fs_spare1[2]; /* old fs_csmask */ /* old fs_csshift */ int32_t fs_nindir; /* value of NINDIR */ int32_t fs_inopb; /* value of INOPB */ int32_t fs_old_nspf; /* value of NSPF */ /* yet another configuration parameter */ int32_t fs_optim; /* optimization preference, see below */ int32_t fs_old_npsect; /* # sectors/track including spares */ int32_t fs_old_interleave; /* hardware sector interleave */ int32_t fs_old_trackskew; /* sector 0 skew, per track */ int32_t fs_id[2]; /* unique filesystem id */ /* sizes determined by number of cylinder groups and their sizes */ int32_t fs_old_csaddr; /* blk addr of cyl grp summary area */ int32_t fs_cssize; /* size of cyl grp summary area */ int32_t fs_cgsize; /* cylinder group size */ int32_t fs_spare2; /* old fs_ntrak */ int32_t fs_old_nsect; /* sectors per track */ int32_t fs_old_spc; /* sectors per cylinder */ int32_t fs_old_ncyl; /* cylinders in filesystem */ int32_t fs_old_cpg; /* cylinders per group */ int32_t fs_ipg; /* inodes per group */ int32_t fs_fpg; /* blocks per group * fs_frag */ /* this data must be re-computed after crashes */ struct csum fs_old_cstotal; /* cylinder summary information */ /* these fields are cleared at mount time */ int8_t fs_fmod; /* super block modified flag */ int8_t fs_clean; /* filesystem is clean flag */ int8_t fs_ronly; /* mounted read-only flag */ int8_t fs_old_flags; /* old FS_ flags */ u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ u_char fs_volname[MAXVOLLEN]; /* volume name */ u_int64_t fs_swuid; /* system-wide uid */ int32_t fs_pad; /* due to alignment of fs_swuid */ /* these fields retain the current block allocation info */ int32_t fs_cgrotor; /* last cg searched */ void *fs_ocsp[NOCSPTRS]; /* padding; was list of fs_cs buffers */ u_int8_t *fs_contigdirs; /* # of contiguously allocated dirs */ struct csum *fs_csp; /* cg summary info buffer for fs_cs */ int32_t *fs_maxcluster; /* max cluster in each cyl group */ u_int *fs_active; /* used by snapshots to track fs */ int32_t fs_old_cpc; /* cyl per cycle in postbl */ int32_t fs_maxbsize; /* maximum blocking factor permitted */ int64_t fs_unrefs; /* number of unreferenced inodes */ int64_t fs_sparecon64[16]; /* old rotation block list head */ int64_t fs_sblockloc; /* byte offset of standard superblock */ struct csum_total fs_cstotal; /* cylinder summary information */ ufs_time_t fs_time; /* last time written */ int64_t fs_size; /* number of blocks in fs */ int64_t fs_dsize; /* number of data blocks in fs */ ufs2_daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ int64_t fs_pendingblocks; /* blocks in process of being freed */ int32_t fs_pendinginodes; /* inodes in process of being freed */ int32_t fs_snapinum[FSMAXSNAP]; /* list of snapshot inode numbers */ int32_t fs_avgfilesize; /* expected average file size */ int32_t fs_avgfpdir; /* expected # of files per directory */ int32_t fs_save_cgsize; /* save real cg size to use fs_bsize */ int32_t fs_sparecon32[26]; /* reserved for future constants */ int32_t fs_flags; /* see FS_ flags below */ int32_t fs_contigsumsize; /* size of cluster summary array */ int32_t fs_maxsymlinklen; /* max length of an internal symlink */ int32_t fs_old_inodefmt; /* format of on-disk inodes */ u_int64_t fs_maxfilesize; /* maximum representable file size */ int64_t fs_qbmask; /* ~fs_bmask for use with 64-bit size */ int64_t fs_qfmask; /* ~fs_fmask for use with 64-bit size */ int32_t fs_state; /* validate fs_clean field */ int32_t fs_old_postblformat; /* format of positional layout tables */ int32_t fs_old_nrpos; /* number of rotational positions */ int32_t fs_spare5[2]; /* old fs_postbloff */ /* old fs_rotbloff */ int32_t fs_magic; /* magic number */ }; /* * Filesystem identification */ #define FS_UFS1_MAGIC 0x011954 /* UFS1 fast filesystem magic number */ #define FS_UFS2_MAGIC 0x19540119 /* UFS2 fast filesystem magic number */ #define FS_OKAY 0x7c269d38 /* superblock checksum */ #define FS_42INODEFMT -1 /* 4.2BSD inode format */ #define FS_44INODEFMT 2 /* 4.4BSD inode format */ /* * Preference for optimization. */ #define FS_OPTTIME 0 /* minimize allocation time */ #define FS_OPTSPACE 1 /* minimize disk fragmentation */ .Ed .Pp Each disk drive contains some number of file systems. A file system consists of a number of cylinder groups. Each cylinder group has inodes and data. .Pp A file system is described by its super-block, which in turn describes the cylinder groups. The super-block is critical data and is replicated in each cylinder group to protect against catastrophic loss. This is done at file system creation time and the critical super-block data does not change, so the copies need not be referenced further unless disaster strikes. .Pp Addresses stored in inodes are capable of addressing fragments of `blocks'. File system blocks of at most size .Dv MAXBSIZE can be optionally broken into 2, 4, or 8 pieces, each of which is addressable; these pieces may be .Dv DEV_BSIZE , or some multiple of a .Dv DEV_BSIZE unit. .Pp Large files consist of exclusively large data blocks. To avoid undue wasted disk space, the last data block of a small file is allocated as only as many fragments of a large block as are necessary. The file system format retains only a single pointer to such a fragment, which is a piece of a single large block that has been divided. The size of such a fragment is determinable from information in the inode, using the .Fn blksize fs ip lbn macro. .Pp The file system records space availability at the fragment level; to determine block availability, aligned fragments are examined. .Pp The root inode is the root of the file system. Inode 0 cannot be used for normal purposes and historically bad blocks were linked to inode 1, thus the root inode is 2 (inode 1 is no longer used for this purpose, however numerous dump tapes make this assumption, so we are stuck with it). .Pp The .Fa fs_minfree element gives the minimum acceptable percentage of file system blocks that may be free. If the freelist drops below this level only the super-user may continue to allocate blocks. The .Fa fs_minfree element may be set to 0 if no reserve of free blocks is deemed necessary, however severe performance degradations will be observed if the file system is run at greater than 90% full; thus the default value of .Fa fs_minfree is 10%. .Pp Empirically the best trade-off between block fragmentation and overall disk utilization at a loading of 90% comes with a fragmentation of 8, thus the default fragment size is an eighth of the block size. .Pp The element .Fa fs_optim specifies whether the file system should try to minimize the time spent allocating blocks, or if it should attempt to minimize the space fragmentation on the disk. If the value of fs_minfree (see above) is less than 10%, then the file system defaults to optimizing for space to avoid running out of full sized blocks. If the value of minfree is greater than or equal to 10%, fragmentation is unlikely to be problematical, and the file system defaults to optimizing for time. .Pp .Em Cylinder group related limits : Each cylinder keeps track of the availability of blocks at different rotational positions, so that sequential blocks can be laid out with minimum rotational latency. With the default of 8 distinguished rotational positions, the resolution of the summary information is 2ms for a typical 3600 rpm drive. .Pp The element .Fa fs_old_rotdelay gives the minimum number of milliseconds to initiate another disk transfer on the same cylinder. It is used in determining the rotationally optimal layout for disk blocks within a file; the default value for .Fa fs_old_rotdelay is 2ms. .Pp Each file system has a statically allocated number of inodes. An inode is allocated for each .Dv NBPI bytes of disk space. The inode allocation strategy is extremely conservative. .Pp .Dv MINBSIZE is the smallest allowable block size. With a .Dv MINBSIZE of 4096 it is possible to create files of size 2^32 with only two levels of indirection. .Dv MINBSIZE must be big enough to hold a cylinder group block, thus changes to .Pq Fa struct cg must keep its size within .Dv MINBSIZE . Note that super-blocks are never more than size .Dv SBLOCKSIZE . .Pp The path name on which the file system is mounted is maintained in .Fa fs_fsmnt . .Dv MAXMNTLEN defines the amount of space allocated in the super-block for this name. The limit on the amount of summary information per file system is defined by .Dv MAXCSBUFS . For a 4096 byte block size, it is currently parameterized for a maximum of two million cylinders. .Pp Per cylinder group information is summarized in blocks allocated from the first cylinder group's data blocks. These blocks are read in from .Fa fs_csaddr (size .Fa fs_cssize ) in addition to the super-block. .Pp .Sy N.B. : .Fn sizeof "struct csum" must be a power of two in order for the .Fn fs_cs macro to work. .Pp The .Em "Super-block for a file system" : The size of the rotational layout tables is limited by the fact that the super-block is of size .Dv SBLOCKSIZE . The size of these tables is .Em inversely proportional to the block size of the file system. The size of the tables is increased when sector sizes are not powers of two, as this increases the number of cylinders included before the rotational pattern repeats .Pq Fa fs_cpc . The size of the rotational layout tables is derived from the number of bytes remaining in .Pq Fa struct fs . .Pp The number of blocks of data per cylinder group is limited because cylinder groups are at most one block. The inode and free block tables must fit into a single block after deducting space for the cylinder group structure .Pq Fa struct cg . .Pp The .Em Inode : The inode is the focus of all file activity in the .Ux file system. There is a unique inode allocated for each active file, each current directory, each mounted-on file, text file, and the root. An inode is `named' by its device/i-number pair. For further information, see the include file .In ufs/ufs/inode.h . .Pp The format of an external attribute is defined by the extattr structure: .Bd -literal struct extattr { int32_t ea_length; /* length of this attribute */ int8_t ea_namespace; /* name space of this attribute */ int8_t ea_contentpadlen; /* padding at end of attribute */ int8_t ea_namelength; /* length of attribute name */ char ea_name[1]; /* null-terminated attribute name */ /* extended attribute content follows */ }; .Ed .Pp Several macros are defined to manipulate these structures. Each macro takes a pointer to an extattr structure. .Bl -tag -width ".Dv EXTATTR_SET_LENGTHS(eap, size)" .It Dv EXTATTR_NEXT(eap) Returns a pointer to the next extended attribute following .Fa eap . .It Dv EXTATTR_CONTENT(eap) -Returns a pointer to the extended attribute content referenced by +Returns a pointer to the extended attribute content referenced by .Fa eap . .It Dv EXTATTR_CONTENT_SIZE(eap) -Returns the size of the extended attribute content referenced by +Returns the size of the extended attribute content referenced by .Fa eap . .It Dv EXTATTR_SET_LENGTHS(eap, size) Called with the size of the attribute content after initializing the attribute name to calculate and set the .Fa ea_length , .Fa ea_namelength , and .Fa ea_contentpadlen fields of the extended attribute structure. .El .Pp The following code identifies an ACL: .Bd -literal if (eap->ea_namespace == EXTATTR_NAMESPACE_SYSTEM && !strcmp(eap->ea_name, POSIX1E_ACL_ACCESS_EXTATTR_NAME) { aclp = EXTATTR_CONTENT(eap); acllen = EXTATTR_CONTENT_SIZE(eap); ... } .Ed .Pp The following code creates an extended attribute containing a copy of a structure .Fa mygif : .Bd -literal eap->ea_namespace = EXTATTR_NAMESPACE_USER; strcpy(eap->ea_name, "filepic.gif"); EXTATTR_SET_LENGTHS(eap, sizeof(struct mygif)); memcpy(EXTATTR_CONTENT(eap), &mygif, sizeof(struct mygif)); .Ed .Sh HISTORY A super-block structure named filsys appeared in .At v6 . The file system described in this manual appeared in .Bx 4.2 . Index: stable/9/share/man/man5/fstab.5 =================================================================== --- stable/9/share/man/man5/fstab.5 (revision 237215) +++ stable/9/share/man/man5/fstab.5 (revision 237216) @@ -1,347 +1,347 @@ .\" Copyright (c) 1980, 1989, 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" @(#)fstab.5 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd June 7, 2011 .Dt FSTAB 5 .Os .Sh NAME .Nm fstab .Nd static information about the file systems .Sh SYNOPSIS .In fstab.h .Sh DESCRIPTION The file .Nm contains descriptive information about the various file systems. .Nm is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. Each file system is described on a separate line; fields on each line are separated by tabs or spaces. The order of records in .Nm is important because .Xr fsck 8 , .Xr mount 8 , and .Xr umount 8 sequentially iterate through .Nm doing their thing. .Pp The first field, .Pq Fa fs_spec , describes the special device or remote file system to be mounted. .Pp The second field, .Pq Fa fs_file , describes the mount point for the file system. For swap partitions, this field should be specified as .Dq none . .Pp The third field, .Pq Fa fs_vfstype , describes the type of the file system. The system can support various file system types. Only the root, /usr, and /tmp file systems need be statically compiled into the kernel; everything else will be automatically loaded at mount time. (Exception: the FFS cannot currently be demand-loaded.) Some people still prefer to statically compile other file systems as well. .Pp The fourth field, .Pq Fa fs_mntops , describes the mount options associated with the file system. It is formatted as a comma separated list of options. It contains at least the type of mount (see .Fa fs_type below) plus any additional options appropriate to the file system type. See the options flag .Pq Fl o in the .Xr mount 8 page and the file system specific page, such as .Xr mount_nfs 8 , for additional options that may be specified. All options that can be given to the file system specific mount commands can be used in .Nm as well. They just need to be formatted a bit differently. The arguments of the .Fl o option can be used without the preceding .Fl o flag. Other options need both the file system specific flag and its argument, separated by an equal sign. For example, mounting an .Xr msdosfs 5 filesystem, the options .Bd -literal -offset indent -o sync -o noatime -m 644 -M 755 -u foo -g bar .Ed .Pp should be written as .Bd -literal -offset indent sync,noatime,-m=644,-M=755,-u=foo,-g=bar .Ed .Pp in the option field of .Nm . .Pp If the options .Dq userquota and/or .Dq groupquota are specified, the file system is automatically processed by the .Xr quotacheck 8 command, and user and/or group disk quotas are enabled with .Xr quotaon 8 . By default, file system quotas are maintained in files named .Pa quota.user and .Pa quota.group which are located at the root of the associated file system. These defaults may be overridden by putting an equal sign and an alternative absolute pathname following the quota option. Thus, if the user quota file for .Pa /tmp is stored in .Pa /var/quotas/tmp.user , this location can be specified as: .Bd -literal -offset indent userquota=/var/quotas/tmp.user .Ed .Pp If the option .Dq failok is specified, the system will ignore any error which happens during the mount of that filesystem, which would otherwise cause the system to drop into single user mode. This option is implemented by the .Xr mount 8 command and will not be passed to the kernel. .Pp If the option .Dq noauto is specified, the file system will not be automatically mounted at system startup. Note that, for network file systems of third party types (i.e., types supported by additional software not included in the base system) to be automatically mounted at system startup, the .Va extra_netfs_types .Xr rc.conf 5 variable must be used to extend the .Xr rc 8 startup script's list of network file system types. .Pp The type of the mount is extracted from the .Fa fs_mntops field and stored separately in the .Fa fs_type field (it is not deleted from the .Fa fs_mntops field). If .Fa fs_type is .Dq rw or .Dq ro then the file system whose name is given in the .Fa fs_file field is normally mounted read-write or read-only on the specified special file. If .Fa fs_type is .Dq sw then the special file is made available as a piece of swap space by the .Xr swapon 8 command at the end of the system reboot procedure. The fields other than .Fa fs_spec and .Fa fs_type are unused. If .Fa fs_type is specified as .Dq xx the entry is ignored. This is useful to show disk partitions which are currently unused. .Pp The fifth field, .Pq Fa fs_freq , is used for these file systems by the .Xr dump 8 command to determine which file systems need to be dumped. If the fifth field is not present, a value of zero is returned and .Nm dump will assume that the file system does not need to be dumped. If the fifth field is greater than 0, then it specifies the number of days between dumps for this file system. .Pp The sixth field, .Pq Fa fs_passno , is used by the .Xr fsck 8 and .Xr quotacheck 8 programs to determine the order in which file system and quota checks are done at reboot time. The .Fa fs_passno -field can be any value between 0 and +field can be any value between 0 and .Ql INT_MAX Ns -1 . .Pp The root file system should be specified with a .Fa fs_passno of 1, and other file systems should have a .Fa fs_passno of 2 or greater. A file system with a .Fa fs_passno -value of 1 is always checked sequentially and be completed before +value of 1 is always checked sequentially and be completed before another file system is processed, and it will be processed before all file systems with a larger .Fa fs_passno . .Pp For any given value of .Fa fs_passno , file systems within a drive will be checked sequentially, but file systems on different drives will be checked at the same time to utilize parallelism available in the hardware. Once all file system checks are complete for the current .Fa fs_passno , the same process will start over for the next .Fa fs_passno . .Pp If the sixth field is not present or is zero, a value of zero is returned and .Xr fsck 8 and .Xr quotacheck 8 will assume that the file system does not need to be checked. .Pp The .Fa fs_passno -field can be used to implement finer control when +field can be used to implement finer control when the system utilities may determine that the file system resides on a different physical device, when it actually does not, as with a .Xr ccd 4 device. All file systems with a lower .Fa fs_passno value will be completed before starting on file systems with a higher .Fa fs_passno value. E.g. all file systems with a .Fa fs_passno of 2 will be completed before any file systems with a .Fa fs_passno of 3 or greater are started. Gaps are allowed between the different .Fa fs_passno values. E.g. file systems listed in .Pa /etc/fstab may have .Fa fs_passno values such as 0, 1, 2, 15, 100, 200, 300, and may appear in any order within .Pa /etc/fstab . .Bd -literal #define FSTAB_RW "rw" /* read/write device */ #define FSTAB_RQ "rq" /* read/write with quotas */ #define FSTAB_RO "ro" /* read-only device */ #define FSTAB_SW "sw" /* swap device */ #define FSTAB_XX "xx" /* ignore totally */ struct fstab { char *fs_spec; /* block special device name */ char *fs_file; /* file system path prefix */ char *fs_vfstype; /* File system type, ufs, nfs */ char *fs_mntops; /* Mount options ala -o */ char *fs_type; /* FSTAB_* from fs_mntops */ int fs_freq; /* dump frequency, in days */ int fs_passno; /* pass number on parallel fsck */ }; .Ed .Pp The proper way to read records from .Pa fstab is to use the routines .Xr getfsent 3 , .Xr getfsspec 3 , .Xr getfstype 3 , and .Xr getfsfile 3 . .Sh FILES .Bl -tag -width /etc/fstab -compact .It Pa /etc/fstab The file .Nm resides in .Pa /etc . .El .Sh SEE ALSO .Xr getfsent 3 , .Xr getvfsbyname 3 , .Xr ccd 4 , .Xr dump 8 , .Xr fsck 8 , .Xr mount 8 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr swapon 8 , .Xr umount 8 .Sh HISTORY The .Nm file format appeared in .Bx 4.0 . Index: stable/9/share/man/man5/nsmb.conf.5 =================================================================== --- stable/9/share/man/man5/nsmb.conf.5 (revision 237215) +++ stable/9/share/man/man5/nsmb.conf.5 (revision 237216) @@ -1,159 +1,159 @@ .\" Copyright (c) 2003 .\" Originally written by Sergey A. Osokin .\" Rewritten by Tom Rhodes .\" .\" 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 ``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 October 19, 2010 .Dt NSMB.CONF 5 .Os .Sh NAME .Nm nsmb.conf .Nd configuration file for .Tn SMB requests .Sh DESCRIPTION The .Nm file contains information about the computers, users, and shares or mount points for the .Tn SMB network protocol. .Pp The configuration hierarchy is made up of several sections, each section containing a few or several lines of parameters and their assigned values. Each of these sections must begin with a section name enclosed within square brackets, similar to: .Pp .D1 Bq Ar section_name .Pp The end of each section is marked by either the start of a new section, or by the abrupt ending of the file, commonly referred to as the .Tn EOF . Each section may contain zero or more parameters such as: .Pp .D1 Bq Ar section_name .D1 Ar key Ns = Ns Ar value .Pp where .Ar key represents a parameter name, and .Ar value would be the parameter's assigned value. .Pp The .Tn SMB library uses the following information for section names: .Pp .Bl -tag -width indent -compact .It Ic A) .Bq Li default .It Ic B) .Bq Ar SERVER .It Ic C) .Bq Ar SERVER : Ns Ar USER .It Ic D) .Op Ar SERVER : Ns Ar USER : Ns Ar SHARE .El .Pp Possible keywords may include: .Bl -column ".Va retry_count" ".Sy Section" .It Sy "Keyword Section Comment" .It Sy " A B C D" .It Va addr Ta "- + - -" Ta "IP or IPX address of SMB server" .It Va charsets Ta "- + + +" Ta "local:remote charset pair" .It Va nbns Ta "+ + - -" Ta "address of NetBIOS name server (WINS)" .It Va nbscope Ta "+ + - -" Ta "NetBIOS scope" .It Va nbtimeout Ta "+ + - -" Ta "timeout for NetBIOS name servers" .It Va password Ta "- - + +" Ta "plain text or simple encrypted password used to access the given share" .It Va retry_count Ta "+ + - -" Ta "number of retries before connection is marked as broken" .It Va timeout Ta "+ + - -" Ta "SMB request timeout" .It Va workgroup Ta "+ + + +" Ta "workgroup name" .El .Sh FILES .Bl -tag -width ".Pa /etc/nsmb.conf" .It Pa /etc/nsmb.conf The default remote mount-point configuration file. .It Pa ~/nsmb.conf The user specific remote mount-point configuration file. .El .Sh EXAMPLES What follows is a sample configuration file which may, or may not match your environment: .Bd -literal -offset indent # Configuration file for example.com [default] workgroup=SALES # The 'FSERVER' is an NT server. [FSERVER] charsets=koi8-r:cp866 addr=fserv.example.com # User specific data for FSERVER [FSERVER:MYUSER] password=$$16144562c293a0314e6e1 .Ed .Pp All lines which begin with the .Ql # character are comments and will not be parsed. The .Dq Li default section describes the default workgroup or domain, in this case .Dq Li SALES . The next section depicted here as .Dq Li FSERVER , defines a server section and then assigns it a charset which is only required when Cyrillic characters are not used. The hostname value, .Dq Li fserv.example.com , is also assigned in this section. .Dq Li FSERVER:USER , defines the user settings and is useful for saving the password used during a specific connection. -The password may be plaintext or obfuscated using simple encryption. +The password may be plaintext or obfuscated using simple encryption. The simple encrypted password starts with the `$$1' symbols. Warning: the encryption function is very weak and intended only to hide clear text passwords. If the use of simple encryption is desired, the following command may be used on a password: .Bd -literal -offset indent smbutil crypt -.Ed +.Ed .Sh COMPATIBILITY At the time of this writing, the .Tn IPX protocol remains unsupported. Future .Fx releases are expected to support this. .Sh SEE ALSO .Xr smbutil 1 , .Xr mount_smbfs 8 .Sh AUTHORS This manual page was written by .An -nosplit .An Sergey Osokin Aq osa@FreeBSD.org and .An Tom Rhodes Aq trhodes@FreeBSD.org . Index: stable/9/share/man/man5/quota.user.5 =================================================================== --- stable/9/share/man/man5/quota.user.5 (revision 237215) +++ stable/9/share/man/man5/quota.user.5 (revision 237216) @@ -1,129 +1,129 @@ .\" Copyright (c) 2001 Nik Clayton .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd October 30, 2007 .Dt QUOTA.USER 5 .Os .Sh NAME .Nm quota.user , quota.group .Nd per file system quota database .Sh DESCRIPTION Each file system with active quotas should contain a .Pa quota.user and .Pa quota.group file in the file system root. These files are created by .Xr quotacheck 8 , and should be edited with .Xr edquota 8 . It is possible to specify a different location and file name with the .Dq Li userquota and .Dq Li groupquota options in the -.Xr fstab 5 +.Xr fstab 5 file. .Pp The data files contain the following information: .Pp .Bl -bullet -offset indent -compact .It Current block usage .It Current number of files .It Soft block limit .It Soft file limit .It Hard block limit .It Hard file limit .It Block grace time remaining if over the soft limit .It File grace time remaining if over the soft limit .El .Pp See .Xr edquota 8 for an explanation on the various limits and grace periods. .Pp -During normal quota operations the +During normal quota operations the .Xr quotactl 2 -interface is used to query or set quota information and the kernel +interface is used to query or set quota information and the kernel will maintain the data files as needed. If quotas are disabled on a file system, but marked as having quotas enabled in .Xr fstab 5 , then the quota data files will be used directly. .Pp The data files are stored as an array of .Dq Li struct dqblk structures, as defined in .In ufs/ufs/quota.h , and indexed by UID or GID. The data files will be written as a sparse file if possible. Data is only maintained for ids that have either non-zero usage or non-zero quota limits. If an attempt is made to access data for an id that would exist past the end of the current data file, a quota structure with all values set to zero will be created, and the data file extended as needed. The .Xr quotacheck 8 utility will truncate the data files to the minimum size needed to store the highest id with either non-zero file usage or non-zero quota limits. .Pp The data record for id 0 has special meaning. If the .Dq Dv dqb_btime or .Dq Dv dbq_itime fields are non-zero, they are used to indicate the grace period on that file system for users who have exceeded their soft limit. -These times can be set by -.Xr edquota 8 +These times can be set by +.Xr edquota 8 with the .Fl t flag. If no explicit grace period has been set with .Xr edquota 8 , then the default value of 7 days will be used. The default values are defined by .Dv MAX_DQ_TIME and .Dv MAX_IQ_TIME in .In ufs/ufs/quota.h . .Sh SEE ALSO .Xr quota 1 , .Xr quotactl 2 , .Xr fstab 5 , .Xr edquota 8 , .Xr quotacheck 8 , .Xr quotaoff 8 , .Xr quotaon 8 , .Xr repquota 8 Index: stable/9/share/man/man5/services.5 =================================================================== --- stable/9/share/man/man5/services.5 (revision 237215) +++ stable/9/share/man/man5/services.5 (revision 237216) @@ -1,107 +1,107 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. 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. .\" .\" @(#)services.5 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd April 4, 2010 .Dt SERVICES 5 .Os .Sh NAME .Nm services .Nd service name data base .Sh DESCRIPTION The .Nm file contains information regarding the known services available in the Internet. For each service a single line should be present with the following information: .Bd -unfilled -offset indent official service name port number protocol name aliases .Ed .Pp Items are separated by any number of blanks and/or tab characters. The port number and protocol name are considered a single .Em item ; a ``/'' is used to separate the port and protocol (e.g.\& ``512/tcp''). A ``#'' indicates the beginning of a comment; subsequent characters up to the end of the line are not interpreted by the routines which search the file. .Pp Service names may contain any printable character other than a field delimiter, newline, or comment character. .Pp -If +If .Dq db is specified as source in the .Xr nsswitch.conf 5 , .Pa /var/db/services.db is searched. The database in .Pa /var/db/services.db needs to be updated with .Xr services_mkdb 8 after changes to the services file have been applied. .Sh NIS INTERACTION Access to the NIS .Pa services.byname map can be enabled by adding a single ``+'' on a line by itself in the .Pa /etc/services file. This causes the contents of the NIS services map to be inserted at the location where the ``+'' appears. .Sh FILES .Bl -tag -width /etc/services -compact .It Pa /etc/services The .Nm file resides in .Pa /etc . .El .Sh SEE ALSO .Xr getservent 3 .Xr nsswitch.conf 5 .Xr services_mkdb 8 .Sh HISTORY The .Nm file format appeared in .Bx 4.2 . .Sh BUGS A name server should be used instead of a static file. Index: stable/9/share/man/man5 =================================================================== --- stable/9/share/man/man5 (revision 237215) +++ stable/9/share/man/man5 (revision 237216) Property changes on: stable/9/share/man/man5 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man5:r233648 Index: stable/9/share/man/man7/release.7 =================================================================== --- stable/9/share/man/man7/release.7 (revision 237215) +++ stable/9/share/man/man7/release.7 (revision 237216) @@ -1,390 +1,393 @@ .\" Copyright (c) 2002 Murray Stokely .\" 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 ``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 March 18, 2011 +.Dd January 14, 2012 .Dt RELEASE 7 .Os .Sh NAME .Nm release .Nd "release building infrastructure" .Sh DESCRIPTION .Fx provides a complete build environment suitable for users to make full releases of the .Fx operating system. All of the tools necessary to build a release are available from the .Fx source code repository in .Pa src/release . A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to CD-ROM, memory stick images, and an FTP install directory. This command is aptly named .Dq Li "make release" . .Pp For some users, it may be desirable to provide an absolutely clean build environment, with no local modifications to the source tree or to .Xr make.conf 5 , and with clean checkouts of specific versions of the doc, src, and ports trees. For this purpose, a script .Pq Pa src/release/generate-release.sh is provided to automate these checkouts and then execute -.Dq Li "make release" +.Dq Li "make release" in a clean .Xr chroot 8 . .Pp Before attempting to build a release, the user is expected to be familiar with the contents of .Xr build 7 , and should have experience upgrading systems from source. .Pp The release build process requires that .Pa /usr/obj be populated with the output of -.Dq Li "make buildworld" +.Dq Li "make buildworld" and .Dq Li "make buildkernel" . This is necessary to provide the object files for the release or, when using .Pa generate-release.sh , so that the object files for a complete system can be installed into a clean .Xr chroot 8 environment. In this second case, the built world must be capable of running on the build system (i.e. it must be for the same architecture and be compatible with the installed kernel). The release procedure on some architectures may also require that the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). .Pp This document does not cover source code management, quality assurance, or other aspects of the release engineering process. .Sh CLEAN RELEASE GENERATION Official releases of FreeBSD are produced in a totally clean environment to ensure consistency between the versions of the src, ports, and doc trees and to avoid contamination from the host system (e.g. local patches, changes to .Xr make.conf 5 , etc.). This is accomplished using the wrapper script .Pa src/release/generate-release.sh . .Pp .Ic generate-release.sh svn-branch scratch-dir .Pp .Ic generate-release.sh calls .Dq Li "make installworld" to generate a .Xr chroot 8 environment in .Ar scratch-dir . It then checks out the src tree specified by .Ar svn-branch using .Xr svn 1 and (optionally) the ports and documentation trees using .Xr csup 1 or .Xr cvs 1 . Once the various source trees have been obtained, it executes .Dq Li "make release" within the .Xr chroot 8 environment and places the result in .Pa $scratch-dir/R . Note that because this uses a chroot, it cannot be used to cross-build .Fx release media. .Pp Environment variables: .Bl -tag -width ".Cm MAKE_FLAGS" .It Ev CVSUP_HOST The CVSUP server to use for the doc and ports trees. One of .Ev CVSUP_HOST or .Ev CVSROOT must be specified for ports and documentation to be included in the release. .It Ev CVSROOT The location of the .Fx CVS repository to use for the doc and ports trees. One of .Ev CVSUP_HOST or .Ev CVSROOT must be specified for ports and documentation to be included in the release. .It Ev CVS_TAG If the variable .Ev CVS_TAG -is set, that tag will be used for CVS checkouts (doc and ports), otherwise +is set, that tag will be used for CVS checkouts (doc and ports), otherwise .Ic generate-release.sh will use HEAD. .It Ev MAKE_FLAGS This environment variable can be set to pass flags (e.g. -j) to .Xr make 1 when invoked by the script. .It Ev SVNROOT The location of the FreeBSD SVN source repository. Defaults to .Pa svn://svn.freebsd.org/base . +.It Ev RELSTRING +Optional base name for generated media images (e.g. FreeBSD-9.0-RC2-amd64). +Defaults to the output of +.Ic `uname -s`-`uname -r`-`uname -p` +within the chroot. .El .Sh MAKEFILE TARGETS The release makefile .Pq Pa src/release/Makefile is fairly abstruse. Most developers will only be concerned with the .Cm release and .Cm install targets. .\" XXX: Some sort of introduction to this list? All the others have one. .Bl -tag -width ".Cm packagesystem" .It Cm release Meta-target to build all release media and distributions applicable to this platform. .It Cm install -Copy all produced release media to +Copy all produced release media to .Pa ${DESTDIR} . .It Cm cdrom Builds installation CD-ROM images. On some systems, this may require that .Xr mkisofs 8 -be installed +be installed .Pq Pa sysutils/cdrtools and possibly that the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). This target produces files called .Pa release.iso and .Pa bootonly.iso as its output. .It Cm memstick Builds an installation memory stick image named .Pa memstick . Not applicable on all platforms. Requires that the .Xr md 4 (memory disk) device driver be present in the kernel (either by being compiled in or available as a module). .It Cm ftp Creates a directory named .Pa ftp containing the distribution files used in network installations and suitable for upload to an FTP mirror. .El .Pp Major subtargets called by targets above: .Bl -tag -width ".Cm packagesystem" .It Cm packagesystem Generates all the distribution archives (e.g. base, kernel, ports, doc) applicable on this platform. .It Cm system Builds a bootable installation system containing all the distribution files packaged by the .Cm packagesystem target, and suitable for imaging by the .Cm cdrom and .Cm memstick targets. .It Cm reldoc Builds the release documentation. This includes the release notes, hardware guide, and installation instructions. Other documentation (e.g. the Handbook) is built during the .Cm base.txz target invoked by -.Cm packagesystem . +.Cm packagesystem. .El .Sh ENVIRONMENT Optional variables: .Bl -tag -width ".Va TARGET_ARCH" .It Va WORLDDIR Location of a directory containing the src tree. By default, the directory above the one containing the makefile .Pq Pa src . .It Va PORTSDIR Location of a directory containing the ports tree. By default, .Pa /usr/ports . If it is unset or cannot be found, ports will not be included in the release. .It Va DOCDIR Location of a directory containing the doc tree. By default, .Pa /usr/doc . If it is unset or cannot be found, most documentation will not be included in the release; see -.Ev NODOC +.Ev NODOC below. .It Va NOPORTS If defined, the Ports Collection will be omitted from the release. .It Va NOSRC If set, do not include system source code in the release. .It Va NODOC If defined, the SGML-based documentation from the .Fx Documentation Project will not be built. However, the .Dq doc distribution will still be created with the minimal documentation set provided in .Pa src/share/doc . .It Va TARGET The target hardware platform. This is analogous to the .Dq Nm uname Fl m output. This is necessary to cross-build some target architectures. For example, cross-building for PC98 machines requires .Va TARGET_ARCH Ns = Ns Li i386 and .Va TARGET Ns = Ns Li pc98 . If not set, .Va TARGET defaults to the current hardware platform. .It Va TARGET_ARCH The target machine processor architecture. This is analogous to the .Dq Nm uname Fl p output. Set this to cross-build for a different architecture. If not set, .Va TARGET_ARCH defaults to the current machine architecture, unless .Va TARGET is also set, in which case it defaults to the appropriate value for that platform. Typically, one only needs to set .Va TARGET . .El .Sh FILES -.Bl -tag -compact -width Pa +.Bl -tag -compact .It Pa /usr/doc/Makefile .It Pa /usr/doc/share/mk/doc.project.mk .It Pa /usr/ports/Mk/bsd.port.mk .It Pa /usr/ports/Mk/bsd.sites.mk .It Pa /usr/share/examples/etc/make.conf .It Pa /usr/src/Makefile .It Pa /usr/src/Makefile.inc1 .It Pa /usr/src/release/Makefile .It Pa /usr/src/release/generate-release.sh .El .Sh EXAMPLES The following sequence of commands can be used to build a .Dq "-CURRENT snapshot": .Bd -literal -offset indent cd /usr svn co svn://svn.freebsd.org/base/head src cd src make buildworld buildkernel cd release make release make install DESTDIR=/var/freebsd-snapshot .Ed .Pp After running these commands, all produced distribution files (tarballs for FTP, CD-ROM images, etc.) are available in the .Pa /var/freebsd-snapshot directory. .Pp The following sequence of commands can be used to build a .Dq "-CURRENT snapshot" in a clean environment, including ports and documentation: .Bd -literal -offset indent -cd /usr/src -make buildworld -cd release +cd /usr/src/release export CVSUP_HOST=cvsupN.freebsd.org sh generate-release.sh head /local3/release .Ed .Pp After running these commands, all prepared release files are available in the .Pa /local3/release/R directory. .Sh SEE ALSO .Xr cc 1 , .Xr cvs 1 , .Xr install 1 , .Xr make 1 , .Xr svn 1 Pq Pa ports/devel/subversion-freebsd , .Xr uname 1 , .Xr md 4 , .Xr make.conf 5 , .Xr build 7 , .Xr ports 7 , .Xr chroot 8 , .Xr mtree 8 , .Xr sysctl 8 .Rs .%T "FreeBSD Release Engineering" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/ .Re .Rs .%T "FreeBSD Release Engineering of Third Party Packages" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng-packages/ .Re .Rs .%T "FreeBSD Developers' Handbook" .%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ .Re .Sh HISTORY .Fx 1.x used a manual checklist, compiled by .An Rod Grimes , to produce a release. Apart from being incomplete, the list put a lot of specific demands on available file systems and was quite torturous to execute. .Pp As part of the .Fx 2.0 release engineering effort, significant effort was spent getting .Pa src/release/Makefile into a shape where it could at least automate most of the tediousness of building a release in a sterile environment. .Pp For the .Fx 9.0 -release, +release, .Pa src/release/Makefile was overhauled and the wrapper script .Pa src/release/generate-release.sh introduced to support the introduction of a new installer. .Pp At near 1000 revisions spread over multiple branches, the .Xr cvs 1 log of .Pa src/release/Makefile contains a vivid historical record of some of the hardships release engineers go through. .Sh AUTHORS .Pa src/release/Makefile was originally written by .An -nosplit .An Rod Grimes , .An Jordan Hubbard , and .An Poul-Henning Kamp . This manual page was written by .An Murray Stokely Aq murray@FreeBSD.org . Index: stable/9/share/man/man7 =================================================================== --- stable/9/share/man/man7 (revision 237215) +++ stable/9/share/man/man7 (revision 237216) Property changes on: stable/9/share/man/man7 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man7:r233648 Index: stable/9/share/man/man8/picobsd.8 =================================================================== --- stable/9/share/man/man8/picobsd.8 (revision 237215) +++ stable/9/share/man/man8/picobsd.8 (revision 237216) @@ -1,663 +1,663 @@ .\" -*- nroff-fill -*- .\" $FreeBSD$ .Dd June 25, 2009 .Dt PICOBSD 8 .Os .Sh NAME .Nm picobsd .Nd building small FreeBSD disk images .Sh SYNOPSIS .Nm .Op Ar options .Op Ar config-name Op Ar site-name .Sh DESCRIPTION The .Nm utility is a script which produces a minimal implementation of .Fx (historically called .Nm PicoBSD ) which typically fits on a small media such as a floppy disk, or can be downloaded as a single image file from some media such as CDROM, flash memory, or through .Xr etherboot . .Pp The .Nm utility was originally created to build simple standalone systems such as firewalls or bridges, but because of the ability to cross-build images with different source trees than the one in the server, it can be extremely useful to developers to test their code without having to reinstall the system. .Pp The boot media (historically a floppy disk, but also small CDROM or USB keys) contains a boot loader and a compressed kernel which includes a memory file system. Depending on the media, it might also contain a number of additional files, which can be updated at run time, and are used to override/update those in the memory file system. .Pp The system loads the kernel in the normal way, uncompresses the memory file system and mounts it as root. It then updates the memory file system with files from the boot media (if present), and executes a specialized version of .Pa /etc/rc . The boot media (floppy, etc.) is required for loading only, and typically used read-only. After the boot phase, the system runs entirely from RAM. .Pp The following options are available (but also check the .Nm script for more details). The most important options for common operations are .Fl src , .Fl init , .Fl n and .Fl v. .Bl -tag -width indent .\" .It Fl -all_in_mfs Put the entire contents of the file system in the memory file system image which is contained in the kernel. This is the default behaviour, and is extremely useful as the kernel itself can be loaded, using .Xr etherboot or .Xr pxeboot 8 , .\" .It Fl c , Fl clean Clean the product of previous builds. .\" .It Fl -cfg Ar file Specify a file that contains additional config commands. .\" .It Fl -floppy_size Ar size Set the size of the disk image. Typical values for a floppy disk are 1440 or 2880, but other values can be used for other media (flash memories, CDROM, network booted kernels). Note that this option is overridden by the content of the config files (config in the image tree, or the one specified with .Fl Fl cfg ) .\" .It Fl -init When used together with the .Fl -src option, this initializes the .Ao Ar SRC_PATH Ac Ns Pa /../usr subtree as necessary to subsequently build .Nm images. .\" .It Fl -iso Generate an ISO image, picobsd.iso, in addition to the disk image picobsd.bin .\" .It Fl -modules Also build kernel modules. These are not stored on the .Nm image but are left available in the build directory. .\" .It Fl n Make the script non-interactive, skipping the initial menu and proceeding with the build process without requiring user input. .\" .It Fl -no_all_in_mfs Leaves files contained in the .Pa floppy.tree on the .Nm image, so they can be loaded separately from the kernel (and updated individually to customize the image). .\" .It Fl -no_loader Omit /boot/loader, just rely on boot2 to load the kernel. This saves some space but may have problems with kernels > 4MB. .\" .It Fl -objdir Ar directory Specify a directory with the result of a previous buildworld. This saves the need for an .Fl Fl init call before creating an image. .\" .It Fl -src Ar SRC_PATH Use the source tree at .Ar SRC_PATH instead the one at .Pa /usr/src . This can be useful for cross-building .Nm images. When using this option, you must also create and initialize the subtree at .Ao Ar SRC_PATH Ac Ns Pa /../usr with the correct header files, libraries, and tools (such as the .Xr config 8 program) that are necessary for the cross-build (see the .Fl -init option). The source files are unmodified by the .Nm script. However the source tree is not completely read-only, because .Xr config 8 expects the kernel configuration file to be in one of its subdirectories, and also the process of initializing the .Pa usr subtree touches some parts of the source tree (this is a bug in the release build scripts which might go away with time). .\" .It Fl v Make the script verbose, showing commands to be executed and waiting for user input before executing each of them. Useful for debugging. as a fully functional system. .El .Sh ENVIRONMENT As a result of extreme size limitations, the .Nm environment differs from the normal .Fx in a number of ways: .Bl -bullet .It There are no dynamic libraries, and there is no directory .Pa /usr/lib . As a result, only static executables may be executed. .It In order to reduce the size of the executables, all executables on a specific floppy are joined together as a single executable built with .Xr crunchgen 1 . .It Some programs are supplied in minimalistic versions, specifically .Nm ns , a cut-down version of .Xr netstat 1 , and .Nm vm , a cut-down version of .Xr vmstat 8 . .El .Sh BUILDING PicoBSD The .Nm sources reside in the hierarchy .Pa /usr/src/release/picobsd . In the following discussion, all relative path names are relative to this directory. .Pp The supported build script is .Pa /usr/src/release/picobsd/build/picobsd which can be run from anywhere, and relies on the .Xr sysutils/makefs port to build a filesystem without requiring .Xr mdconfig or root privileges to mount a filesystem. When run in interactive mode (the default without the .Fl n option), the script will let you configure the various parameters used to build the PicoBSD image. An image is configured using the files and directories described below. The base system contains a template, called .Pa bridge for historical reasons, that can be used as a base for building various kinds of network appliances. .Pp You can define your own PicoBSD configuration, by creating a directory with a name of your choice (e.g.\& .Pa FOO ) which contains some of the following files and directories. For more information on how to construct these files, look at one of the standard .Nm configurations as a reference. .Bl -tag -width indent .It Pa PICOBSD The kernel configuration file (required). This is a mostly standard kernel configuration file, possibly stripped down by removing unnecessary drivers and options to reduce the kernel's size. .Pp To be recognised as a .Nm kernel config file, the file must also contain the line beginning with .Dq Li #PicoBSD below, and a matching .Dv MD_ROOT_SIZE option: .Bd -literal -offset indent #marker def_sz init MFS_inodes floppy_inodes #PicoBSD 4200 init 8192 32768 options MD_ROOT_SIZE=4200 # same as def_sz .Ed .Pp This informs the script of the size of the memory file system and provides a few other details on how to build the image. .It Pa crunch.conf .Xr crunchgen 1 configuration (required). It contains the list of directories containing program sources, the list of binaries to be built, and the list of libraries that these programs use. See the .Xr crunchgen 1 manpage for the exact details on the syntax of this file. .Pp The following issues are particularly important when dealing with .Nm configurations: .Bl -bullet .It We can pass build options to those makefiles which understand that, in order to reduce the size of the programs. This is achieved with a line of the form .Pp .Dl "buildopts -DNO_PAM -DRELEASE_CRUNCH ..." .It When providing the list of directories where source files are, it is convenient to list the following entry first: .Pp .Dl "srcdirs /usr/src/release/picobsd/tinyware" .Pp so that .Nm Ns -specific versions of the programs will be found there. .It The string .Dq Li @__CWD__@ is replaced with the full pathname of the directory where the .Nm configuration resides (i.e., the one where we find .Pa PICOBSD , crunch.conf , and so on). This can be useful to refer source code that resides within a configuration, e.g.\& .Pp .Dl "srcdirs @__CWD__@/src" .El .It Pa config Shell variables, sourced by the .Nm script (optional). The most important variables here are: .Bl -tag -width ".Va MY_DEVS" .It Va MY_DEVS (Not used in .Fx 5.0 where we have .Xr devfs 5 ) . Should be set to the list of devices to be created in the .Pa /dev directory of the image (it is really the argument passed to .Xr MAKEDEV 8 , so refer to that manpage for the names). .It Va fd_size Size (in kilobytes) of the .Nm image. By default, .Va fd_size is set to 1440 which produces an image suitable for a standard floppy. .Pp If you plan to store the image on a CDROM (e.g.\& using the .Dq "El Torito" floppy emulation), you can set .Va fd_size equal to 2880. If you are planning to dump the image onto a hard disk (either in a partition or on the whole disk), you are not restricted to one of the standard floppy sizes. Using a large image size per se does not waste RAM at runtime, because only the files that are actually loaded from the image contribute to the memory usage. .It Va import_files Contains a list of files to be imported in the floppy tree. Absolute names refer to the standard file system, relative names refer to the root of the source tree being used (i.e.\& .Va SRC_PATH/.. ) . You can normally use this option if you want to import files such as shared libraries, or databases, without having to replicate them first in your configuration under the .Pa floppy.tree/ directory. .El .It Pa floppy.tree.exclude List of files from the standard floppy tree which we do not want to be copied (optional). .It Pa floppy.tree/ Local additions to the standard floppy tree (optional). The content of this subtree will be copied as-is into the floppy image. .It Pa floppy.tree. Ns Aq Ar site-name Same as above, but site-specific (optional). .El .Pp More information on the build process can be found in the comments in the .Nm script. .Sh USING ALTERNATE SOURCE TREES The build script can be instructed to use an alternate source tree using the .Fl -src Ar SRC_PATH option. The tree that you specify must contain full sources for the kernel and for all programs that you want to include in your image. As an example, to cross-build the .Pa bridge floppy using RELENG_4 sources, you can do the following: .Bd -literal -offset indent cd mkdir FOO (cd FOO; cvs -d co -rRELENG_4 src) picobsd --src FOO/src --init # this is needed only once picobsd --src FOO/src -n -v bridge .Ed .Pp If the build is successful, the directory .Pa build_dir-bridge/ will contain a .Pa kernel that can be downloaded with .Xr etherboot , a floppy image called .Pa picobsd.bin , plus the products of the compilation in other directories. If you want to modify the source tree in .Pa FOO/src , a new image can be produced by simply running .Pp .Dl "picobsd --src FOO/src -n -v bridge" .Pp whereas if the change affects include files or libraries you first need to update them, e.g.\& by re-running .Pp .Dl "picobsd --src FOO/src --init # this is needed only once" .Pp as you would normally do for any change of this kind. .Sh INSTALLING PicoBSD .Ss Floppy Install Historically, .Nm is run from a floppy disk, where it can be installed with a simple .Pp .Dl "dd if=picobsd.bin of=/dev/rfd0" .Pp and the floppy is ready to boot. .Ss Hard Disk Install The same process can be used to store the image on a hard disk (entire volume or one of the slices): .Bd -literal -offset indent dd if=picobsd.bin of=/dev/ad2 dd if=picobsd.bin of=/dev/ad2s3 dd if=picobsd.bin of=/dev/ad2 oseek=NN .Ed .Pp The first form will install the image on the entire disk, and it should work in the same way as for a floppy. .Pp The second form will install the image on slice number 3 (which should be large enough to store the contents of the image). However, the process will only have success if the partition does not contain a valid disklabel, otherwise the kernel will likely prevent overwriting the label. In this case you can use the third form, replacing .Ar NN with the actual start of the partition (which you can determine using .Xr fdisk 8 ) . Note that after saving the image to the slice, it will not yet be recognised. You have to use the .Xr disklabel 8 command to properly initialize the label (do not ask why!). One way to do this is .Bd -literal -offset indent disklabel -w ad0s2 auto disklabel -e ad0s2 .Ed .Pp and from the editor enter a line corresponding to the actual partition, e.g.\& if the image has 2.88MB (5760 sectors) you need to enter the following line for the partition: .Pp .Dl "a: 5760 0 4.2BSD 512 4096" .Pp At this point the partition is bootable. Note that the image size can be smaller than the slice size (indicated as partition .Dq Li c: ) . .Ss CDROM Install .Nm can produce an ISO image named picobsd.iso, which does not use .Dq "El Torito" emulation, so it has no size restrictions. Installing means just burning a media with the file. .Ss Booting From The Network Yet another way to use .Nm is to boot the image off the network. For this purpose you should use the uncompressed kernel which is available as a byproduct of the compilation. Refer to the documentation for network booting for more details, the .Nm kernel is bootable as a standard .Fx kernel. .Sh BOOTING PicoBSD To boot .Nm , insert the floppy and reset the machine. The boot procedure is similar to the standard .Fx boot. Booting from a floppy is normally rather slow (in the order of 1-2 minutes), things are much faster if you store your image on a hard disk, Compact Flash, or CDROM. .Pp You can also use .Xr etherboot to load the preloaded, uncompressed kernel image which is a byproduct of the .Nm build. In this case the load time is a matter of a few seconds, even on a 10Mbit/s ethernet. .Pp After booting, .Nm loads the root file system from the memory file system, starts .Pa /sbin/init , and passes control to a first startup script, .Pa /etc/rc . The latter populates the .Pa /etc and .Pa /root directories with the default files, then tries to identify the boot device (floppy, hard disk partition) and possibly override the contents of the root file system with files read from the boot device. This allows you to store local configuration on the same media. After this phase the boot device is no longer used, unless the user specifically does it. .Pp After this, control is transferred to a second script, .Pa /etc/rc1 (which can be overridden from the boot device). This script tries to associate a hostname to the system by using the MAC address of the first ethernet interface as a key, and .Pa /etc/hosts as a lookup table. Then control is passed to the main user configuration script, .Pa /etc/rc.conf , which is supposed to override the value of a number of configuration variables which have been pre-set in .Pa /etc/rc.conf.defaults . You can use the .Va hostname variable to create different configurations from the same file. After taking control back, .Pa /etc/rc1 completes the initializations, and as part of this it configures network interfaces and optionally calls the firewall configuration script, .Pa /etc/rc.firewall , where the user can store his own firewall configuration. .Pp Note that by default .Nm runs entirely from main memory, and has no swap space, unless you explicitly request it. The boot device is also not used anymore after .Pa /etc/rc1 takes control, again, unless you explicitly request it. .Sh CONFIGURING a PicoBSD system The operation of a .Nm system can be configured through a few files which are read at boot time, very much like a standard .Fx system. There are, however, some minor differences to reduce the number of files to store and/or customize, thus saving space. Among the files to configure we have the following: .Bl -tag -width indent .It Pa /etc/hosts Traditionally, this file contains the IP-to-hostname mappings. In addition to this, the .Nm version of this file also contains a mapping between Ethernet (MAC) addresses and hostnames, as follows: .Bd -literal -offset indent #ethertable start of the ethernet->hostname mapping # mac_address hostname # 00:12:34:56:78:9a pinco # 12:34:56:* pallino # * this-matches-all .Ed .Pp where the line containing .Dq Li #ethertable marks the start of the table. .Pp If the MAC address is not found, the script will prompt you to enter a hostname and IP address for the system, and this information will be stored in the .Pa /etc/hosts file (in memory) so you can simply store them on disk later. .Pp Note that you can use wildcards in the address part, so a line like the last one in the example will match any MAC address and avoid the request. .It Pa /etc/rc.conf This file contains a number of variables which control the operation of the system, such as interface configuration, router setup, network service startup, etc. For the exact list and meaning of these variables see .Pa /etc/rc.conf.defaults . .Pp It is worth mentioning that some of the variables let you overwrite the contents of some files in .Pa /etc . This option is available at the moment for .Pa /etc/host.conf and .Pa /etc/resolv.conf , whose contents are generally very short and suitable for this type of updating. In case you use these variables, remember to use newlines as appropriate, e.g.\& .Bd -literal -offset indent host_conf="# this goes into /etc/host.conf hosts bind" .Ed .Pp Although not mandatory, in this file you should only set the variables indicated in .Pa /etc/rc.conf.defaults , and avoid starting services which depend on having the network running. This can be done at a later time: if you set .Va firewall_enable Ns = Ns Qq Li YES , the .Pa /etc/rc.firewall script will be run after configuring the network interfaces, so you can set up your firewall and safely start network services or enable things such as routing and bridging. .It Pa /etc/rc.firewall This script can be used to configure the .Xr ipfw 4 firewall. On entry, the .Va fwcmd variable is set to the pathname of the firewall command, .Va firewall_type contains the value set in .Pa /etc/rc.conf , and .Va hostname contains the name assigned to the host. .El .Pp There is a small script called .Nm update which can be used to edit and/or save to disk a copy of the files you have modified after booting. The script takes one or more absolute pathnames, runs the editor on the files passed as arguments, and then saves a compressed copy of the files on the disk (mounting and unmounting the latter around the operation). .Pp If invoked without arguments, .Nm update edits and saves .Pa rc.conf , rc.firewall , and .Pa master.passwd . .Pp If one of the arguments is .Pa /etc (the directory name alone), then the command saves to disk (without editing) all the files in the directory for which a copy already exists on disk (e.g.\& as a result of a previous update). .Sh SEE ALSO .Xr crunchgen 1 , .Xr mdconfig 8 , .Xr nanobsd 8 , -.Xr swapon 8 +.Xr swapon 8 .Sh AUTHORS .An -nosplit .An Andrzej Bialecki Aq abial@FreeBSD.org , with subsequent work on the scripts by .An Luigi Rizzo Aq luigi@iet.unipi.it and others. Man page and .Pa Makefiles created by .An Greg Lehey Aq grog@lemis.com . .Sh BUGS Documentation is still incomplete. Index: stable/9/share/man/man8 =================================================================== --- stable/9/share/man/man8 (revision 237215) +++ stable/9/share/man/man8 (revision 237216) Property changes on: stable/9/share/man/man8 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man8:r233648 Index: stable/9/share/man/man9/BUS_DESCRIBE_INTR.9 =================================================================== --- stable/9/share/man/man9/BUS_DESCRIBE_INTR.9 (revision 237215) +++ stable/9/share/man/man9/BUS_DESCRIBE_INTR.9 (revision 237216) @@ -1,104 +1,104 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2009 Advanced Computing Technologies LLC .\" Written by: John H. Baldwin .\" 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. .\" .\" $FreeBSD$ .\" .Dd October 14, 2009 .Dt BUS_DESCRIBE_INTR 9 .Os .Sh NAME .Nm BUS_DESCRIBE_INTR , .Nm bus_describe_intr .Nd "associate a description with an active interrupt handler" .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int .Fo BUS_BIND_INTR .Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookie" .Fa "const char *descr" .Fc .Ft int .Fo bus_describe_intr .Fa "device_t dev" "struct resource *irq" "void *cookie" "const char *fmt" -.Fa ... +.Fa ... .Fc .Sh DESCRIPTION The .Fn BUS_DESCRIBE_INTR method associates a description with an active interrupt handler. The .Fa cookie parameter must be the value returned by a successful call to .Xr BUS_SETUP_INTR 9 for the interrupt .Fa irq . .Pp The .Fn bus_describe_intr function is a simple wrapper around .Fn BUS_DESCRIBE_INTR . As a convenience, .Fn bus_describe_intr allows the caller to use .Xr printf 9 style formatting to build the description string using .Fa fmt . .Pp When an interrupt handler is established by .Xr BUS_SETUP_INTR 9 , the handler is named after the device the handler is established for. This name is then used in various places such as interrupt statistics displayed by .Xr systat 1 and .Xr vmstat 8 . For devices that use a single interrupt, the device name is sufficiently unique to identify the interrupt handler. However, for devices that use multiple interrupts it can be useful to distinguish the interrupt handlers. When a description is set for an active interrupt handler, a colon followed by the description is appended to the device name to form the interrupt handler name. .Sh RETURN VALUES Zero is returned on success, otherwise an appropriate error is returned. .Sh SEE ALSO .Xr BUS_SETUP_INTR 9 , .Xr systat 1 , .Xr vmstat 8 , .Xr device 9 , .Xr printf 9 .Sh HISTORY The .Fn BUS_DESCRIBE_INTR method and .Fn bus_describe_intr functions first appeared in .Fx 8.1 . .Sh BUGS It is not currently possible to remove a description from an active interrupt handler. Index: stable/9/share/man/man9/BUS_SETUP_INTR.9 =================================================================== --- stable/9/share/man/man9/BUS_SETUP_INTR.9 (revision 237215) +++ stable/9/share/man/man9/BUS_SETUP_INTR.9 (revision 237216) @@ -1,216 +1,216 @@ .\" Copyright (c) 2000 Jeroen Ruigrok van der Werven .\" 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. .\" .\" $FreeBSD$ .\" .Dd November 3, 2010 .Dt BUS_SETUP_INTR 9 .Os .Sh NAME .Nm BUS_SETUP_INTR , .Nm bus_setup_intr , .Nm BUS_TEARDOWN_INTR , .Nm bus_teardown_intr .Nd create, attach and teardown an interrupt handler .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int .Fo BUS_SETUP_INTR .Fa "device_t dev" "device_t child" "struct resource *irq" "int flags" .Fa "driver_filter_t *filter" "driver_intr_t *ithread" "void *arg" .Fa "void **cookiep" .Fc .Ft int .Fo bus_setup_intr .Fa "device_t dev" "struct resource *r" "int flags" .Fa "driver_filter_t filter" "driver_intr_t ithread" "void *arg" .Fa "void **cookiep" .Fc .Ft int .Fo BUS_TEARDOWN_INTR .Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookiep" .Fc .Ft int .Fn bus_teardown_intr "device_t dev" "struct resource *r" "void *cookiep" .Sh DESCRIPTION The .Fn BUS_SETUP_INTR method will create and attach an interrupt handler to an interrupt previously allocated by the resource manager's .Xr BUS_ALLOC_RESOURCE 9 method. The .Fa flags are found in .In sys/bus.h , and give the broad category of interrupt. The .Fa flags also tell the interrupt handlers about certain device driver characteristics. .Dv INTR_EXCL marks the handler as being an exclusive handler for this interrupt. .Dv INTR_MPSAFE tells the scheduler that the interrupt handler is well behaved in a preemptive environment (``SMP safe''), and does not need to be protected by the ``Giant Lock'' mutex. .Dv INTR_ENTROPY marks the interrupt as being a good source of entropy - this may be used by the entropy device .Pa /dev/random . .Pp To define a time-critical handler that will not execute any potentially blocking operation, use the .Fa filter argument. See the .Sx "Filter Routines" section below for information on writing a filter. Otherwise, use the .Fa ithread argument. The defined handler will be called with the value .Fa arg as its only argument. See the .Sx "ithread Routines" section below for more information on writing an interrupt handler. .Pp The .Fa cookiep argument is a pointer to a .Vt "void *" that .Fn BUS_SETUP_INTR will write a cookie for the parent bus' use to if it is successful in establishing an interrupt. Driver writers may assume that this cookie will be non-zero. The nexus driver will write 0 on failure to .Fa cookiep . .Pp The interrupt handler will be detached by .Fn BUS_TEARDOWN_INTR . The cookie needs to be passed to .Fn BUS_TEARDOWN_INTR in order to tear down the correct interrupt handler. Once .Fn BUS_TEARDOWN_INTR returns, it is guaranteed that the interrupt function is not active and will no longer be called. .Pp Mutexes are not allowed to be held across calls to these functions. .Ss "Filter Routines" A filter runs in primary interrupt context. In this context, normal mutexes cannot be used. Only the spin lock version of these can be used (specified by passing -.Dv MTX_SPIN -to +.Dv MTX_SPIN +to .Fn mtx_init when initializing the mutex). .Xr wakeup 9 and similar routines can be called. Atomic operations from .Pa machine/atomic may be used. Reads and writes to hardware through .Xr bus_space 9 may be used. PCI configuration registers may be read and written. All other kernel interfaces cannot be used. .Pp In this restricted environment, care must be taken to account for all races. A careful analysis of races should be done as well. It is generally cheaper to take an extra interrupt, for example, than to protect variables with spinlocks. Read, modify, write cycles of hardware registers need to be carefully analyzed if other threads are accessing the same registers. .Pp Generally, a filter routine will use one of two strategies. The first strategy is to simply mask the interrupt in hardware and allow the .Dv ithread routine to read the state from the hardware and then reenable interrupts. The .Dv ithread also acknowledges the interrupt before re-enabling the interrupt source in hardware. Most PCI hardware can mask its interrupt source. .Pp The second common approach is to use a filter with multiple .Xr taskqueue 9 tasks. In this case, the filter acknowledges the interrupts and queues the work to the appropriate taskqueue. Where one has to multiplex different kinds of interrupt sources, like a network card's transmit and receive paths, this can reduce lock contention and increase performance. .Pp You should not .Xr malloc 9 from inside a filter. You may not call anything that uses a normal mutex. Witness may complain about these. .Ss "ithread Routines" You can do whatever you want in an ithread routine, except sleep. Care must be taken not to sleep in an ithread. In addition, one should minimize lock contention in an ithread routine because contested locks ripple over to all other ithread routines on that interrupt. .Ss "Sleeping" Sleeping is voluntarily giving up control of your thread. All the sleep routine found in .Xr msleep 9 sleep. Waiting for a condition variable described in .Xr condvar 9 is sleeping. Calling any function that does any of these things is sleeping. .Sh RETURN VALUES Zero is returned on success, otherwise an appropriate error is returned. .Sh SEE ALSO .Xr random 4 , .Xr device 9 , .Xr driver 9 , .Xr locking 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Jeroen Ruigrok van der Werven .Aq asmodai@FreeBSD.org based on the manual pages for .Fn BUS_CREATE_INTR and .Fn BUS_CONNECT_INTR written by .An Doug Rabson .Aq dfr@FreeBSD.org . Index: stable/9/share/man/man9/DB_COMMAND.9 =================================================================== --- stable/9/share/man/man9/DB_COMMAND.9 (revision 237215) +++ stable/9/share/man/man9/DB_COMMAND.9 (revision 237216) @@ -1,111 +1,111 @@ .\"- .\" Copyright (c) 2008 Guillaume Ballet .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 27, 2008 .Dt DB_COMMAND 9 .Os .Sh NAME .Nm DB_COMMAND , .Nm DB_SHOW_COMMAND , .Nm DB_SHOW_ALL_COMMAND .Nd Extends the ddb command set .Sh SYNOPSIS .In ddb/ddb.h .Fo DB_COMMAND .Fa command_name .Fa command_function -.Fc -.Fn DB_SHOW_COMMAND "command_name" "command_function" -.Fn DB_SHOW_ALL_COMMAND "command_name" "command_function" +.Fc +.Fn DB_SHOW_COMMAND "command_name" "command_function" +.Fn DB_SHOW_ALL_COMMAND "command_name" "command_function" .Sh DESCRIPTION .Pp The .Fn DB_COMMAND macro adds .Fa command_name to the list of top-level commands. -Invoking +Invoking .Fa command_name -from ddb will call +from ddb will call .Fa command_function . .Pp The .Fn DB_SHOW_COMMAND and .Fn DB_SHOW_ALL_COMMAND are roughly equivalent to .Fn DB_COMMAND but in these cases, .Fa command_name -is a sub-command of the ddb +is a sub-command of the ddb .Sy show command and .Sy show all command, respectively. .Pp The general command syntax: -.Cm command Ns Op Li \&/ Ns Ar modifier +.Cm command Ns Op Li \&/ Ns Ar modifier .Ar address Ns Op Li , Ns Ar count , translates into the following parameters for .Fa command_function : .Bl -tag -width Fa -offset indent .It Fa addr The address passed to the command as an argument. .It Fa have_addr A boolean value that is true if the addr field is valid. .It Fa count The number of quad words starting at offset .Fa addr that the command must process. .It Fa modif A pointer to the string of modifiers. That is, a series of symbols used to pass some options to the command. For example, the .Sy examine command will display words in decimal form if it is passed the modifier "d". .El .Sh EXAMPLE In your module, the command is declared as: .Bd -literal DB_COMMAND(mycmd, my_cmd_func) { if (have_addr) db_printf("Calling my command with address %p\\n", addr); } .Ed .Pp Then, when in ddb: .Bd -literal .Bf Sy db> mycmd 0x1000 Calling my command with address 0x1000 db> .Ef .Ed .Sh "SEE ALSO" .Xr ddb 4 .Sh AUTHOR This manual page was written by .An Guillaume Ballet Aq gballet@gmail.com . Index: stable/9/share/man/man9/DEVICE_PROBE.9 =================================================================== --- stable/9/share/man/man9/DEVICE_PROBE.9 (revision 237215) +++ stable/9/share/man/man9/DEVICE_PROBE.9 (revision 237216) @@ -1,139 +1,139 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1998 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 8, 2012 .Dt DEVICE_PROBE 9 .Os .Sh NAME .Nm DEVICE_PROBE .Nd probe for device existence .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int .Fn DEVICE_PROBE "device_t dev" .Sh DESCRIPTION The .Fn DEVICE_PROBE method should probe to see if the device is present. It should return 0 if the device exists, .Er ENXIO if it cannot be found. If some other error happens during the probe (such as a memory allocation failure), an appropriate error code should be returned. For cases where more than one driver matches a device, a priority value can be returned. In this case, success codes are values less than or equal to zero with the highest value representing the best match. Failure codes are represented by positive values and the regular .Ux error codes should be used for the purpose. .Pp If a driver returns a success code which is less than zero, it must not assume that it will be the same driver which is attached to the device. In particular, it must not assume that any values stored in the softc structure will be available for its attach method and any resources allocated during probe must be released and re-allocated if the attach method is called. In addition it is an absolute requirement that the probe routine have no side effects whatsoever. The probe routine may be called more than once before the attach routine is called. .Pp If a success code of zero is returned, the driver can assume that it will be the one attached, but must not hold any resources when the probe routine returns. A driver may assume that the softc is preserved when it returns a success code of zero. .Sh RETURN VALUES A value equal to or less than zero indicates success, greater than zero indicates an error (errno). For values equal to or less than zero: zero indicates highest priority, no further probing is done; for a value less than zero, the lower the value the lower the priority, e.g.\& -100 indicates a lower priority than -50. .Pp The following values are used by convention to indicate different strengths of matching in a probe routine. Except as noted, these are just suggested values, and there's nothing magical about them. .Bl -tag -width BUS_PROBE_NOWILDCARD .It BUS_PROBE_SPECIFIC The device that cannot be reprobed, and that no possible other driver may exist (typically legacy drivers who don't follow all the rules, or special needs drivers). .It BUS_PROBE_VENDOR The device is supported by a vendor driver. This is for source or binary drivers that are not yet integrated into the -.Fx +.Fx tree. Its use in the base OS is prohibited. .It BUS_PROBE_DEFAULT The device is a normal device matching some plug and play ID. This is the normal return value for drivers to use. It is intended that nearly all of the drivers in the tree should return this value. .It BUS_PROBE_LOW_PRIORITY The driver is a legacy driver, or an otherwise less desirable driver for a given plug and play ID. The driver has special requirements like when there are two drivers that support overlapping series of hardware devices. In this case the one that supports the older part of the line would return this value, while the one that supports the newer ones would return BUS_PROBE_DEFAULT. .It BUS_PROBE_GENERIC The driver matches the type of device generally. This allows drivers to match all serial ports generally, with specialized drivers matching particular types of serial ports that need special treatment for some reason. .It BUS_PROBE_HOOVER The driver matches all unclaimed devices on a bus. -The -.Xr ugen 4 +The +.Xr ugen 4 device is one example. .It BUS_PROBE_NOWILDCARD The driver expects its parent to tell it which children to manage and no probing is really done. The device only matches if its parent bus specifically said to use this driver. .El .Sh SEE ALSO .Xr device 9 , .Xr DEVICE_ATTACH 9 , .Xr DEVICE_DETACH 9 , .Xr DEVICE_IDENTIFY 9 , .Xr DEVICE_SHUTDOWN 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: stable/9/share/man/man9/SYSINIT.9 =================================================================== --- stable/9/share/man/man9/SYSINIT.9 (revision 237215) +++ stable/9/share/man/man9/SYSINIT.9 (revision 237216) @@ -1,163 +1,163 @@ .\" Copyright (c) 2003 Hiten M. Pandya .\" 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. .\" .\" $FreeBSD$ .\" .Dd December 1, 2010 .Dt SYSINIT 9 .Os .Sh NAME .Nm SYSINIT , -.Nm SYSUNINIT +.Nm SYSUNINIT .Nd a framework for dynamic kernel initialization .Sh SYNOPSIS .In sys/param.h .In sys/kernel.h .Fn SYSINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident" .Fn SYSUNINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident" .Sh DESCRIPTION .Nm is a mechanism for scheduling the execution of initialization and teardown routines. This is similar to init and fini routines with the addition of explicit ordering metadata. It allows runtime ordering of subsystem initialization in the kernel as well as kernel modules (KLDs). .Pp The .Fn SYSINIT macro creates a .Vt struct sysinit and stores it in a startup linker set. The .Vt struct sysinit type as well as the subsystem identifier constants .Pq Dv SI_SUB_* and initialization ordering constants .Pq Dv SI_ORDER_* are defined in .In sys/kernel.h : .Bd -literal struct sysinit { enum sysinit_sub_id subsystem; /* subsystem identifier*/ enum sysinit_elem_order order; /* init order within subsystem*/ sysinit_cfunc_t func; /* function */ const void *udata; /* multiplexer/argument */ }; .Ed .Pp The .Fn SYSINIT macro takes a .Fa uniquifier argument to identify the particular function dispatch data, the .Fa subsystem type of startup interface, the subsystem element .Fa order of initialization within the subsystem, the .Fa func function to call, and the data specified in .Fa ident argument to pass the function. .Pp The .Fn SYSUNINIT macro behaves similarly to the .Fn SYSINIT macro except that it adds the data to a shutdown linker set. .Pp The startup linker set for the kernel is scanned during boot to build a sorted list of initialization routines. The initialization routines are then executed in the sorted order. The .Fa subsystem is used as the primary key and is sorted in ascending order. The .Fa order is used as the secondary key and is sorted in ascending order. The relative order of two routines that have the same .Fa subsystem and .Fa order is undefined. .Pp The startup linker sets for modules that are loaded together with the kernel by the boot loader are scanned during the .Dv SI_SUB_KLD subsystem initialization. These modules' initialization routines are sorted and merged into the kernel's list of startup routines and are executed during boot along with the kernel's initialization routines. Note that this has the effect that any initialization routines in a kernel module that are scheduled earlier than .Dv SI_SUB_KLD are not executed until after .Dv SI_SUB_KLD during boot. .Pp The startup linker set for a kernel module loaded at runtime via .Xr kldload 2 is scanned, sorted, and executed when the module is loaded. .Pp The shutdown linker set for a kernel module is scanned, sorted, and executed when a kernel module is unloaded. The teardown routines are sorted in the reverse order of the initialization routines. The teardown routines of the kernel and any loaded modules are .Sy not executed during shutdown. .Sh EXAMPLES This example shows the SYSINIT which displays the copyright notice during boot: .Bd -literal -offset indent static void print_caddr_t(void *data) { printf("%s", (char *)data); } SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, copyright); .Ed .Sh SEE ALSO .Xr kld 4 , .Xr DECLARE_MODULE 9 , .Xr DEV_MODULE 9 , .Xr DRIVER_MODULE 9 , .Xr MTX_SYSINIT 9 , .Xr SYSCALL_MODULE 9 .Sh HISTORY The .Nm framework first appeared in .Fx 2.2 . .Sh AUTHORS .An -nosplit The .Nm framework was written by .An Terrence Lambert Aq terry@FreeBSD.org . .Pp This manual page was written by .An Hiten Pandya Aq hmp@FreeBSD.org . Index: stable/9/share/man/man9/buf_ring.9 =================================================================== --- stable/9/share/man/man9/buf_ring.9 (revision 237215) +++ stable/9/share/man/man9/buf_ring.9 (revision 237216) @@ -1,144 +1,144 @@ .\" Copyright (c) 2009 Bitgravity Inc .\" Written by: Kip Macy .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 30, 2012 .Dt BUF_RING 9 .Os .Sh NAME .Nm buf_ring , .Nm buf_ring_alloc , .Nm buf_ring_free , .Nm buf_ring_enqueue , .Nm buf_ring_enqueue_bytes , .Nm buf_ring_dequeue_mc , .Nm buf_ring_dequeue_sc , .Nm buf_ring_count , .Nm buf_ring_empty , .Nm buf_ring_full , .Nm buf_ring_peek , .Nd multi-producer, {single, multi}-consumer lock-less ring buffer .Sh SYNOPSIS .In sys/param.h .In sys/buf_ring.h .Ft struct buf_ring * .Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock" .Ft void .Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type" .Ft int .Fn buf_ring_enqueue "struct buf_ring *br" "void *buf" .Ft int .Fn buf_ring_enqueue_bytes "struct buf_ring *br" "void *buf" "int bytes" .Ft void * .Fn buf_ring_dequeue_mc "struct buf_ring *br" .Ft void * .Fn buf_ring_dequeue_sc "struct buf_ring *br" .Ft int .Fn buf_ring_count "struct buf_ring *br" .Ft int .Fn buf_ring_empty "struct buf_ring *br" .Ft int .Fn buf_ring_full "struct buf_ring *br" .Ft void * .Fn buf_ring_peek "struct buf_ring *br" .Sh DESCRIPTION The .Nm functions provide a lock-less multi-producer and lock-less multi-consumer as -well as single-consumer ring buffer. +well as single-consumer ring buffer. .Pp The .Fn buf_ring_alloc function is used to allocate a buf_ring ring buffer with .Fa count slots using malloc_type .Fa type and memory flags .Fa flags . The single consumer interface is protected by .Fa sc_lock . .Pp The .Fn buf_ring_free function is used to free a buf_ring. The user is responsible for freeing any enqueued items. .Pp The .Fn buf_ring_enqueue function is used to enqueue a buffer to a buf_ring. .Pp The .Fn buf_ring_enqueue_bytes function is used to enqueue a buffer to a buf_ring and increment the number of bytes enqueued by .Fa bytes . .Pp The .Fn buf_ring_dequeue_mc function is a multi-consumer safe way of dequeueing elements from a buf_ring. .Pp The .Fn buf_ring_dequeue_sc function is a single-consumer interface to dequeue elements - requiring the user to serialize accesses with a lock. .Pp The .Fn buf_ring_count function returns the number of elements in a buf_ring. .Pp The .Fn buf_ring_empty function returns .Dv TRUE if the buf_ring is empty, .Dv FALSE otherwise. .Pp The .Fn buf_ring_full function returns .Dv TRUE if no more items can be enqueued, .Dv FALSE otherwise. .Pp The .Fn buf_ring_peek function returns a pointer to the last element in the buf_ring if the buf_ring is not empty, .Dv NULL otherwise. .Sh RETURN VALUES The .Fn buf_ring_enqueue and .Fn buf_ring_enqueue_bytes functions return .Er ENOBUFS if there are no available slots in the buf_ring. .Sh HISTORY These functions were introduced in .Fx 8.0 . Index: stable/9/share/man/man9/condvar.9 =================================================================== --- stable/9/share/man/man9/condvar.9 (revision 237215) +++ stable/9/share/man/man9/condvar.9 (revision 237216) @@ -1,233 +1,233 @@ .\" .\" Copyright (C) 2000 Jason Evans . 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(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 5, 2007 .Dt CONDVAR 9 .Os .Sh NAME .Nm condvar , .Nm cv_init , .Nm cv_destroy , .Nm cv_wait , .Nm cv_wait_sig , .Nm cv_wait_unlock , .Nm cv_timedwait , .Nm cv_timedwait_sig , .Nm cv_signal , .Nm cv_broadcast , .Nm cv_broadcastpri , .Nm cv_wmesg .Nd kernel condition variable .Sh SYNOPSIS .In sys/param.h .In sys/proc.h .In sys/condvar.h .Ft void .Fn cv_init "struct cv *cvp" "const char *desc" .Ft void .Fn cv_destroy "struct cv *cvp" .Ft void .Fn cv_wait "struct cv *cvp" "lock" .Ft int .Fn cv_wait_sig "struct cv *cvp" "lock" .Ft void .Fn cv_wait_unlock "struct cv *cvp" "lock" .Ft int .Fn cv_timedwait "struct cv *cvp" "lock" "int timo" .Ft int .Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo" .Ft void .Fn cv_signal "struct cv *cvp" .Ft void .Fn cv_broadcast "struct cv *cvp" .Ft void .Fn cv_broadcastpri "struct cv *cvp" "int pri" .Ft const char * .Fn cv_wmesg "struct cv *cvp" .Sh DESCRIPTION Condition variables are used in conjunction with mutexes to wait for conditions to occur. Condition variables are created with .Fn cv_init , where .Fa cvp is a pointer to space for a .Vt struct cv , and .Fa desc is a pointer to a null-terminated character string that describes the condition variable. Condition variables are destroyed with .Fn cv_destroy . Threads wait on condition variables by calling .Fn cv_wait , .Fn cv_wait_sig , .Fn cv_wait_unlock , .Fn cv_timedwait , or .Fn cv_timedwait_sig . Threads unblock waiters by calling .Fn cv_signal to unblock one waiter, or .Fn cv_broadcast or .Fn cv_broadcastpri to unblock all waiters. In addition to waking waiters, .Fn cv_broadcastpri ensures that all of the waiters have a priority of at least .Fa pri by raising the priority of any threads that do not. .Fn cv_wmesg returns the description string of .Fa cvp , as set by the initial call to .Fn cv_init . .Pp The .Fa lock argument is a pointer to either a .Xr mutex 9 , .Xr rwlock 9 , or .Xr sx 9 lock. -A +A .Xr mutex 9 argument must be initialized with -.Dv MTX_DEF +.Dv MTX_DEF and not .Dv MTX_SPIN . A thread must hold .Fa lock before calling .Fn cv_wait , .Fn cv_wait_sig , .Fn cv_wait_unlock , .Fn cv_timedwait , or .Fn cv_timedwait_sig . When a thread waits on a condition, .Fa lock is atomically released before the thread is blocked, then reacquired before the function call returns. In addition, the thread will fully drop the .Va Giant mutex (even if recursed) while the it is suspended and will reacquire the .Va Giant mutex before the function returns. The .Fn cv_wait_unlock function does not reacquire the lock before returning. Note that the .Va Giant mutex may be specified as .Fa lock . However, .Va Giant may not be used as .Fa lock for the .Fn cv_wait_unlock function. All waiters must pass the same .Fa lock in conjunction with .Fa cvp . .Pp When .Fn cv_wait , .Fn cv_wait_sig , .Fn cv_wait_unlock , .Fn cv_timedwait , and .Fn cv_timedwait_sig unblock, their calling threads are made runnable. .Fn cv_timedwait and .Fn cv_timedwait_sig wait for at most .Fa timo / .Dv HZ seconds before being unblocked and returning .Er EWOULDBLOCK ; otherwise, they return 0. .Fn cv_wait_sig and .Fn cv_timedwait_sig return prematurely with a value of .Er EINTR or .Er ERESTART if a signal is caught, or 0 if signaled via .Fn cv_signal or .Fn cv_broadcast . .Sh RETURN VALUES If successful, .Fn cv_wait_sig , .Fn cv_timedwait , and .Fn cv_timedwait_sig return 0. Otherwise, a non-zero error code is returned. .Pp .Fn cv_wmesg returns the description string that was passed to .Fn cv_init . .Sh ERRORS .Fn cv_wait_sig and .Fn cv_timedwait_sig will fail if: .Bl -tag -width Er .It Bq Er EINTR A signal was caught and the system call should be interrupted. .It Bq Er ERESTART A signal was caught and the system call should be restarted. .El .Pp .Fn cv_timedwait and .Fn cv_timedwait_sig will fail if: .Bl -tag -width Er .It Bq Er EWOULDBLOCK Timeout expired. .El .Sh SEE ALSO .Xr locking 9 , .Xr mtx_pool 9 , .Xr mutex 9 , .Xr rwlock 9 , .Xr sema 9 , .Xr sleep 9 , .Xr sx 9 Index: stable/9/share/man/man9/devclass_get_maxunit.9 =================================================================== --- stable/9/share/man/man9/devclass_get_maxunit.9 (revision 237215) +++ stable/9/share/man/man9/devclass_get_maxunit.9 (revision 237216) @@ -1,66 +1,66 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1998 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 September 10, 2010 .Dt DEVCLASS_GET_MAXUNIT 9 .Os .Sh NAME .Nm devclass_get_maxunit .Nd find the maximum unit number in the class .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int .Fn devclass_get_maxunit "devclass_t dc" .Sh DESCRIPTION Returns the next unit number to be allocated to device instances in the .Dv devclass . This is one greater than the highest currently allocated unit. .Sh RETURN VALUES The .Fn devclass_get_maxunit function returns -1 if .Fa dc -is +is .Dv NULL , otherwise it returns the next unit number in .Fa dc's devclass. .Sh ERRORS None. .Sh SEE ALSO .Xr devclass 9 , .Xr device 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . .Sh BUGS The name is confusing since it is one greater than the maximum unit. Index: stable/9/share/man/man9/device_get_children.9 =================================================================== --- stable/9/share/man/man9/device_get_children.9 (revision 237215) +++ stable/9/share/man/man9/device_get_children.9 (revision 237216) @@ -1,62 +1,62 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1998 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 August 23, 2008 .Dt DEVICE_GET_CHILDREN 9 .Os .Sh NAME .Nm device_get_children .Nd get a list of devices connected to a device .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Ft int .Fn device_get_children "device_t dev" "device_t **devlistp" "int *devcountp" .Sh DESCRIPTION Retrieve a list of all device instances currently connected to .Pa dev and return the list in .Fa *devlistp and the count in .Fa *devcountp . The memory allocated for the list should be freed using .Fn free "*devlistp" "M_TEMP" . -.Fa devlistp +.Fa devlistp and -.Fa devcountp +.Fa devcountp are not changed when an error is returned. .Sh RETURN VALUES Zero is returned on success, otherwise an appropriate error is returned. .Sh SEE ALSO .Xr devclass 9 , .Xr device 9 .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: stable/9/share/man/man9/drbr.9 =================================================================== --- stable/9/share/man/man9/drbr.9 (revision 237215) +++ stable/9/share/man/man9/drbr.9 (revision 237216) @@ -1,147 +1,147 @@ .\" Copyright (c) 2009 Bitgravity Inc .\" Written by: Kip Macy .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 30, 2012 .Dt DRBR 9 .Os .Sh NAME .Nm drbr , .Nm drbr_free , .Nm drbr_enqueue , .Nm drbr_dequeue , .Nm drbr_dequeue_cond , .Nm drbr_flush , .Nm drbr_empty , .Nm drbr_inuse , .Nm drbr_stats_update , .Nd network driver interface to buf_ring .Sh SYNOPSIS .In sys/param.h .In net/if.h .In net/if_var.h .Ft void .Fn drbr_free "struct buf_ring *br" "struct malloc_type *type" .Ft int .Fn drbr_enqueue "struct ifnet *ifp" "struct buf_ring *br" "struct mbuf *m" .Ft struct mbuf * .Fn drbr_dequeue "struct ifnet *ifp" "struct buf_ring *br" .Ft struct mbuf * .Fn drbr_dequeue_cond "struct ifnet *ifp" "struct buf_ring *br" "int (*func) (struct mbuf *, void *)" "void *arg" .Ft void .Fn drbr_flush "struct ifnet *ifp" "struct buf_ring *br" .Ft int .Fn drbr_empty "struct ifnet *ifp" "struct buf_ring *br" .Ft int .Fn drbr_inuse "struct ifnet *ifp" "struct buf_ring *br" .Ft void .Fn drbr_stats_update "struct ifnet *ifp" "int len" "int mflags" .Sh DESCRIPTION The .Nm functions provide an API to network drivers for using .Xr buf_ring 9 for enqueueing and dequeueing packets. This is meant as a replacement for the IFQ interface for packet queuing. It allows a packet to be enqueued with a single atomic and packet dequeue to be done without any per-packet atomics as it is protected by the driver's tx queue lock. If .Dv INVARIANTS is enabled, .Fn drbr_dequeue will assert that the tx queue lock is held when it is called. .Pp The -.Fn drbr_free +.Fn drbr_free function frees all the enqueued mbufs and then frees the buf_ring. .Pp The .Fn drbr_enqueue function is used to enqueue an mbuf to a buf_ring, falling back to the ifnet's IFQ if .Xr ALTQ 4 is enabled. .Pp The .Fn drbr_dequeue function is used to dequeue an mbuf from a buf_ring or, if .Xr ALTQ 4 is enabled, from the ifnet's IFQ. .Pp The .Fn drbr_dequeue_cond function is used to conditionally dequeue an mbuf from a buf_ring based on whether .Fa func returns .Dv TRUE or .Dv FALSE . .Pp The .Fn drbr_flush function frees all mbufs enqueued in the buf_ring and the ifnet's IFQ. .Pp -The +The .Fn drbr_empty function returns .Dv TRUE if there are no mbufs enqueued, .Dv FALSE otherwise. .Pp The .Fn drbr_inuse function returns the number of mbufs enqueued. Note to users that this is intrinsically racy as there is no guarantee that -there will not be more mbufs when +there will not be more mbufs when .Fn drbr_dequeue is actually called. Provided the tx queue lock is held there will not be less. .Pp The .Fn drbr_stats_update function updates the number of bytes and the number of multicast packets sent. .Sh RETURN VALUES The .Fn drbr_enqueue function returns .Er ENOBUFS if there are no slots available in the buf_ring and .Dv 0 on success. .Pp The .Fn drbr_dequeue -and +and .Fn drbr_dequeue_cond functions return an mbuf on success and .Dv NULL if the buf_ring is empty. .Sh HISTORY These functions were introduced in .Fx 8.0 . Index: stable/9/share/man/man9/eventtimers.9 =================================================================== --- stable/9/share/man/man9/eventtimers.9 (revision 237215) +++ stable/9/share/man/man9/eventtimers.9 (revision 237216) @@ -1,236 +1,236 @@ .\" .\" Copyright (c) 2011 Alexander Motin .\" 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 DEVELOPERS ``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 DEVELOPERS 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 December 14, 2011 .Dt EVENTTIMERS 9 .Os .Sh NAME .Nm eventtimers .Nd kernel event timers subsystem .Sh SYNOPSIS .In sys/timeet.h .Bd -literal struct eventtimer; typedef int et_start_t(struct eventtimer *et, struct bintime *first, struct bintime *period); typedef int et_stop_t(struct eventtimer *et); typedef void et_event_cb_t(struct eventtimer *et, void *arg); typedef int et_deregister_cb_t(struct eventtimer *et, void *arg); struct eventtimer { SLIST_ENTRY(eventtimer) et_all; char *et_name; int et_flags; #define ET_FLAGS_PERIODIC 1 #define ET_FLAGS_ONESHOT 2 #define ET_FLAGS_PERCPU 4 #define ET_FLAGS_C3STOP 8 #define ET_FLAGS_POW2DIV 16 int et_quality; int et_active; u_int64_t et_frequency; struct bintime et_min_period; struct bintime et_max_period; et_start_t *et_start; et_stop_t *et_stop; et_event_cb_t *et_event_cb; et_deregister_cb_t *et_deregister_cb; void *et_arg; void *et_priv; struct sysctl_oid *et_sysctl; }; .Ed .Ft int .Fn et_register "struct eventtimer *et" .Ft int .Fn et_deregister "struct eventtimer *et" .Fn ET_LOCK .Fn ET_UNLOCK .Ft struct eventtimer * .Fn et_find "const char *name" "int check" "int want" .Ft int .Fn et_init "struct eventtimer *et" "et_event_cb_t *event" "et_deregister_cb_t *deregister" "void *arg" .Ft int .Fn et_start "struct eventtimer *et" "struct bintime *first" "struct bintime *period" .Ft int .Fn et_stop "struct eventtimer *et" .Ft int .Fn et_ban "struct eventtimer *et" .Ft int .Fn et_free "struct eventtimer *et" .Sh DESCRIPTION Event timers are responsible for generating interrupts at specified time or periodically, to run different time-based events. Subsystem consists of three main parts: .Bl -tag -width "Consumers" .It Drivers Manage hardware to generate requested time events. .It Consumers .Pa sys/kern/kern_clocksource.c uses event timers to supply kernel with .Fn hardclock , .Fn statclock and .Fn profclock time events. .It Glue code .Pa sys/sys/timeet.h , .Pa sys/kern/kern_et.c provide APIs for event timer drivers and consumers. .El .Sh DRIVER API Driver API is built around eventtimer structure. To register its functionality driver allocates that structure and calls .Fn et_register . Driver should fill following fields there: .Bl -tag -width Va .It Va et_name Unique name of the event timer for management purposes. .It Va et_flags Set of flags, describing timer capabilities: .Bl -tag -width "ET_FLAGS_PERIODIC" -compact .It ET_FLAGS_PERIODIC Periodic mode supported. .It ET_FLAGS_ONESHOT One-shot mode supported. .It ET_FLAGS_PERCPU Timer is per-CPU. .It ET_FLAGS_C3STOP Timer may stop in CPU sleep state. .It ET_FLAGS_POW2DIV Timer supports only 2^n divisors. .El .It Va et_quality Abstract value to certify whether this timecounter is better than the others. Higher value means better. .It Va et_frequency Timer oscillator's base frequency, if applicable and known. Used by consumers to predict set of possible frequencies that could be obtained by dividing it. Should be zero if not applicable or unknown. .It Va et_min_period , et_max_period Minimal and maximal reliably programmable time periods. .It Va et_start Driver's timer start function pointer. .It Va et_stop Driver's timer stop function pointer. .It Va et_priv Driver's private data storage. .El .Pp After the event timer functionality is registered, it is controlled via .Va et_start and .Va et_stop methods. .Va et_start method is called to start the specified event timer. The last two arguments are used to specify time when events should be generated. .Va first argument specifies time period before the first event generated. In periodic mode NULL value specifies that first period is equal to the .Va period argument value. .Va period argument specifies the time period between following events for the periodic mode. The NULL value there specifies the one-shot mode. At least one of these two arguments should be not NULL. When event time arrive, driver should call .Va et_event_cb callback function, passing .Va et_arg as the second argument. .Va et_stop method is called to stop the specified event timer. For the per-CPU event timers .Va et_start and .Va et_stop methods control timers associated with the current CPU. .Pp Driver may deregister its functionality by calling .Fn et_deregister . .Sh CONSUMER API .Fn et_find allows consumer to find available event timer, optionally matching specific name and/or capability flags. Consumer may read returned eventtimer structure, but should not modify it. When wanted event timer is found, .Fn et_init should be called for it, submitting .Va event and optionally .Va deregister callbacks functions, and the opaque argument .Va arg . That argument will be passed as argument to the callbacks. Event callback function will be called on scheduled time events. It is called from the hardware interrupt context, so no sleep is permitted there. Deregister callback function may be called to report consumer that the event timer functionality is no longer available. On this call, consumer should stop using event timer before the return. .Pp After the timer is found and initialized, it can be controlled via .Fn et_start and .Fn et_stop . The arguments are the same as described in driver API. Per-CPU event timers can be controlled only from specific CPUs. .Pp .Fn et_ban allows consumer to mark event timer as broken via clearing both one-shot and periodic capability flags, if it was somehow detected. .Fn et_free is the opposite to .Fn et_init . It releases the event timer for other consumers use. .Pp .Fn ET_LOCK -and +and .Fn ET_UNLOCK macros should be used to manage .Xr mutex 9 lock around .Fn et_find , .Fn et_init and .Fn et_free calls to serialize access to the list of the registered event timers and the pointers returned by .Fn et_find . .Fn et_start and .Fn et_stop calls should be serialized in consumer's internal way to avoid concurrent timer hardware access. .Sh SEE ALSO .Xr eventtimers 4 .Sh AUTHORS .An Alexander Motin Aq mav@FreeBSD.org Index: stable/9/share/man/man9/firmware.9 =================================================================== --- stable/9/share/man/man9/firmware.9 (revision 237215) +++ stable/9/share/man/man9/firmware.9 (revision 237216) @@ -1,272 +1,272 @@ .\" Copyright (c) 2006 Max Laier .\" 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 DEVELOPERS ``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 DEVELOPERS 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 August 2, 2008 .Dt FIRMWARE 9 .Os .Sh NAME .Nm firmware_register , .Nm firmware_unregister , .Nm firmware_get , .Nm firmware_put .Nd firmware image loading and management .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In sys/linker.h .In sys/firmware.h .Bd -literal struct firmware { const char *name; /* system-wide name */ const void *data; /* location of image */ size_t datasize; /* size of image in bytes */ unsigned int version; /* version of the image */ }; .Ed .Ft "const struct firmware *" .Fo firmware_register .Fa "const char *imagename" .Fa "const void *data" .Fa "size_t datasize" .Fa "unsigned int version" .Fa "const struct firmware *parent" .Fc .Ft int .Fn firmware_unregister "const char *imagename" .Ft "const struct firmware *" .Fn firmware_get "const char *imagename" .Ft void .Fn firmware_put "const struct firmware *fp" "int flags" .Sh DESCRIPTION The .Nm firmware abstraction provides a convenient interface for loading .Nm firmware images into the kernel, and for accessing such images from kernel components. .Pp A .Nm firmware image (or .Nm image for brevity) is an opaque block of data residing in kernel memory. It is associated to a unique .Nm imagename which constitutes a search key, and to an integer .Nm version number, which is also an opaque piece of information for the firmware subsystem. .Pp An image is registered with the .Nm firmware subsystem by calling the function .Fn firmware_register , and unregistered by calling .Fn firmware_unregister . These functions are usually (but not exclusively) called by specially crafted kernel modules that contain the firmware image. The modules can be statically compiled in the kernel, or loaded by .Nm /boot/loader , manually at runtime, or on demand by the firmware subsystem. .Pp .Nm Clients of the firmware subsystem can request access to a given image by calling the function .Fn firmware_get with the .Nm imagename they want as an argument. If a matching image is not already registered, the firmware subsystem will try to load it using the mechanisms specified below (typically, a kernel module with .Nm the same name as the image). .Sh API DESCRIPTION The kernel .Nm firmware API is made of the following functions: .Pp .Fn firmware_register registers with the kernel an image of size .Nm datasize located at address .Nm data , under the name .Nm imagename . .Pp The function returns NULL on error (e.g. because an image with the same name already exists, or the image table is full), or a .Ft const struct firmware * pointer to the image requested. .Pp .Fn firmware_unregister tries to unregister the firmware image .Nm imagename from the system. The function is successful and returns 0 if there are no pending references to the image, otherwise it does not unregister the image and returns EBUSY. .Pp .Fn firmware_get returns the requested firmware image. If the image is not yet registered with the system, the function tries to load it. This involves the linker subsystem and disk access, so .Fn firmware_get must not be called with any locks (except for .Va Giant ) . Note also that if the firmware image is loaded from a filesystem it must already be mounted. In particular this means that it may be necessary to defer requests from a driver attach method unless it is known the root filesystem is already mounted. .Pp On success, .Fn firmware_get returns a pointer to the image description and increases the reference count for this image. On failure, the function returns NULL. .Pp .Fn firmware_put drops a reference to a firmware image. The .Fa flags argument may be set to .Dv FIRMWARE_UNLOAD to indicate that firmware_put is free to reclaim resources associated with the firmware image if this is the last reference. -By default a firmware image will be deferred to a +By default a firmware image will be deferred to a .Xr taskqueue 9 thread so the call may be done while holding a lock. In certain cases, such as on driver detach, this cannot be allowed. .Sh FIRMWARE LOADING MECHANISMS As mentioned before, any component of the system can register firmware images at any time by simply calling .Fn firmware_register . .Pp This is typically done when a module containing a firmware image is given control, whether compiled in, or preloaded by .Nm /boot/loader , or manually loaded with .Xr kldload 8 . However, a system can implement additional mechanisms to bring these images in memory before calling .Fn firmware_register . .Pp When .Fn firmware_get does not find the requested image, it tries to load it using one of the available loading mechanisms. At the moment, there is only one, namely .Nm Loadable kernel modules : .Pp A firmware image named .Nm foo is looked up by trying to load the module named .Nm foo.ko , using the facilities described in .Xr kld 4 . In particular, images are looked up in the directories specified by the sysctl variable .Nm kern.module_path which on most systems defaults to .Nm /boot/kernel;/boot/modules . .Pp Note that in case a module contains multiple images, the caller should first request a .Fn firmware_get for the first image contained in the module, followed by requests for the other images. .Sh BUILDING FIRMWARE LOADABLE MODULES A firmware module is built by embedding the .Nm firmware image into a suitable loadable kernel module that calls .Fn firmware_register on loading, and .Fn firmware_unregister on unloading. .Pp Various system scripts and makefiles let you build a module by simply writing a Makefile with the following entries: .Bd -literal KMOD= imagename FIRMWS= image_file:imagename[:version] .include .Ed where KMOD is the basename of the module; FIRMWS is a list of colon-separated tuples indicating the image_file's to be embedded in the module, the imagename and version of each firmware image. .Pp If you need to embed firmware images into a system, you should write appropriate entries in the file, e.g. this example is from .Nm sys/arm/xscale/ixp425/files.ixp425 : .Bd -literal ixp425_npe_fw.c optional npe_fw \\ compile-with "${AWK} -f $S/tools/fw_stub.awk \\ IxNpeMicrocode.dat:npe_fw -mnpe -c${.TARGET}" \\ no-implicit-rule before-depend local \\ clean "ixp425_npe_fw.c" # # NB: ld encodes the path in the binary symbols generated for the # firmware image so link the file to the object directory to # get known values for reference in the _fw.c file. # IxNpeMicrocode.fwo optional npe_fw \\ dependency "IxNpeMicrocode.dat" \\ compile-with "${LD} -b binary -d -warn-common \\ -r -d -o ${.TARGET} IxNpeMicrocode.dat" \\ no-implicit-rule \\ clean "IxNpeMicrocode.fwo" IxNpeMicrocode.dat optional npe_fw \\ dependency ".PHONY" \\ compile-with "uudecode < $S/contrib/dev/npe/IxNpeMicrocode.dat.uu" \\ no-obj no-implicit-rule \\ clean "IxNpeMicrocode.dat" .Ed .Pp Note that generating the firmware modules in this way requires the availability of the following tools: .Xr awk , .Xr Make , the compiler and the linker. .Sh SEE ALSO .Xr module 9 , .Xr kld 4 .Pp .Pa /usr/share/examples/kld/firmware .Sh HISTORY The .Nm firmware system was introduced in .Fx 6.1 . .Sh AUTHORS This manual page was written by .An Max Laier Aq mlaier@FreeBSD.org . Index: stable/9/share/man/man9/ieee80211.9 =================================================================== --- stable/9/share/man/man9/ieee80211.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211.9 (revision 237216) @@ -1,568 +1,568 @@ .\" .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd April 28, 2010 .Dt IEEE80211 9 .Os .Sh NAME -.Nm IEEE80211 +.Nm IEEE80211 .Nd 802.11 network layer .Sh SYNOPSIS .In net80211/ieee80211_var.h .Ft void .Fn ieee80211_ifattach "struct ieee80211com *ic" "const uint8_t macaddr[IEEE80211_ADDR_LEN]" .Ft void .Fn ieee80211_ifdetach "struct ieee80211com *ic" .Sh DESCRIPTION IEEE 802.11 device drivers are written to use the infrastructure provided by the .Nm software layer. This software provides a support framework for drivers that includes ifnet cloning, state management, and a user management API by which applications interact with 802.11 devices. Most drivers depend on the .Nm layer for protocol services but devices that off-load functionality may bypass the layer to connect directly to the device (e.g. the .Xr ndis 4 emulation support does this). .Pp A .Nm device driver implements a virtual radio API that is exported to users through network interfaces (aka vaps) that are cloned from the underlying device. These interfaces have an operating mode (station, adhoc, hostap, wds, monitor, etc.) that is fixed for the lifetime of the interface. Devices that can support multiple concurrent interfaces allow multiple vaps to be cloned. This enables construction of interesting applications such as an AP vap and one or more WDS vaps or multiple AP vaps, each with a different security model. The .Nm layer virtualizes most 802.11 state and coordinates vap state changes including scheduling multiple vaps. State that is not virtualized includes the current channel and WME/WMM parameters. Protocol processing is typically handled entirely in the .Nm layer with drivers responsible purely for moving data between the host and device. Similarly, .Nm handles most .Xr ioctl 2 requests without entering the driver; instead drivers are notified of state changes that require their involvement. .Pp The virtual radio interface defined by the .Nm layer means that drivers must be structured to follow specific rules. Drivers that support only a single interface at any time must still follow these rules. .Sh DATA STRUCTURES The virtual radio architecture splits state between a single per-device .Vt ieee80211com structure and one or more .Vt ieee80211vap structures. Drivers are expected to setup various shared state in these structures at device attach and during vap creation but otherwise should treat them as read-only. The .Vt ieee80211com structure is allocated by the .Nm layer as adjunct data to a device's .Vt ifnet ; it is accessed through the .Vt if_l2com structure member. The .Vt ieee80211vap structure is allocated by the driver in the .Dq vap create method and should be extended with any driver-private state. This technique of giving the driver control to allocate data structures is used for other .Nm data structures and should be exploited to maintain driver-private state together with public .Nm state. .Pp The other main data structures are the station, or node, table that tracks peers in the local BSS, and the channel table that defines the current set of available radio channels. Both tables are bound to the .Vt ieee80211com structure and shared by all vaps. Long-lasting references to a node are counted to guard against premature reclamation. In particular every packet sent/received holds a node reference (either explicitly for transmit or implicitly on receive). .Pp The .Vt ieee80211com and .Vt ieee80211vap structures also hold a collection of method pointers that drivers fill-in and/or override to take control of certain operations. These methods are the primary way drivers are bound to the .Nm layer and are described below. .Sh DRIVER ATTACH/DETACH Drivers attach to the .Nm layer with the .Fn ieee80211_ifattach function. The driver is expected to allocate and setup any device-private data structures before passing control. The .Vt ieee80211com structure must be pre-initialized with state required to setup the .Nm layer: .Bl -tag -width ic_channels .It Dv ic_ifp Backpointer to the physical device's ifnet. .It Dv ic_caps Device/driver capabilities; see below for a complete description. .It Dv ic_channels Table of channels the device is capable of operating on. This is initially provided by the driver but may be changed through calls that change the regulatory state. .It Dv ic_nchan -Number of entries in +Number of entries in .Dv ic_channels . .El .Pp On return from .Fn ieee80211_ifattach the driver is expected to override default callback functions in the .Vt ieee80211com structure to register it's private routines. Methods marked with a .Dq * must be provided by the driver. .Bl -tag -width ic_channels .It Dv ic_vap_create* Create a vap instance of the specified type (operating mode). Any fixed BSSID and/or MAC address is provided. Drivers that support multi-bssid operation may honor the requested BSSID or assign their own. .It Dv ic_vap_delete* Destroy a vap instance created with .Dv ic_vap_create . .It Dv ic_getradiocaps Return the list of calibrated channels for the radio. The default method returns the current list of channels (space permitting). .It Dv ic_setregdomain Process a request to change regulatory state. The routine may reject a request or constrain changes (e.g. reduce transmit power caps). The default method accepts all proposed changes. .It Dv ic_send_mgmt Send an 802.11 management frame. The default method fabricates the frame using .Nm state and passes it to the driver through the .Dv ic_raw_xmit method. .It Dv ic_raw_xmit Transmit a raw 802.11 frame. The default method drops the frame and generates a message on the console. .It Dv ic_updateslot Update hardware state after an 802.11 IFS slot time change. There is no default method; the pointer may be NULL in which case it will not be used. .It Dv ic_update_mcast Update hardware for a change in the multicast packet filter. The default method prints a console message. .It Dv ic_update_promisc Update hardware for a change in the promiscuous mode setting. The default method prints a console message. .It Dv ic_newassoc Update driver/device state for association to a new AP (in station mode) or when a new station associates (e.g. in AP mode). There is no default method; the pointer may be NULL in which case it will not be used. .It Dv ic_node_alloc Allocate and initialize a -.Vt ieee80211_node +.Vt ieee80211_node structure. This method cannot sleep. The default method allocates zero'd memory using .Xr malloc 9 . Drivers should override this method to allocate extended storage for their own needs. Memory allocated by the driver must be tagged with .Dv M_80211_NODE to balance the memory allocation statistics. .It Dv ic_node_free -Reclaim storage of a node allocated by +Reclaim storage of a node allocated by .Dv ic_node_alloc . Drivers are expected to .Em interpose their own method to cleanup private state but must call through this method to allow .Nm to reclaim it's private state. .It Dv ic_node_cleanup Cleanup state in a .Vt ieee80211_node created by .Dv ic_node_alloc . This operation is distinguished from .Dv ic_node_free in that it may be called long before the node is actually reclaimed to cleanup adjunct state. This can happen, for example, when a node must not be reclaimed due to references held by packets in the transmit queue. Drivers typically interpose .Dv ic_node_cleanup instead of .Dv ic_node_free . .It Dv ic_node_age Age, and potentially reclaim, resources associated with a node. The default method ages frames on the power-save queue (in AP mode) and pending frames in the receive reorder queues (for stations using A-MPDU). .It Dv ic_node_drain Reclaim all optional resources associated with a node. This call is used to free up resources when they are in short supply. .It Dv ic_node_getrssi Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for the specified node. This interface returns a subset of the information returned by .Dv ic_node_getsignal . The default method calculates a filtered average over the last ten samples passed in to .Xr ieee80211_input 9 or .Xr ieee80211_input_all 9 . .It Dv ic_node_getsignal Return the RSSI and noise floor (in .5 dBm units) for a station. The default method calculates RSSI as described above; the noise floor returned is the last value supplied to .Xr ieee80211_input 9 or .Xr ieee80211_input_all 9 . .It Dv ic_node_getmimoinfo Return MIMO radio state for a station in support of the .Dv IEEE80211_IOC_STA_INFO ioctl request. The default method returns nothing. .It Dv ic_scan_start* Prepare driver/hardware state for scanning. This callback is done in a sleepable context. .It Dv ic_scan_end* Restore driver/hardware state after scanning completes. This callback is done in a sleepable context. .It Dv ic_set_channel* Set the current radio channel using .Vt ic_curchan . This callback is done in a sleepable context. .It Dv ic_scan_curchan Start scanning on a channel. This method is called immediately after each channel change and must initiate the work to scan a channel and schedule a timer to advance to the next channel in the scan list. This callback is done in a sleepable context. The default method handles active scan work (e.g. sending ProbeRequest -frames), and schedules a call to +frames), and schedules a call to .Xr ieee80211_scan_next 9 according to the maximum dwell time for the channel. Drivers that off-load scan work to firmware typically use this method to trigger per-channel scan activity. .It Dv ic_scan_mindwell Handle reaching the minimum dwell time on a channel when scanning. This event is triggered when one or more stations have been found on a channel and the minimum dwell time has been reached. This callback is done in a sleepable context. The default method signals the scan machinery to advance to the next channel as soon as possible. Drivers can use this method to preempt further work (e.g. if scanning is handled by firmware) or ignore the request to force maximum dwell time on a channel. .It Dv ic_recv_action Process a received Action frame. The default method points to .Xr ieee80211_recv_action 9 which provides a mechanism for setting up handlers for each Action frame class. .It Dv ic_send_action Transmit an Action frame. The default method points to .Xr ieee80211_send_action 9 which provides a mechanism for setting up handlers for each Action frame class. .It Dv ic_ampdu_enable Check if transmit A-MPDU should be enabled for the specified station and AC. The default method checks a per-AC traffic rate against a per-vap threshold to decide if A-MPDU should be enabled. This method also rate-limits ADDBA requests so that requests are not made too frequently when a receiver has limited resources. .It Dv ic_addba_request Request A-MPDU transmit aggregation. The default method sets up local state and issues an ADDBA Request Action frame. Drivers may interpose this method if they need to setup private state for handling transmit A-MPDU. .It Dv ic_addb_response Process a received ADDBA Response Action frame and setup resources as needed for doing transmit A-MPDU. .It Dv ic_addb_stop Shutdown an A-MPDU transmit stream for the specified station and AC. The default method reclaims local state after sending a DelBA Action frame. .It Dv ic_bar_response Process a response to a transmitted BAR control frame. .It Dv ic_ampdu_rx_start Prepare to receive A-MPDU data from the specified station for the TID. .It Dv ic_ampdu_rx_stop Terminate receipt of A-MPDU data from the specified station for the TID. .El .Pp Once the -.Nm +.Nm layer is attached to a driver there are two more steps typically done to complete the work: .Bl -enum .It Setup .Dq radiotap support for capturing raw 802.11 packets that pass through the device. This is done with a call to .Xr ieee80211_radiotap_attach 9 . .It Do any final device setup like enabling interrupts. .El .Pp State is torn down and reclaimed with a call to .Fn ieee80211_ifdetach . Note this call may result in multiple callbacks into the driver so it should be done before any critical driver state is reclaimed. On return from .Fn ieee80211_ifdetach all associated vaps and ifnet structures are reclaimed or inaccessible to user applications so it is safe to teardown driver state without worry about being re-entered. The driver is responsible for calling .Xr if_free 9 on the ifnet it allocated for the physical device. .Sh DRIVER CAPABILITIES Driver/device capabilities are specified using several sets of flags in the .Vt ieee80211com structure. General capabilities are specified by .Vt ic_caps . Hardware cryptographic capabilities are specified by .Vt ic_cryptocaps . 802.11n capabilities, if any, are specified by .Vt ic_htcaps . The .Nm layer propagates a subset of these capabilities to each vap through the equivalent fields: .Vt iv_caps , .Vt iv_cryptocaps , and .Vt iv_htcaps . The following general capabilities are defined: .Bl -tag -width IEEE80211_C_8023ENCAP .It Dv IEEE80211_C_STA Device is capable of operating in station (aka Infrastructure) mode. .It Dv IEEE80211_C_8023ENCAP Device requires 802.3-encapsulated frames be passed for transmit. -By default +By default .Nm will encapsulate all outbound frames as 802.11 frames (without a PLCP header). .It Dv IEEE80211_C_FF Device supports Atheros Fast-Frames. .It Dv IEEE80211_C_TURBOP Device supports Atheros Dynamic Turbo mode. .It Dv IEEE80211_C_IBSS Device is capable of operating in adhoc/IBSS mode. .It Dv IEEE80211_C_PMGT Device supports dynamic power-management (aka power save) in station mode. .It Dv IEEE80211_C_HOSTAP Device is capable of operating as an Access Point in Infrastructure mode. .It Dv IEEE80211_C_AHDEMO Device is capable of operating in Adhoc Demo mode. In this mode the device is used purely to send/receive raw 802.11 frames. .It Dv IEEE80211_C_SWRETRY Device supports software retry of transmitted frames. .It Dv IEEE80211_C_TXPMGT Device support dynamic transmit power changes on transmitted frames; also known as Transmit Power Control (TPC). .It Dv IEEE80211_C_SHSLOT Device supports short slot time operation (for 802.11g). .It Dv IEEE80211_C_SHPREAMBLE Device supports short preamble operation (for 802.11g). .It Dv IEEE80211_C_MONITOR Device is capable of operating in monitor mode. .It Dv IEEE80211_C_DFS Device supports radar detection and/or DFS. DFS protocol support can be handled by .Nm but the device must be capable of detecting radar events. .It Dv IEEE80211_C_MBSS Device is capable of operating in MeshBSS (MBSS) mode (as defined by 802.11s Draft 3.0). .It Dv IEEE80211_C_WPA1 Device supports WPA1 operation. .It Dv IEEE80211_C_WPA2 Device supports WPA2/802.11i operation. .It Dv IEEE80211_C_BURST Device supports frame bursting. .It Dv IEEE80211_C_WME Device supports WME/WMM operation (at the moment this is mostly support for sending and receiving QoS frames with EDCF). .It Dv IEEE80211_C_WDS Device supports transmit/receive of 4-address frames. .It Dv IEEE80211_C_BGSCAN Device supports background scanning. .It Dv IEEE80211_C_TXFRAG Device supports transmit of fragmented 802.11 frames. .It Dv IEEE80211_C_TDMA Device is capable of operating in TDMA mode. .El .Pp The follow general crypto capabilities are defined. In general .Nm will fall-back to software support when a device is not capable of hardware acceleration of a cipher. This can be done on a per-key basis. .Nm can also handle software .Dv Michael calculation combined with hardware .Dv AES acceleration. .Bl -tag -width IEEE80211_C_8023ENCAP .It Dv IEEE80211_CRYPTO_WEP Device supports hardware WEP cipher. .It Dv IEEE80211_CRYPTO_TKIP Device supports hardware TKIP cipher. .It Dv IEEE80211_CRYPTO_AES_OCB Device supports hardware AES-OCB cipher. .It Dv IEEE80211_CRYPTO_AES_CCM Device supports hardware AES-CCM cipher. .It Dv IEEE80211_CRYPTO_TKIPMIC Device supports hardware Michael for use with TKIP. .It Dv IEEE80211_CRYPTO_CKIP Devices supports hardware CKIP cipher. .El .Pp The follow general 802.11n capabilities are defined. The first capabilities are defined exactly as they appear in the 802.11n specification. Capabilities beginning with IEEE80211_HTC_AMPDU are used solely by the .Nm layer. .Bl -tag -width IEEE80211_C_8023ENCAP .It Dv IEEE80211_HTCAP_CHWIDTH40 Device supports 20/40 channel width operation. .It Dv IEEE80211_HTCAP_SMPS_DYNAMIC Device supports dynamic SM power save operation. .It Dv IEEE80211_HTCAP_SMPS_ENA Device supports static SM power save operation. .It Dv IEEE80211_HTCAP_GREENFIELD Device supports Greenfield preamble. .It Dv IEEE80211_HTCAP_SHORTGI20 Device supports Short Guard Interval on 20MHz channels. .It Dv IEEE80211_HTCAP_SHORTGI40 Device supports Short Guard Interval on 40MHz channels. .It Dv IEEE80211_HTCAP_TXSTBC Device supports Space Time Block Convolution (STBC) for transmit. .It Dv IEEE80211_HTCAP_RXSTBC_1STREAM Device supports 1 spatial stream for STBC receive. .It Dv IEEE80211_HTCAP_RXSTBC_2STREAM Device supports 1-2 spatial streams for STBC receive. .It Dv IEEE80211_HTCAP_RXSTBC_3STREAM Device supports 1-3 spatial streams for STBC receive. .It Dv IEEE80211_HTCAP_MAXAMSDU_7935 Device supports A-MSDU frames up to 7935 octets. .It Dv IEEE80211_HTCAP_MAXAMSDU_3839 Device supports A-MSDU frames up to 3839 octets. .It Dv IEEE80211_HTCAP_DSSSCCK40 Device supports use of DSSS/CCK on 40MHz channels. .It Dv IEEE80211_HTCAP_PSMP Device supports PSMP. .It Dv IEEE80211_HTCAP_40INTOLERANT Device is intolerant of 40MHz wide channel use. .It Dv IEEE80211_HTCAP_LSIGTXOPPROT Device supports L-SIG TXOP protection. .It Dv IEEE80211_HTC_AMPDU Device supports A-MPDU aggregation. Note that any 802.11n compliant device must support A-MPDU receive -so this implicitly means support for +so this implicitly means support for .Em transmit of A-MPDU frames. .It Dv IEEE80211_HTC_AMSDU Device supports A-MSDU aggregation. Note that any 802.11n compliant device must support A-MSDU receive -so this implicitly means support for +so this implicitly means support for .Em transmit of A-MSDU frames. -.It Dv IEEE80211_HTC_HT +.It Dv IEEE80211_HTC_HT Device supports High Throughput (HT) operation. This capability must be set to enable 802.11n functionality in .Nm . .It Dv IEEE80211_HTC_SMPS Device supports MIMO Power Save operation. .It Dv IEEE80211_HTC_RIFS Device supports Reduced Inter Frame Spacing (RIFS). .El .Sh SEE ALSO .Xr ioctl 2 , .Xr ndis 4 , .Xr ieee80211_amrr 9 , .Xr ieee80211_beacon 9 , .Xr ieee80211_bmiss 9 , .Xr ieee80211_crypto 9 , .Xr ieee80211_ddb 9 , .Xr ieee80211_input 9 , .Xr ieee80211_node 9 , .Xr ieee80211_output 9 , .Xr ieee80211_proto 9 , .Xr ieee80211_radiotap 9 , .Xr ieee80211_regdomain 9 , .Xr ieee80211_scan 9 , .Xr ieee80211_vap 9 , .Xr ifnet 9 , .Xr malloc 9 Index: stable/9/share/man/man9/ieee80211_amrr.9 =================================================================== --- stable/9/share/man/man9/ieee80211_amrr.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_amrr.9 (revision 237216) @@ -1,194 +1,194 @@ .\" .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 4, 2009 .Dt IEEE8021_AMRR 9 .Os .Sh NAME .Nm ieee80211_amrr .Nd 802.11 network driver transmit rate control support .Sh SYNOPSIS .In net80211/ieee80211_amrr.h .Ft void .Fo ieee80211_amrr_init .Fa "struct ieee80211_amrr *" .Fa "struct ieee80211vap *" .Fa "int amin" .Fa "int amax" .Fa "int interval" .Fc .\" .Ft void .Fn ieee80211_amrr_cleanup "struct ieee80211_amrr *" .\" .Ft void .Fn ieee80211_amrr_setinterval "struct ieee80211_amrr *" "int interval" .\" .Ft void .Fo ieee80211_amrr_node_init .Fa "struct ieee80211_amrr *" .Fa "struct ieee80211_amrr_node *" .Fa "struct ieee80211_node *" .Fc .\" .Ft int .Fo ieee80211_amrr_choose .Fa "struct ieee80211_node *" .Fa "struct ieee80211_amrr_node *" .Fc .\" .Ft void .Fo ieee80211_amrr_tx_complete .Fa "struct ieee80211_amrr_node *" .Fa "int ok" .Fa "int retries" .Fc .\" .Ft void .Fo ieee80211_amrr_tx_update .Fa "struct ieee80211_amrr_node *" .Fa "int txnct" .Fa "int success" .Fa "int retrycnt" .Fc .Sh DESCRIPTION .Nm is an implementation of the AMRR transmit rate control algorithm for drivers that use the .Nm net80211 software layer. A rate control algorithm is responsible for choosing the transmit rate for each frame. To maximize throughput algorithms try to use the highest rate that is appropriate for the operating conditions. The rate will vary as conditions change; the distance between two stations -may change, transient noise may be present that affects signal quality, +may change, transient noise may be present that affects signal quality, etc. .Nm uses very simple information from a driver to do it's job: whether a frame was successfully delivered and how many transmit attempts were made. While this enables its use with virtually any wireless device it limits it's effectiveness--do not expect it to function well in difficult environments and/or respond quickly to changing conditions. .Pp .Nm requires per-vap state and per-node state for each station it is to select rates for. The API's are designed for drivers to pre-allocate state in the driver-private extension areas of each vap and node. For example the .Xr ral 4 driver defines a vap as: .Bd -literal -offset indent struct rt2560_vap { struct ieee80211vap ral_vap; struct ieee80211_beacon_offsets ral_bo; struct ieee80211_amrr amrr; int (*ral_newstate)(struct ieee80211vap *, enum ieee80211_state, int); }; .Ed .Pp The .Vt amrr structure member holds the per-vap state for .Nm -and -.Xr ral 4 +and +.Xr ral 4 initializes it in the vap create method with: .Bd -literal -offset indent ieee80211_amrr_init(&rvp->amrr, vap, IEEE80211_AMRR_MIN_SUCCESS_THRESHOLD, IEEE80211_AMRR_MAX_SUCCESS_THRESHOLD, 500 /* ms */); .Ed .Pp The node is defined as: .Bd -literal -offset indent struct rt2560_node { struct ieee80211_node ni; struct ieee80211_amrr_node amrr; }; .Ed .Pp with initialization done in the driver's .Vt iv_newassoc method: .Bd -literal -offset indent static void rt2560_newassoc(struct ieee80211_node *ni, int isnew) { struct ieee80211vap *vap = ni->ni_vap; ieee80211_amrr_node_init(&RT2560_VAP(vap)->amrr, &RT2560_NODE(ni)->amrr, ni); } .Ed .Pp Once .Nm state is setup, transmit rates are requested by calling .Fn ieee80211_amrr_choose in the transmit path; e.g.: .Bd -literal -offset indent tp = &vap->iv_txparms[ieee80211_chan2mode(ni->ni_chan)]; if (IEEE80211_IS_MULTICAST(wh->i_addr1)) { rate = tp->mcastrate; } else if (m0->m_flags & M_EAPOL) { rate = tp->mgmtrate; } else if (tp->ucastrate != IEEE80211_FIXED_RATE_NONE) { rate = tp->ucastrate; } else { (void) ieee80211_amrr_choose(ni, &RT2560_NODE(ni)->amrr); rate = ni->ni_txrate; } .Ed .Pp Note a rate is chosen only for unicast data frames when a fixed transmit rate is not configured; the other cases are handled with the .Nm net80211 transmit parameters. Note also that .Fn ieee80211_amrr_choose writes the chosen rate in .Vt ni_txrate ; this eliminates copying the value as it is exported to user applications so they can display the current transmit rate in status. .Pp The remaining work a driver must do is feed status back to .Nm when a frame transmit completes using .Fn ieee80211_amrr_tx_complete . Drivers that poll a device to retrieve statistics can use .Fn ieee80211_amrr_tx_update (instead or in addition). .Sh SEE ALSO .Xr ieee80211 9 , .Xr ieee80211_output 9 Index: stable/9/share/man/man9/ieee80211_bmiss.9 =================================================================== --- stable/9/share/man/man9/ieee80211_bmiss.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_bmiss.9 (revision 237216) @@ -1,91 +1,91 @@ .\" .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 4, 2009 .Dt IEEE80211_BMISS 9 .Os .Sh NAME .Nm ieee80211_bmiss .Nd 802.11 beacon miss support .Sh SYNOPSIS .In net80211/ieee80211_var.h .Pp .Ft void .Fn ieee80211_beacon_miss "struct ieee80211com *" .Sh DESCRIPTION The .Nm net80211 software layer provides a support framework for drivers that includes handling beacon miss events in station mode. Drivers can dispatch beacon miss events that are recognized in hardware or .Nm net80211 can detect beacon miss if the driver dispatches received beacon frames through the normal receive path. Software beacon miss support is especially useful when multiple vaps are operating and any hardware beacon miss support is not available (e.g. operating as an access point together with one or more station mode vaps). .Pp Drivers should dispatch beacon miss events recognized in the driver with .Fn ieee80211_beacon_miss . This causes some number of ProbeRequest frames to be sent to the access point to check if the association is still alive. If no response is received and roaming mode is set to .Dv IEEE80211_ROAMING_AUTO -then +then .Nm net80211 -will try to re-associate and if that fails +will try to re-associate and if that fails trigger a scan to look for the access point or another suitable AP. When the .Nm net80211 state machine is being operated manually, e.g. by .Xr wpa_supplicant 8 , then applications are notified of the state change and are responsible for handling the work of scanning for a new access point. The number of beacon miss events (without a ProbeResponse) is user settable with the .Dv IEEE80211_IOC_BMISSTHRESHOLD request. .Pp Software beacon miss detection is enabled per-vap by setting the .Dv IEEE80211_FEXT_SWBMISS flag. Typically this is done when a vap is setup when the .Dv IEEE80211_CLONE_NOBEACONS option is supplied to the clone operation. But drivers may also force this when they know they need help detecting beacon miss. When beacon miss is detected in software the event is dispatched without driver involvement. Note that software beacon miss handling is not limited to station mode; it can be used in any operating mode where beacons from a peer station are received. .Sh SEE ALSO .Xr wpa_supplicant 8 , .Xr ieee80211 9 , .Xr ieee80211_vap 9 Index: stable/9/share/man/man9/ieee80211_input.9 =================================================================== --- stable/9/share/man/man9/ieee80211_input.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_input.9 (revision 237216) @@ -1,116 +1,116 @@ .\" .\" Copyright (c) 2004 Bruce M. Simpson .\" Copyright (c) 2004 Darron Broad .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 4, 2009 .Dt IEEE80211_INPUT 9 .Os .Sh NAME .Nm ieee80211_input .Nd software 802.11 stack input functions .Sh SYNOPSIS .In net80211/ieee80211_var.h .Ft void .Fo ieee80211_input .Fa "struct ieee80211_node *" .Fa "struct mbuf *" .Fa "int rssi" .Fa "int noise" .Fc .Ft void .Fo ieee80211_input_all .Fa "struct ieee80211com *" .Fa "struct mbuf *" .Fa "int rssi" .Fa "int noise" .Fc .Sh DESCRIPTION The .Nm net80211 layer that supports 802.11 device drivers requires that receive processing be single-threaded. Typically this is done using a dedicated driver .Xr taskqueue 9 thread. .Fn ieee80211_input and .Fn ieee80211_input_all process received 802.11 frames and are designed for use in that context; e.g. no driver locks may be held. .Pp The frame passed up in the .Vt mbuf must have the 802.11 protocol header at the front; all device-specific information and/or PLCP must be removed. Any CRC must be stripped from the end of the frame. The 802.11 protocol header should be 32-bit aligned for optimal performance but receive processing does not require it. If the frame holds a payload and that is not aligned to a 32-bit boundary then the payload will be re-aligned so that it is suitable for processing by protocols such as .Xr ip 4 . .Pp If a device (such as .Xr ath 4 ) inserts padding after the 802.11 header to align the payload to a 32-bit boundary the .Dv IEEE80211_C_DATAPAD capability must be set. Otherwise header and payload are assumed contiguous in the mbuf chain. .Pp If a received frame must pass through the A-MPDU receive reorder buffer then the mbuf must be marked with the .Dv M_AMPDU flag. Note that for the moment this is required of all frames received from a station and TID where a Block ACK stream is active, not just A-MPDU aggregates. It is sufficient to check for .Dv IEEE80211_NODE_HT in the .Vt ni_flags of the station's node table entry, any frames that do not require reorder processing will be dispatched with only minimal overhead. .Pp The .Vt rssi parameter is the Receive Signal Strength Indication of the frame measured in 0.5dBm units relative to the noise floor. The .Vt noise parameter is the best approximation of the noise floor in dBm units at the time the frame was received. RSSI and noise are used by the .Nm net80211 layer to make scanning and roaming decisions in station mode and to do auto channel selection for hostap and similar modes. Otherwise the values are made available to user applications -(with the rssi presented as a filtered average over the last ten values +(with the rssi presented as a filtered average over the last ten values and the noise floor the last reported value). .Sh SEE ALSO .Xr ieee80211 9 Index: stable/9/share/man/man9/ieee80211_node.9 =================================================================== --- stable/9/share/man/man9/ieee80211_node.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_node.9 (revision 237216) @@ -1,251 +1,251 @@ .\" .\" Copyright (c) 2004 Bruce M. Simpson .\" Copyright (c) 2004 Darron Broad .\" 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. .\" .\" $FreeBSD$ .\" .Dd April 28, 2010 .Dt IEEE80211_NODE 9 .Os .Sh NAME .Nm ieee80211_node .Nd software 802.11 stack node management functions .Sh SYNOPSIS .In net80211/ieee80211_var.h .\" .Ft struct ieee80211_node * .Fo ieee80211_find_rxnode .Fa "struct ieee80211com *" .Fa "const struct ieee80211_frame_min *" .Fc .\" .Ft struct ieee80211_node * .Fo ieee80211_find_rxnode_withkey .Fa "struct ieee80211com *" .Fa "const struct ieee80211_frame_min *" .Fa "ieee80211_keyix" .Fc .\" .Ft struct ieee80211_node * .Fn ieee80211_ref_node "struct ieee80211_node *" .\" .Ft void .Fn ieee80211_unref_node "struct ieee80211_node *" .\" .Ft void .Fn ieee80211_free_node "struct ieee80211_node *" .\" .Ft void .Fo ieee80211_iterate_nodes .Fa "struct ieee80211_node_table *" .Fa "ieee80211_iter_func *f" .Fa "void *arg" .Fc .\" .Ft void .Fo ieee80211_dump_nodes .Fa "struct ieee80211_node_table *" -.Fc +.Fc .\" .Ft void .Fo ieee80211_dump_node .Fa "struct ieee80211_node *" -.Fc +.Fc .Sh DESCRIPTION The .Nm net80211 layer that supports 802.11 device drivers maintains a database of peer stations called the -.Dq node table +.Dq node table in the .Vt ic_sta entry of the .Vt ieee80211com structure. Station mode vaps create an entry for the access point the station is associated to. AP mode vaps create entries for associated stations. Adhoc and mesh mode vaps create entries for neighbor stations. WDS mode vaps create an entry for the peer station. Stations for all vaps reside in the same table; each node entry has a .Vt ni_vap field that identifies the vap that created it. In some instances an entry is used by multiple vaps (e.g. for dynamic WDS a station associated to an ap vap may also be the peer of a WDS vap). .Pp Node table entries are reference counted. That is, there is a count of all long term references that determines when an entry may be reclaimed. References are held by every in-flight frame sent to a station to ensure the entry is not reclaimed while the frame is queued or otherwise held by a driver. Routines that lookup a table entry return a .Dq held reference (i.e. a pointer to a table entry with the reference count incremented). The .Fn ieee80211_ref_node and .Fn ieee80211_unref_node calls explicitly increment/decrement the reference count of a node, but are rarely used. Instead most callers use .Fn ieee80211_free_node to release a reference and, if the count goes to zero, reclaim the table entry. .Pp The station table and its entries are exposed to drivers in several ways. Each frame transmitted to a station includes a reference to the associated node in the .Vt m_pkthdr.rcvif field. This reference must be reclaimed by the driver when transmit processing is done. For each frame received the driver must lookup the table entry to -use in dispatching the frame +use in dispatching the frame .Dq up the stack . This lookup implicitly obtains a reference to the table entry and the driver must reclaim the reference when frame processing is completed. Otherwise drivers frequently inspect the contents of the .Vt iv_bss node when handling state machine changes as important information is maintained in the data structure. .Pp The node table is opaque to drivers. Entries may be looked up using one of the pre-defined API's or the .Fn ieee80211_iterate_nodes call may be used to iterate through all entries to do per-node processing or implement some non-standard search mechanism. -Note that +Note that .Fn ieee80211_iterate_nodes is single-threaded per-device and the effort processing involved is fairly substantial so it should be used carefully. .Pp Two routines are provided to print the contents of nodes to the console for debugging: .Fn ieee80211_dump_node displays the contents of a single node while .Fn ieee80211_dump_nodes displays the contents of the specified node table. Nodes may also be displayed using .Xr ddb 4 with the .Dq show node directive and the station node table can be displayed with .Dq show statab . .Sh DRIVER PRIVATE STATE Node data structures may be extended by the driver to include driver-private state. This is done by overriding the .Vt ic_node_alloc method used to allocate a node table entry. The driver method must allocate a structure that is an extension of the .Vt ieee80211_node structure. For example the .Xr iwi 4 driver defines a private node structure as: .Bd -literal -offset indent struct iwi_node { struct ieee80211_node in_node; int in_station; }; .Ed .Pp and then provides a private allocation routine that does this: .Bd -literal -offset indent static struct ieee80211_node * iwi_node_alloc(struct ieee80211vap *vap, const uint8_t mac[IEEE80211_ADDR_LEN]) { struct iwi_node *in; in = malloc(sizeof (struct iwi_node), M_80211_NODE, M_NOWAIT | M_ZERO); if (in == NULL) return NULL; in->in_station = -1; return &in->in_node; } .Ed .Pp Note that when reclaiming a node allocated by the driver the .Dq parent method must be called to ensure .Nm net80211 state is reclaimed; for example: .Bd -literal -offset indent static void iwi_node_free(struct ieee80211_node *ni) { struct ieee80211com *ic = ni->ni_ic; struct iwi_softc *sc = ic->ic_ifp->if_softc; struct iwi_node *in = (struct iwi_node *)ni; - + if (in->in_station != -1) free_unr(sc->sc_unr, in->in_station); sc->sc_node_free(ni); /* invoke net80211 free handler */ } .Ed .Pp Beware that care must be taken to avoid holding references that might cause nodes from being reclaimed. .Nm net80211 will reclaim a node when the last reference is reclaimed in its data structures. However if a driver holds additional references then .Nm net80211 will not recognize this and table entries will not be reclaimed. Such references should not be needed if the driver overrides the .Vt ic_node_cleanup and/or .Vt ic_node_free methods. .Sh KEY TABLE SUPPORT Node table lookups are typically done using a hash of the stations' mac address. When receiving frames this is sufficient to find the node table entry for the transmitter. But some devices also identify the sending station in the device state received with each frame and this data can be used to optimize lookups on receive using a companion table called the .Dq keytab . This table records a separate node table reference that can be fetched without any locking using the table index. This logic is handled with the .Fn ieee80211_find_rxnode_withkey call: if a keytab entry is found using the specified index then it is returned directly; otherwise a normal lookup is done and the keytab entry is written using the specified index. If the specified index is .Dv IEEE80211_KEYIX_NONE then a normal lookup is done without a table update. .Sh SEE ALSO .Xr ddb 9 , .Xr ieee80211 9 , .Xr ieee80211_proto 9 Index: stable/9/share/man/man9/ieee80211_output.9 =================================================================== --- stable/9/share/man/man9/ieee80211_output.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_output.9 (revision 237216) @@ -1,194 +1,194 @@ .\" .\" Copyright (c) 2004 Bruce M. Simpson .\" Copyright (c) 2004 Darron Broad .\" 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. .\" .\" $FreeBSD$ .\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $ .\" .Dd March 29, 2010 .Dt IEEE80211_OUTPUT 9 .Os .Sh NAME .Nm ieee80211_output .Nd software 802.11 stack output functions .Sh SYNOPSIS .In net80211/ieee80211_var.h .\" .Ft int .Fn M_WME_GETAC "struct mbuf *" .\" .Ft int .Fn M_SEQNO_GET "struct mbuf *" .\" .Ft struct ieee80211_key * .Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *" .\" .Ft void .Fo ieee80211_process_callback .Fa "struct ieee80211_node *" .Fa "struct mbuf *" .Fa "int" .Fc .Sh DESCRIPTION The .Nm net80211 layer that supports 802.11 device drivers handles most of the work required to transmit frames. Drivers usually receive fully-encapsulated 802.11 frames that have been classified and assigned a transmit priority; all that is left is to do crypto encapsulation, prepare any hardware-specific state, and push the packet out to the device. Outbound frames are either generated by the .Nm net80211 layer (e.g. management frames) or are passed down from upper layers through the .Xr ifnet 9 transmit queue. Data frames passed down for transmit flow through .Nm net80211 which handles aggregation, 802.11 encapsulation, and then dispatches the frames to the driver through it's transmit queue. .Pp There are two control paths by which frames reach a driver for transmit. Data packets are queued to the device's .Vt if_snd queue and the driver's .Vt if_start method is called. Other frames are passed down using the .Vt ic_raw_xmit method without queueing (unless done by the driver). The raw transmit path may include data frames from user applications that inject them through .Xr bpf 4 and NullData frames generated by .Nm net80211 to probe for idle stations (when operating as an access point). .Pp .Nm net80211 handles all state-related bookkeeping and management for the handling of data frames. Data frames are only transmit for a vap in the .Dv IEEE80211_S_RUN state; there is no need, for example, to check for frames sent down when CAC or CSA is active. Similarly, .Nm net80211 handles activities such as background scanning and power save mode, frames will not be sent to a driver unless it is operating on the BSS channel with .Dq full power . .Pp All frames passed to a driver for transmit hold a reference to a node table entry in the .Vt m_pkthdr.rcvif field. The node is associated with the frame destination. Typically it is the receiver's entry but in some situations it may be -a placeholder entry or the +a placeholder entry or the .Dq next hop station (such as in a mesh network). In all cases the reference must be reclaimed with .Fn ieee80211_free_node when the transmit work is completed. -The rule to remember is: +The rule to remember is: .Nm net80211 passes responsibility for the .Vt mbuf and .Dq node reference to the driver with each frame it hands off for transmit. .Sh PACKET CLASSIFICATION All frames passed by .Nm net80211 for transmit are assigned a priority based on any vlan tag assigned to the receiving station and/or any Diffserv setting in an IP or IPv6 header. If both vlan and Diffserv priority are present the higher of the two is used. -If WME/WMM is being used then any ACM policy (in station mode) is +If WME/WMM is being used then any ACM policy (in station mode) is also enforced. The resulting AC is attached to the mbuf and may be read back using the .Fn M_WME_GETAC macro. .Pp PAE/EAPOL frames are tagged with an .Dv M_EAPOL mbuf flag; drivers should transmit them with care, usually by using the transmit rate for management frames. Multicast/broadcast frames are marked with the .Dv M_MCAST mbuf flag. Frames coming out of a station's power save queue and that have more frames immediately following are marked with the .Dv M_MORE_DATA mbuf flag. Such frames will be queued consecutively in the driver's .Vt if_snd queue and drivers should preserve the ordering when passing them to the device. .Sh FRAGMENTED FRAMES The .Nm net80211 layer will fragment data frames according to the setting of .Vt iv_fragthreshold if a driver marks the .Dv IEEE80211_C_TXFRAG capability. Fragmented frames are placed in the devices transmit queue with the fragments chained together with .Vt m_nextpkt . Each frame is marked with the .Dv M_FRAG mbuf flag, and the first and last are marked with .Dv M_FIRSTFRAG and .Dv M_LASTFRAG , respectively. Drivers are expected to process all fragments or none. .Sh TRANSMIT CALLBACKS Frames sent by .Nm net80211 may be tagged with the .Dv M_TXCB mbuf flag to indicate a callback should be done when their transmission completes. The callback is done using .Fn ieee80211_process_callback with the last parameter set to a non-zero value if an error occurred and zero otherwise. -Note +Note .Nm net80211 understands that drivers may be incapable of determining status; a device may not report if an ACK frame is received and/or a device may queue transmit requests in its hardware and only report status on whether the frame was successfully queued. .Sh SEE ALSO .Xr bpf 4 , .Xr ieee80211 9 , .Xr ifnet 9 Index: stable/9/share/man/man9/ieee80211_proto.9 =================================================================== --- stable/9/share/man/man9/ieee80211_proto.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_proto.9 (revision 237216) @@ -1,241 +1,241 @@ .\" .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 4, 2009 .Dt IEEE80211_PROTO 9 .Os .Sh NAME .Nm ieee80211_proto .Nd 802.11 state machine support .Sh SYNOPSIS .In net80211/ieee80211_var.h .Pp .Ft void .Fn ieee80211_start_all "struct ieee80211com *" .Ft void .Fn ieee80211_stop_all "struct ieee80211com *" .Ft void .Fn ieee80211_suspend_all "struct ieee80211com *" .Ft void .Fn ieee80211_resume_all "struct ieee80211com *" .Pp .Dv enum ieee80211_state ; .Ft int .Fn ieee80211_new_state "struct ieee80211vap *" "enum ieee80211_state" "int" .Pp .Ft void .Fn ieee80211_wait_for_parent "struct ieee80211com *" .Sh DESCRIPTION The .Nm net80211 layer that supports 802.11 device drivers uses a state machine to control operation of vaps. These state machines vary according to the vap operating mode. Station mode state machines follow the 802.11 MLME states in the protocol specification. Other state machines are simpler and reflect operational work such as scanning for a BSS or automatically selecting a channel to operate on. When multiple vaps are operational the state machines are used to coordinate operation such as choosing a channel. The state machine mechanism also serves to bind the .Nm net80211 layer to a driver; this is described more below. .Pp The following states are defined for state machines: .Bl -tag -width IEEE80211_S_ASSOC .It Dv IEEE80211_S_INIT Default/initial state. A vap in this state should not hold any dynamic state (e.g. entries for associated stations in the node table). The driver must quiesce the hardware; e.g. there should be no interrupts firing. .It Dv IEEE80211_S_SCAN Scanning for a BSS or choosing a channel to operate on. Note that scanning can also take place in other states (e.g. when background scanning is active); this state is entered when initially bringing a vap to an operational state or after an event such as a beacon miss (in station mode). .It Dv IEEE80211_S_AUTH Authenticating to an access point (in station mode). This state is normally reached from .Dv IEEE80211_S_SCAN after selecting a BSS, but may also be reached from .Dv IEEE80211_S_ASSOC or .Dv IEEE80211_S_RUN if the authentication handshake fails. .It Dv IEEE80211_S_ASSOC Associating to an access point (in station mode). This state is reached from .Dv IEEE80211_S_AUTH after successfully authenticating or from .Dv IEEE80211_S_RUN if a DisAssoc frame is received. .It Dv IEEE80211_S_CAC Doing Channel Availability Check (CAC). This state is entered only when DFS is enabled and the channel selected for operation requires CAC. .It Dv IEEE80211_S_RUN Operational. In this state a vap can transmit data frames, accept requests for stations associating, etc. Beware that data traffic is also gated by whether the associated .Dq port is authorized. When WPA/802.11i/802.1x is operational authorization may happen separately; -e.g. in station mode +e.g. in station mode .Xr wpa_supplicant 8 must complete the handshakes and plumb the necessary keys before a port is authorized. In this state a BSS is operational and associated state is valid and may be used; e.g. .Vt ic_bss and .Vt ic_bsschan are guaranteed to be usable. .It Dv IEEE80211_S_CSA Channel Switch Announcement (CSA) is pending. This state is reached only from .Dv IEEE80211_S_RUN when either a CSA is received from an access point (in station mode) or the local station is preparing to change channel. In this state traffic may be muted depending on the Mute setting in the CSA. .It Dv IEEE80211_S_SLEEP Asleep to save power (in station mode). This state is reached only from .Dv IEEE80211_S_RUN when power save operation is enabled and the local station is deemed sufficiently idle to enter low power mode. .El .Pp Note that states are ordered (as shown above); e.g. a vap must be in the .Dv IEEE80211_S_RUN or .Dq greater before it can transmit frames. Certain .Nm net80211 data are valid only in certain states; e.g. the .Vt iv_bsschan -that specifies the channel for the operating BSS should never be used +that specifies the channel for the operating BSS should never be used except in .Dv IEEE80211_S_RUN or greater. .Sh STATE CHANGES State machine changes are typically handled internal to the .Nm net80211 -layer in response to +layer in response to .Xr ioctl 2 requests, received frames, or external events such as a beacon miss. The .Fn ieee80211_new_state function is used to initiate a state machine change on a vap. The new state and an optional argument are supplied. The request is initially processed to handle coordination of multiple vaps. For example, only one vap at a time can be scanning, if multiple vaps request a change to .Dv IEEE80211_S_SCAN -the first will be permitted to run and the others will be +the first will be permitted to run and the others will be .Em deferred until the scan operation completes at which time the selected channel will be adopted. Similarly .Nm net80211 handles coordination of combinations of vaps such as an AP and station vap where the station may need to roam to follow the AP it is associated to (dragging along the AP vap to the new channel). Another important coordination is the handling of .Dv IEEE80211_S_CAC and .Dv IEEE80211_S_CSA . No more than one vap can ever be actively changing state at a time. In fact .Nm net80211 single-threads the state machine logic in a dedicated .Xr taskqueue 9 thread that is also used to synchronize work such as scanning and beacon miss handling. .Pp After multi-vap scheduling/coordination is done the per-vap .Vt iv_newstate method is called to carry out the state change work. Drivers use this entry to setup private state and then dispatch the call to the .Nm net80211 layer using the previously defined method pointer (in OOP-parlance they call the .Dq super method ). .Pp .Nm net80211 handles two state changes specially. On transition to .Dv IEEE80211_S_RUN -the +the .Dv IFF_DRV_OACTIVE bit on the vap's transmit queue is cleared so traffic can flow. On transition to .Dv IEEE80211_S_INIT -any state in the scan cache associated with the vap is flushed +any state in the scan cache associated with the vap is flushed and any frames pending on the transmit queue are flushed. .Sh DRIVER INTEGRATION Drivers are expected to override the .Vt iv_newstate method to interpose their own code and handle setup work required by state changes. Otherwise drivers must call .Fn ieee80211_start_all in response to being marked up through an .Dv SIOCSIFFLAGS ioctl request and they should use .Fn ieee80211_suspend_all and .Fn ieee80211_resume_all to implement suspend/resume support. .Pp There is also an .Fn ieee80211_stop_all call to force all vaps to an .Dv IEEE80211_S_INIT state but this should not be needed by a driver; control is usually handled by .Nm net80211 or, in the case of card eject or vap destroy, work will be initiated outside the driver. .Sh SEE ALSO .Xr ioctl 2 , .Xr wpa_supplicant 8 , .Xr ieee80211 9 , .Xr ifnet 9 , .Xr taskqueue 9 .Sh HISTORY The state machine concept was part of the original .Nm ieee80211 code base that first appeared in .Nx 1.5 . Index: stable/9/share/man/man9/ieee80211_radiotap.9 =================================================================== --- stable/9/share/man/man9/ieee80211_radiotap.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_radiotap.9 (revision 237216) @@ -1,302 +1,302 @@ .\" .\" Copyright (c) 2004 Bruce M. Simpson , .\" Darron Broad , .\" David Young . .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 4, 2009 .Dt IEEE80211_RADIOTAP 9 .Os .Sh NAME .Nm ieee80211_radiotap .Nd 802.11 device packet capture support .Sh SYNOPSIS .In net80211/ieee80211_var.h .\" .Pp .Ft void .Fo ieee80211_radiotap_attach .Fa "struct ieee80211com *" .Fa "struct ieee80211_radiotap_header *th" .Fa "int tlen" .Fa "uint32_t tx_radiotap" .Fa "struct ieee80211_radiotap_header *rh" .Fa "int rlen" .Fa "uint32_t rx_radiotap" .Fc .\" .Ft int .Fn ieee80211_radiotap_active_vap "struct ieee80211vap *" .\" .Ft int .Fn ieee80211_radiotap_active "struct ieee80211com *" .\" .Ft void .Fn ieee80211_radiotap_tx "struct ieee80211vap *" "struct mbuf *" .Sh DESCRIPTION The .Nm net80211 layer used by 802.11 drivers includes support for a device-independent packet capture format called -.Nm radiotap +.Nm radiotap that is understood by tools such as .Xr tcpdump 1 . This facility is designed for capturing 802.11 traffic, including information that is not part of the normal 802.11 frame structure. .Pp Radiotap was designed to balance the desire for a hardware-independent, extensible capture format against the need to conserve CPU and memory bandwidth on embedded systems. These considerations led to a format consisting of a standard preamble followed by an extensible bitmap indicating the presence of optional capture fields. A .Nm net80211 device driver supporting .Vt radiotap defines two packed structures that it shares with .Nm net80211 . These structures embed an instance of a .Vt ieee80211_radiotap_header structure at the beginning, with subsequent fields in the appropriate order, and macros to set the bits of the .Va it_present bitmap to indicate which fields exist and are filled in by the driver. This information is then supplied through the .Fn ieee80211_radiotap_attach call after a successful .Fn ieee80211_ifattach request. .Pp With radiotap setup, drivers just need to fill in per-packet capture state for frames sent/received and dispatch capture state in the transmit path (since control is not returned to the .Nm net80211 layer before the packet is handed to the device). To minimize overhead this work should be done only when one or more processes are actively capturing data; this is checked with one of .Fn ieee80211_radiotap_active_vap and .Fn ieee80211_radiotap_active . In the transmit path capture work looks like this: .Bd -literal -offset indent if (ieee80211_radiotap_active_vap(vap)) { ... /* record transmit state */ ieee80211_radiotap_tx(vap, m); /* capture transmit event */ } .Ed .Pp While in the receive path capture is handled in .Nm net80211 but state must be captured before dispatching a frame: .Bd -literal -offset indent if (ieee80211_radiotap_active(ic)) { ... /* record receive state */ } \&... ieee80211_input(...); /* packet capture handled in net80211 */ .Ed .Pp .\" The following fields are defined for .Vt radiotap , in the order in which they should appear in the buffer supplied to .Nm net80211 . .Bl -tag -width indent .It Dv IEEE80211_RADIOTAP_TSFT This field contains the unsigned 64-bit value, in microseconds, of the MAC's 802.11 Time Synchronization Function (TSF). In theory, for each received frame, this value is recorded when the first bit of the MPDU arrived at the MAC. In practice, hardware snapshots the TSF otherwise and one cannot assume this data is accurate without driver adjustment. .It Dv IEEE80211_RADIOTAP_FLAGS This field contains a single unsigned 8-bit value, containing one or more of these bit flags: .Bl -tag -width indent .It Dv IEEE80211_RADIOTAP_F_CFP Frame was sent/received during the Contention Free Period (CFP). .It Dv IEEE80211_RADIOTAP_F_SHORTPRE Frame was sent/received with short preamble. .It Dv IEEE80211_RADIOTAP_F_WEP Frame was encrypted. .It Dv IEEE80211_RADIOTAP_F_FRAG Frame was an 802.11 fragment. .It Dv IEEE80211_RADIOTAP_F_FCS Frame contents includes the FCS. .It Dv IEEE80211_RADIOTAP_F_DATAPAD Frame contents potentially has padding between the 802.11 header and the data payload to align the payload to a 32-bit boundary. .It Dv IEEE80211_RADIOTAP_F_BADFCS Frame was received with an invalid FCS. .It Dv IEEE80211_RADIOTAP_F_SHORTGI Frame was sent/received with Short Guard Interval. .El .It Dv IEEE80211_RADIOTAP_RATE This field contains a single unsigned 8-bit value that is the data rate. Legacy rates are in units of 500Kbps. MCS rates (used on 802.11n/HT channels) have the high bit set and the MCS in the low 7 bits. .It Dv IEEE80211_RADIOTAP_CHANNEL This field contains two unsigned 16-bit values. The first value is the center frequency for the channel the frame was sent/received on. The second value is a bitmap containing flags that specify channel properties. .Pp This field is deprecated in favor of .Dv IEEE80211_RADIOTAP_XCHANNEL but may be used to save space in the capture file for legacy devices. .\".It Dv IEEE80211_RADIOTAP_FHSS .\"This field contains two 8-bit values. .\"This field should be present only for frequency-hopping radios. .\"The first byte is the hop set. .\"The second byte is the pattern in use. .It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL This field contains a single signed 8-bit value that indicates the RF signal power at the antenna, in decibels difference from 1mW. .It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE This field contains a single signed 8-bit value that indicates the RF noise power at the antenna, in decibels difference from 1mW. .\".It Dv IEEE80211_RADIOTAP_LOCK_QUALITY .\"This field contains a single unsigned 16-bit value, indicating the .\"quality of the Barker Code lock. .\"No unit is specified for this field. .\"There does not appear to be a standard way of measuring this at this time; .\"this quantity is often referred to as .\".Dq "Signal Quality" .\"in some datasheets. .\".It Dv IEEE80211_RADIOTAP_TX_ATTENUATION .\"This field contains a single unsigned 16-bit value, expressing transmit .\"power as unitless distance from maximum power set at factory calibration. .\"0 indicates maximum transmit power. .\"Monotonically nondecreasing with lower power levels. .\".It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION .\"This field contains a single unsigned 16-bit value, expressing transmit .\"power as decibel distance from maximum power set at factory calibration. .\"0 indicates maximum transmit power. .\"Monotonically nondecreasing with lower power levels. .It Dv IEEE80211_RADIOTAP_DBM_TX_POWER Transmit power expressed as decibels from a 1mW reference. This field is a single signed 8-bit value. This is the absolute power level measured at the antenna port. .It Dv IEEE80211_RADIOTAP_ANTENNA This field contains a single unsigned 8-bit value that specifies which antenna was used to transmit or receive the frame. Antenna numbering is device-specific but typically the primary antenna has the lowest number. On transmit a value of zero may be seen which typically means antenna selection is left to the device. .It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL This field contains a single unsigned 8-bit value that indicates the RF signal power at the antenna, in decibels difference from an arbitrary, fixed reference. .It Dv IEEE80211_RADIOTAP_DB_ANTNOISE This field contains a single unsigned 8-bit value that indicates the RF noise power at the antenna, in decibels difference from an arbitrary, fixed reference. .It Dv IEEE80211_RADIOTAP_XCHANNEL This field contains four values: a 32-bit unsigned bitmap of flags that describe the channel attributes, a 16-bit unsigned frequency in MHz (typically the channel center), an 8-bit unsigned IEEE channel number, and a signed 8-bit value that holds the maximum regulatory transmit power cap in .5 dBm (8 bytes total). Channel flags are defined in: .In net80211/_ieee80211.h (only a subset are found in .In net80211/ieee80211_radiotap.h ). This property supersedes .Dv IEEE80211_RADIOTAP_CHANNEL and is the only way to completely express all channel attributes and the mapping between channel frequency and IEEE channel number. .El .Sh EXAMPLES Radiotap receive definitions for the Intersil Prism driver: .Bd -literal -offset indent #define WI_RX_RADIOTAP_PRESENT \\ ((1 << IEEE80211_RADIOTAP_TSFT) \\ (1 << IEEE80211_RADIOTAP_FLAGS) | \\ (1 << IEEE80211_RADIOTAP_RATE) | \\ (1 << IEEE80211_RADIOTAP_CHANNEL) | \\ (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\ (1 << IEEE80211_RADIOTAP_DB_ANTNOISE)) struct wi_rx_radiotap_header { struct ieee80211_radiotap_header wr_ihdr; uint64_t wr_tsf; uint8_t wr_flags; uint8_t wr_rate; uint16_t wr_chan_freq; uint16_t wr_chan_flags; uint8_t wr_antsignal; uint8_t wr_antnoise; -} __packed; +} __packed; .Ed .Pp and transmit definitions for the Atheros driver: .Bd -literal -offset indent #define ATH_TX_RADIOTAP_PRESENT ( \\ (1 << IEEE80211_RADIOTAP_TSFT) | \\ (1 << IEEE80211_RADIOTAP_FLAGS) | \\ (1 << IEEE80211_RADIOTAP_RATE) | \\ (1 << IEEE80211_RADIOTAP_DBM_TX_POWER) | \\ (1 << IEEE80211_RADIOTAP_ANTENNA) | \\ (1 << IEEE80211_RADIOTAP_XCHANNEL) | \\ 0) struct ath_tx_radiotap_header { struct ieee80211_radiotap_header wt_ihdr; uint64_t wt_tsf; uint8_t wt_flags; uint8_t wt_rate; uint8_t wt_txpower; uint8_t wt_antenna; uint32_t wt_chan_flags; uint16_t wt_chan_freq; uint8_t wt_chan_ieee; int8_t wt_chan_maxpow; } __packed; .Ed .Sh SEE ALSO .Xr tcpdump 1 , .Xr bpf 4 , .Xr ieee80211 9 .Sh HISTORY The .Nm definitions first appeared in .Nx 1.5 . .\" .Sh AUTHORS .An -nosplit The original version of this manual page was written by .An Bruce M. Simpson Aq bms@FreeBSD.org and .An Darron Broad Aq darron@kewl.org . Index: stable/9/share/man/man9/ieee80211_regdomain.9 =================================================================== --- stable/9/share/man/man9/ieee80211_regdomain.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_regdomain.9 (revision 237216) @@ -1,143 +1,143 @@ .\" .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 4, 2009 .Dt IEEE80211_REGDOMAIN 9 .Os .Sh NAME .Nm ieee80211_regdomain .Nd 802.11 regulatory support .Sh SYNOPSIS .In net80211/ieee80211_var.h .In net80211/ieee80211_regdomain.h .Pp .Ft int .Fo ieee80211_init_channels .Fa "struct ieee80211com *" .Fa "const struct ieee80211_regdomain *" .Fa "const uint8_t bands[]" .Fc .\" .Ft void .Fo ieee80211_sort_channels .Fa "struct ieee80211_channel *" .Fa "int nchans" .Fc .\" .Ft "struct ieee80211_appie *" .Fn ieee80211_alloc_countryie "struct ieee80211com *" .Sh DESCRIPTION The .Nm net80211 software layer provides a support framework for drivers that includes comprehensive regulatory support. .Nm net80211 -provides mechanisms that enforce +provides mechanisms that enforce .Em "regulatory policy" by privileged user applications. .Pp Drivers define a device's capabilities and can intercept and control regulatory changes requested through .Nm net80211 . The initial regulatory state, including the channel list, must be filled in by the driver before calling .Fn ieee80211_ifattach . The channel list should reflect the set of channels the device is .Em calibrated for use on. This list may also be requested later through the .Vt ic_getradiocaps method in the .Vt ieee80211com structure. The .Fn ieee80211_init_channels function is provided as a rudimentary fallback for drivers that do not (or cannot) fill in a proper channel list. Default regulatory state is supplied such as the regulatory SKU, ISO country code, location (e.g. indoor, outdoor), and a set of frequency bands the device is capable of operating on. .Nm net80211 populates the channel table in .Vt ic_channels with a default set of channels and capabilities. Note this mechanism should be used with care as any mismatch between the channel list created and the device's capabilities can result in runtime errors (e.g. a request to operate on a channel the device does not support). The SKU and country information are used for generating 802.11h protocol elements and related operation such as for 802.11d; mis-setup by a driver is not fatal, only potentially confusing. .Pp Devices that do not have a fixed/default regulatory state can set the regulatory SKU to .Dv SKU_DEBUG and country code to .Dv CTRY_DEFAULT and leave proper setup to user applications. If default settings are known they can be installed and/or an event can be dispatched to user space using .Fn ieee80211_notify_country -so that +so that .Xr devd 8 will do the appropriate setup work at system boot (or device insertion). .Pp The channel table is sorted to optimize lookups using the .Fn ieee80211_sort_channels routine. This should be done whenever the channel table contents are modified. .Pp The .Fn ieee80211_alloc_countryie function allocates an information element as specified by 802.11h. Because this is expensive to generate it is cached in .Vt ic_countryie and generated only when regulatory state changes. Drivers that call .Fn ieee80211_alloc_countryie directly should not help with this caching; doing so may confuse the .Nm net80211 layer. .Sh DRIVER REGULATORY CONTROL Drivers can control regulatory change requests by overriding the .Vt ic_setregdomain method that checks change requests. While drivers can reject any request that does not meet its requirements it is recommended that one be lenient in what is accepted and, whenever possible, instead of rejecting a request, alter it to be correct. For example, if the transmit power cap for a channel is too high the driver can either reject the request or (better) reduce the cap to be compliant. Requests that include unacceptable channels should cause the request to be rejected as otherwise a mismatch may be created between application state and the state managed by .Nm net80211 . The exact rules by which to operate are still being codified. .Sh SEE ALSO .Xr regdomain 5 , .Xr ifconfig 8 , .Xr ieee80211 9 Index: stable/9/share/man/man9/ieee80211_scan.9 =================================================================== --- stable/9/share/man/man9/ieee80211_scan.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_scan.9 (revision 237216) @@ -1,350 +1,350 @@ .\" .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd March 29, 2010 .Dt IEEE80211_SCAN 9 .Os .Sh NAME .Nm ieee80211_scan .Nd 802.11 scanning support .Sh SYNOPSIS .In net80211/ieee80211_var.h .Pp .Ft int .Fo ieee80211_start_scan .Fa "struct ieee80211vap *" .Fa "int flags" .Fa "u_int duration" .Fa "u_int mindwell" .Fa "u_int maxdwell" .Fa "u_int nssid" .Fa "const struct ieee80211_scan_ssid ssids[]" .Fc .\" .Ft int .Fo ieee80211_check_scan .Fa "struct ieee80211vap *" .Fa "int flags" .Fa "u_int duration" .Fa "u_int mindwell" .Fa "u_int maxdwell" .Fa "u_int nssid" .Fa "const struct ieee80211_scan_ssid ssids[]" .Fc .\" .Ft int .Fn ieee80211_check_scan_current "struct ieee80211vap *" .\" .Ft int .Fn ieee80211_bg_scan "struct ieee80211vap *" "int" .\" .Ft int .Fn ieee80211_cancel_scan "struct ieee80211vap *" .\" .Ft int .Fn ieee80211_cancel_scan_any "struct ieee80211vap *" .\" .Ft int .Fn ieee80211_scan_next "struct ieee80211vap *" .\" .Ft int .Fn ieee80211_scan_done "struct ieee80211vap *" .\" .Ft int .Fn ieee80211_probe_curchan "struct ieee80211vap *" "int" .\" .Ft void .Fo ieee80211_add_scan .Fa "struct ieee80211vap *" .Fa "const struct ieee80211_scanparams *" .Fa "const struct ieee80211_frame *" .Fa "int subtype" .Fa "int rssi" .Fa "int noise" .Fc .\" .Ft void .Fn ieee80211_scan_timeout "struct ieee80211com *" .\" .Ft void .Fo ieee80211_scan_assoc_fail .Fa "struct ieee80211vap *" .Fa "const uint8_t mac[IEEE80211_ADDR_LEN]" .Fa "int reason" .Fc .\" .Ft void .Fn ieee80211_scan_flush "struct ieee80211vap *" .\" .Ft void .Fo ieee80211_scan_iterate .Fa "struct ieee80211vap *" .Fa "ieee80211_scan_iter_func" .Fa "void *" .Fc .\" .Ft void .Fn ieee80211_scan_dump_channels "const struct ieee80211_scan_state *" .\" .Ft void .Fo ieee80211_scanner_register .Fa "enum ieee80211_opmode" .Fa "const struct ieee80211_scanner *" .Fc .\" .Ft void .Fo ieee80211_scanner_unregister .Fa "enum ieee80211_opmode" .Fa "const struct ieee80211_scanner *" .Fc .\" .Ft void .Fn ieee80211_scanner_unregister_all "const struct ieee80211_scanner *" .\" .Ft const struct ieee80211_scanner * .Fn ieee80211_scanner_get "enum ieee80211_opmode" .Sh DESCRIPTION The .Nm net80211 software layer provides an extensible framework for scanning. Scanning is the procedure by which a station locates a BSS to join (in infrastructure and IBSS mode), or a channel to use (when operating as an AP or an IBSS master). Scans are either .Dq active or .Dq passive . An active scan causes one or more ProbeRequest frames to be sent on visiting each channel. A passive request causes each channel in the scan set to be visited but no frames to be transmitted; the station only listens for traffic. Note that active scanning may still need to listen for traffic before sending ProbeRequest frames depending on regulatory constraints. .Pp A scan operation involves constructing a set of channels to inspect (the scan set), visiting each channel and collecting information (e.g. what BSS are present), and then analyzing the results to make decisions such as which BSS to join. This process needs to be as fast as possible so .Nm net80211 does things like intelligently construct scan sets and dwell on a channel only as long as necessary. Scan results are cached and the scan cache is used to avoid scanning when possible and to enable roaming between access points when operating in infrastructure mode. .Pp Scanning is handled by pluggable modules that implement .Em policy per-operating mode. The core scanning support provides an infrastructure to support these modules and exports a common API to the rest of the .Nm net80211 layer. Policy modules decide what channels to visit, what state to record to make decisions, and selects the final station/channel to return as the result of a scan. .Pp Scanning is done synchronously when initially bringing a vap to an operational state and optionally in the background to maintain the scan cache for doing roaming and rogue AP monitoring. Scanning is not tied to the .Nm net80211 state machine that governs vaps except for linkage to the .Dv IEEE80211_S_SCAN state. Only one vap at a time may be scanning; this scheduling policy is handled in .Fn ieee80211_new_state and is transparent to scanning code. .Pp Scanning is controlled by a set of parameters that (potentially) constrains the channel set and any desired SSID's and BSSID's. .Nm net80211 comes with a standard scanner module that works with all available operating modes and supports .Dq background scanning and .Dq roaming operation. .Sh SCANNER MODULES Scanning modules use a registration mechanism to hook into the .Nm net80211 layer. Use .Fn ieee80211_scanner_register to register a scan module for a particular operating mode and .Fn ieee80211_scanner_unregister or .Fn ieee80211_scanner_unregister_all to clear entries (typically on module unload). Only one scanner module can be registered at any time for an operating mode. .Sh DRIVER SUPPORT Scanning operations are usually managed by the .Nm net80211 layer. Drivers must provide .Vt ic_scan_start and .Vt ic_scan_stop methods that are called at the start of a scan and when the work is done; these should handle work such as enabling receive of Beacon and ProbeResponse frames and disable any BSSID matching. The .Vt ic_set_channel method is used to change channels while scanning. .Nm net80211 will generate ProbeRequest frames and transmit them using the .Nm ic_raw_xmit method. Frames received while scanning are dispatched to .Nm net80211 using the normal receive path. Devices that off-load scan work to firmware most easily mesh with .Nm net80211 by operating on a channel-at-a-time basis as this defers control to .Nm net80211's scan machine scheduler. But multi-channel scanning is supported if the driver manually dispatches results using .Fn ieee80211_add_scan routine to enter results into the scan cache. .Sh SCAN REQUESTS Scan requests occur by way of the .Dv IEEE80211_SCAN_REQUEST ioctl or through a change in a vap's state machine that requires scanning. In both cases the scan cache can be checked first and, if it is deemed suitably .Dq warm then it's contents are used without leaving the current channel. To start a scan without checking the cache .Fn ieee80211_start_scan can be called; otherwise .Fn ieee80211_check_scan can be used to first check the scan cache, kicking off a scan if the cache contents are out of date. There is also .Fn ieee80211_check_scan_current which is a shorthand for using previously set scan parameters for checking the scan cache and then scanning. .Pp Background scanning is done using .Fn ieee80211_bg_scan in a co-routine fashion. The first call to this routine will start a background scan that runs for a limited period of time before returning to the BSS channel. Subsequent calls advance through the scan set until all channels are visited. Typically these later calls are timed to allow receipt of frames buffered by an access point for the station. .Pp A scan operation can be canceled using .Fn ieee80211_cancel_scan if it was initiated by the specified vap, or .Fn ieee80211_cancel_scan_any to force termination regardless which vap started it. These requests are mostly used by .Nm net80211 in the transmit path to cancel background scans when frames are to be sent. Drivers should not need to use these calls (or most of the calls described on this page). .Pp The .Fn ieee80211_scan_next and .Fn ieee80211_scan_done routines do explicit iteration through the scan set and should not normally be used by drivers. .Fn ieee80211_probe_curchan handles the work of transmitting ProbeRequest frames when visiting a channel during an active scan. When the channel attributes are marked with .Dv IEEE80211_CHAN_PASSIVE this function will arrange that before any frame is transmitted 802.11 traffic is first received (in order to comply with regulatory constraints). .Pp Min/max dwell time parameters are used to constrain time spent visiting a channel. The maximum dwell time constrains the time spent listening for traffic. The minimum dwell time is used to reduce this time--when it is reached and one or more frames have been received then an immediate channel change will be done. Drivers can override this behaviour through the .Vt iv_scan_mindwell method. .Sh SCAN CACHE MANAGEMENT The scan cache contents are managed by the scan policy module and are opaque outside this module. The .Nm net80211 scan framework defines API's for interacting. The validity of the scan cache contents are controlled by .Vt iv_scanvalid which is exported to user space through the .Dv IEEE80211_SCAN_VALID request. .Pp The cache contents can be explicitly flushed with .Fn ieee80211_scan_flush or by setting the .Dv IEEE80211_SCAN_FLUSH flag when starting a scan operation. .Pp Scan cache entries are created with the .Fn ieee80211_add_scan routine; usually on receipt of Beacon or ProbeResponse frames. Existing entries are typically updated based on the latest information though some information such as RSSI and noise floor readings may be combined to present an average. .Pp -The cache contents is aged through +The cache contents is aged through .Fn ieee80211_scan_timeout calls. Typically these happen together with other station table activity; every .Dv IEEE80211_INACT_WAIT seconds (default 15). .Pp Individual cache entries are marked usable with .Fn ieee80211_scan_assoc_success and faulty with .Fn ieee80211_scan_assoc_fail with the latter taking an argument to identify if there was no response to Authentication/Association requests or if a negative response was received (which might hasten cache eviction or blacklist the entry). .Pp The cache contents can be viewed using the .Fn ieee80211_scan_iterate call. Cache entries are exported in a public format that is exported to user applications through the .Dv IEEE80211_SCAN_RESULTS request. .Sh SEE ALSO .Xr ioctl 2 , .Xr ieee80211 9 , .Xr ieee80211_proto 9 Index: stable/9/share/man/man9/ieee80211_vap.9 =================================================================== --- stable/9/share/man/man9/ieee80211_vap.9 (revision 237215) +++ stable/9/share/man/man9/ieee80211_vap.9 (revision 237216) @@ -1,154 +1,154 @@ .\" .\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 4, 2009 .Dt IEEE8021_VAP 9 .Os .Sh NAME .Nm net80211_vap .Nd 802.11 network layer virtual radio support .Sh SYNOPSIS .In net80211/ieee80211_var.h .Ft int .Fo ieee80211_vap_setup .Fa "struct ieee80211com *" .Fa "struct ieee80211vap *" .Fa "const char name[IFNAMSIZ]" .Fa "int unit" .Fa "int opmode" .Fa "int flags" .Fa "const uint8_t bssid[IEEE80211_ADDR_LEN]" .Fa "const uint8_t macaddr[IEEE80211_ADDR_LEN]" .Fc .\" .Ft int .Fo ieee80211_vap_attach .Fa "struct ieee80211vap *" .Fa "ifm_change_cb_t media_change" .Fa "ifm_stat_cb_t media_stat" .Fc .\" .Ft void .Fn ieee80211_vap_detach "struct ieee80211vap *" .Sh DESCRIPTION The .Nm net80211 software layer provides a support framework for drivers that includes a virtual radio API that is exported to users through network interfaces (aka vaps) that are cloned from the underlying device. These interfaces have an operating mode (station, adhoc, hostap, wds, monitor, etc.) that is fixed for the lifetime of the interface. Devices that can support multiple concurrent interfaces allow multiple vaps to be cloned. .Pp The virtual radio interface defined by the .Nm net80211 layer means that drivers must be structured to follow specific rules. Drivers that support only a single interface at any time must still follow these rules. .Pp The virtual radio architecture splits state between a single per-device .Vt ieee80211com structure and one or more .Vt ieee80211vap structures. Vaps are created with the .Dv SIOCIFCREATE2 request. This results in a call into the driver's .Vt ic_vap_create method where the driver can decide if the request should be accepted. .Pp The vap creation process is done in three steps. First the driver allocates the data structure with .Xr malloc 9 . This data structure must have an .Vt ieee80211vap structure at the front but is usually extended with driver-private state. Next the vap is setup with a call to .Fn ieee80211_vap_setup . -This request initializes +This request initializes .Nm net80211 state but does not activate the interface. The driver can then override methods setup by .Nm net80211 and setup driver resources before finally calling .Fn ieee80211_vap_attach to complete the process. Both these calls must be done without holding any driver locks as work may require the process block/sleep. .Pp A vap is deleted when an .Dv SIOCIFDESTROY ioctl request is made or when the device detaches (causing all associated vaps to automatically be deleted). -Delete requests cause the +Delete requests cause the .Vt ic_vap_delete method to be called. Drivers must quiesce the device before calling .Fn ieee80211_vap_detach to deactivate the vap and isolate it from activities such as requests from user applications. The driver can then reclaim resources held by the vap and re-enable device operation. The exact procedure for quiescing a device is unspecified but typically it involves blocking interrupts and stopping transmit and receive processing. .Sh MULTI-VAP OPERATION Drivers are responsible for deciding if multiple vaps can be created and how to manage them. Whether or not multiple concurrent vaps can be supported depends on a device's capabilities. For example, multiple hostap vaps can usually be supported but many devices do not support assigning each vap a unique BSSID. If a device supports hostap operation it can usually support concurrent station mode vaps but possibly with limitations such as losing support for hardware beacon miss support. Devices that are capable of hostap operation and can send and receive 4-address frames should be able to support WDS vaps together with an ap vap. But in contrast some devices cannot support WDS vaps without at least one ap vap (this however can be finessed by forcing the ap vap to not transmit beacon frames). All devices should support the creation of any number of monitor mode vaps concurrent with other vaps but it is the responsibility of the driver to allow this. .Pp An important consequence of supporting multiple concurrent vaps is that a driver's .Vt iv_newstate method must be written to handle being called for each vap. Where necessary, drivers must track private state for all vaps and not just the one whose state is being changed (e.g. for handling beacon timers the driver may need to know if all vaps that beacon are stopped before stopping the hardware timers). .Sh SEE ALSO .Xr ieee80211 9 , .Xr ifnet 9 , .Xr malloc 9 Index: stable/9/share/man/man9/kproc.9 =================================================================== --- stable/9/share/man/man9/kproc.9 (revision 237215) +++ stable/9/share/man/man9/kproc.9 (revision 237216) @@ -1,395 +1,395 @@ .\" Copyright (c) 2000-2001 .\" The Regents of the University of California. All rights reserved. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 October 19, 2007 .Dt KPROC 9 .Os .Sh NAME .Nm kproc_start , .Nm kproc_shutdown , .Nm kproc_create , .Nm kproc_exit , .Nm kproc_resume , .Nm kproc_suspend , .Nm kproc_suspend_check .Nd "kernel processes" .Sh SYNOPSIS .In sys/kthread.h .Ft void .Fn kproc_start "const void *udata" .Ft void .Fn kproc_shutdown "void *arg" "int howto" .Ft int .Fo kproc_create .Fa "void (*func)(void *)" "void *arg" "struct proc **newpp" .Fa "int flags" "int pages" .Fa "const char *fmt" ... .Fc .Ft void .Fn kproc_exit "int ecode" .Ft int .Fn kproc_resume "struct proc *p" .Ft int .Fn kproc_suspend "struct proc *p" "int timo" .Ft void .Fn kproc_suspend_check "struct proc *p" .Ft int .Fo kproc_kthread_add .Fa "void (*func)(void *)" "void *arg" .Fa "struct proc **procptr" "struct thread **tdptr" .Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." .Fc .Sh DESCRIPTION In .Fx 8.0 , the .Fn kthread* 9 family of functions was renamed to be the .Fn kproc* 9 family of functions, as they were misnamed and actually produced kernel processes. A new family of .Em different .Fn kthread_* 9 functions was added to produce .Em real -kernel -.Em threads . +kernel +.Em threads . See the .Xr kthread 9 man page for more information on those calls. Also note that the .Fn kproc_kthread_add 9 function appears in both pages as its functionality is split. .Pp The function .Fn kproc_start is used to start .Dq internal daemons such as .Nm bufdaemon , pagedaemon , vmdaemon , and the .Nm syncer and is intended to be called from .Xr SYSINIT 9 . The .Fa udata argument is actually a pointer to a .Vt "struct kproc_desc" which describes the kernel process that should be created: .Bd -literal -offset indent struct kproc_desc { char *arg0; void (*func)(void); struct proc **global_procpp; }; .Ed .Pp The structure members are used by .Fn kproc_start as follows: .Bl -tag -width ".Va global_procpp" -offset indent .It Va arg0 String to be used for the name of the process. This string will be copied into the .Va p_comm member of the new process' .Vt "struct proc" . .It Va func The main function for this kernel process to run. .It Va global_procpp A pointer to a .Vt "struct proc" pointer that should be updated to point to the newly created process' process structure. If this variable is .Dv NULL , then it is ignored. .El .Pp The .Fn kproc_create function is used to create a kernel process. The new process shares its address space with process 0, the .Nm swapper process, and runs in kernel mode only. The .Fa func argument specifies the function that the process should execute. The .Fa arg argument is an arbitrary pointer that is passed in as the only argument to .Fa func when it is called by the new process. The .Fa newpp pointer points to a .Vt "struct proc" pointer that is to be updated to point to the newly created process. If this argument is .Dv NULL , then it is ignored. The .Fa flags argument specifies a set of flags as described in .Xr rfork 2 . The .Fa pages argument specifies the size of the new kernel process's stack in pages. If 0 is used, the default kernel stack size is allocated. The rest of the arguments form a .Xr printf 9 argument list that is used to build the name of the new process and is stored in the .Va p_comm member of the new process's .Vt "struct proc" . .Pp The .Fn kproc_exit function is used to terminate kernel processes. It should be called by the main function of the kernel process rather than letting the main function return to its caller. The .Fa ecode argument specifies the exit status of the process. While exiting, the function .Xr exit1 9 will initiate a call to .Xr wakeup 9 on the process handle. .Pp The .Fn kproc_resume , .Fn kproc_suspend , and .Fn kproc_suspend_check functions are used to suspend and resume a kernel process. During the main loop of its execution, a kernel process that wishes to allow itself to be suspended should call .Fn kproc_suspend_check passing in .Va curproc as the only argument. This function checks to see if the kernel process has been asked to suspend. If it has, it will .Xr tsleep 9 until it is told to resume. Once it has been told to resume it will return allowing execution of the kernel process to continue. The other two functions are used to notify a kernel process of a suspend or resume request. The .Fa p argument points to the .Vt "struct proc" of the kernel process to suspend or resume. For .Fn kproc_suspend , the .Fa timo argument specifies a timeout to wait for the kernel process to acknowledge the suspend request and suspend itself. .Pp The .Fn kproc_shutdown function is meant to be registered as a shutdown event for kernel processes that need to be suspended voluntarily during system shutdown so as not to interfere with system shutdown activities. The actual suspension of the kernel process is done with .Fn kproc_suspend . .Pp The .Fn kproc_kthread_add -function is much like the +function is much like the .Fn kproc_create function above except that if the kproc already exists, then only a new thread (see .Xr kthread 9 ) is created on the existing process. The .Fa func argument specifies the function that the process should execute. The .Fa arg argument is an arbitrary pointer that is passed in as the only argument to .Fa func when it is called by the new process. The .Fa procptr pointer points to a .Vt "struct proc" pointer that is the location to be updated with the new proc pointer if a new process is created, or if not .Dv NULL , must contain the process pointer for the already existing process. If this argument points to .Dv NULL , then a new process is created and the field updated. If not NULL, the .Fa tdptr pointer points to a .Vt "struct thread" pointer that is the location to be updated with the new thread pointer. The .Fa flags argument specifies a set of flags as described in .Xr rfork 2 . The .Fa pages argument specifies the size of the new kernel thread's stack in pages. If 0 is used, the default kernel stack size is allocated. The procname argument is the name the new process should be given if it needs to be created. It is .Em NOT a printf style format specifier but a simple string. The rest of the arguments form a .Xr printf 9 argument list that is used to build the name of the new thread and is stored in the .Va td_name member of the new thread's .Vt "struct thread" . .Sh RETURN VALUES The .Fn kproc_create , .Fn kproc_resume , and .Fn kproc_suspend functions return zero on success and non-zero on failure. .Sh EXAMPLES This example demonstrates the use of a .Vt "struct kproc_desc" and the functions .Fn kproc_start , .Fn kproc_shutdown , and .Fn kproc_suspend_check to run the .Nm bufdaemon process. .Bd -literal -offset indent static struct proc *bufdaemonproc; static struct kproc_desc buf_kp = { "bufdaemon", buf_daemon, &bufdaemonproc }; SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start, &buf_kp) static void buf_daemon() { ... /* * This process needs to be suspended prior to shutdown sync. */ EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown, bufdaemonproc, SHUTDOWN_PRI_LAST); ... for (;;) { kproc_suspend_check(bufdaemonproc); ... } } .Ed .Sh ERRORS The .Fn kproc_resume and .Fn kproc_suspend functions will fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa p argument does not reference a kernel process. .El .Pp The .Fn kproc_create function will fail 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 . .It Bq Er EINVAL The .Dv RFCFDG flag was specified in the .Fa flags parameter. .El .Sh SEE ALSO .Xr rfork 2 , .Xr exit1 9 , .Xr kthread 9 , .Xr SYSINIT 9 , .Xr wakeup 9 .Sh HISTORY The .Fn kproc_start function first appeared in .Fx 2.2 . The .Fn kproc_shutdown , .Fn kproc_create , .Fn kproc_exit , .Fn kproc_resume , .Fn kproc_suspend , and .Fn kproc_suspend_check functions were introduced in .Fx 4.0 . Prior to .Fx 5.0 , the .Fn kproc_shutdown , .Fn kproc_resume , .Fn kproc_suspend , and .Fn kproc_suspend_check functions were named .Fn shutdown_kproc , .Fn resume_kproc , .Fn shutdown_kproc , and .Fn kproc_suspend_loop , respectively. Originally they had the names .Fn kthread_* but were changed to .Fn kproc_* when real kthreads became available. Index: stable/9/share/man/man9/kthread.9 =================================================================== --- stable/9/share/man/man9/kthread.9 (revision 237215) +++ stable/9/share/man/man9/kthread.9 (revision 237216) @@ -1,349 +1,349 @@ .\" Copyright (c) 2000-2001 .\" The Regents of the University of California. All rights reserved. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 January 24, 2010 .Dt KTHREAD 9 .Os .Sh NAME .Nm kthread_start , .Nm kthread_shutdown , .Nm kthread_add , .Nm kthread_exit , .Nm kthread_resume , .Nm kthread_suspend , .Nm kthread_suspend_check .Nd "kernel threads" .Sh SYNOPSIS .In sys/kthread.h .Ft void .Fn kthread_start "const void *udata" .Ft void .Fn kthread_shutdown "void *arg" "int howto" .Ft void .Fn kthread_exit "void" .Ft int .Fn kthread_resume "struct thread *td" .Ft int .Fn kthread_suspend "struct thread *td" "int timo" .Ft void .Fn kthread_suspend_check "void" .In sys/unistd.h .Ft int .Fo kthread_add .Fa "void (*func)(void *)" "void *arg" "struct proc *procp" .Fa "struct thread **newtdpp" "int flags" "int pages" .Fa "const char *fmt" ... .Fc .Ft int .Fo kproc_kthread_add .Fa "void (*func)(void *)" "void *arg" .Fa "struct proc **procptr" "struct thread **tdptr" .Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." .Fc .Sh DESCRIPTION In .Fx 8.0 , the older family of .Fn kthread_* 9 functions was renamed to be the .Fn kproc_* 9 family of functions, as they were previously misnamed and actually produced kernel processes. This new family of .Fn kthread_* 9 functions was added to produce .Em real kernel threads. See the .Xr kproc 9 man page for more information on the renamed calls. -Also note that the +Also note that the .Fn kproc_kthread_add 9 function appears in both pages as its functionality is split. .Pp The function .Fn kthread_start is used to start .Dq internal daemons such as .Nm bufdaemon , pagedaemon , vmdaemon , and the .Nm syncer and is intended to be called from .Xr SYSINIT 9 . The .Fa udata argument is actually a pointer to a .Vt "struct kthread_desc" which describes the kernel thread that should be created: .Bd -literal -offset indent struct kthread_desc { char *arg0; void (*func)(void); struct thread **global_threadpp; }; .Ed .Pp The structure members are used by .Fn kthread_start as follows: .Bl -tag -width ".Va global_threadpp" -offset indent .It Va arg0 String to be used for the name of the thread. This string will be copied into the .Va td_name member of the new threads' .Vt "struct thread" . .It Va func The main function for this kernel thread to run. .It Va global_threadpp A pointer to a .Vt "struct thread" pointer that should be updated to point to the newly created thread's .Vt thread structure. If this variable is .Dv NULL , then it is ignored. The thread will be a subthread of .Va proc0 (PID 0). .El .Pp The .Fn kthread_add function is used to create a kernel thread. The new thread runs in kernel mode only. It is added to the process specified by the .Fa procp argument, or if that is .Dv NULL , to .Va proc0 . The .Fa func argument specifies the function that the thread should execute. The .Fa arg argument is an arbitrary pointer that is passed in as the only argument to .Fa func when it is called by the new thread. The .Fa newtdpp pointer points to a .Vt "struct thread" pointer that is to be updated to point to the newly created thread. If this argument is .Dv NULL , then it is ignored. The .Fa flags argument may be set to .Dv RFSTOPPED to leave the thread in a stopped state. The caller must call .Fn sched_add to start the thread. The .Fa pages argument specifies the size of the new kernel thread's stack in pages. If 0 is used, the default kernel stack size is allocated. The rest of the arguments form a .Xr printf 9 argument list that is used to build the name of the new thread and is stored in the .Va td_name member of the new thread's .Vt "struct thread" . .Pp The .Fn kproc_kthread_add -function is much like the +function is much like the .Fn kthread_add function above except that if the kproc does not already -exist, it is created. -This function is better documented in the +exist, it is created. +This function is better documented in the .Xr kproc 9 manual page. .Pp The .Fn kthread_exit function is used to terminate kernel threads. It should be called by the main function of the kernel thread rather than letting the main function return to its caller. .\" XXX "int ecode" argument isn't documented. .Pp The .Fn kthread_resume , .Fn kthread_suspend , and .Fn kthread_suspend_check functions are used to suspend and resume a kernel thread. During the main loop of its execution, a kernel thread that wishes to allow itself to be suspended should call .Fn kthread_suspend_check in order to check if the it has been asked to suspend. If it has, it will .Xr msleep 9 until it is told to resume. Once it has been told to resume it will return allowing execution of the kernel thread to continue. The other two functions are used to notify a kernel thread of a suspend or resume request. The .Fa td argument points to the .Vt "struct thread" of the kernel thread to suspend or resume. For .Fn kthread_suspend , the .Fa timo argument specifies a timeout to wait for the kernel thread to acknowledge the suspend request and suspend itself. .Pp The .Fn kthread_shutdown function is meant to be registered as a shutdown event for kernel threads that need to be suspended voluntarily during system shutdown so as not to interfere with system shutdown activities. The actual suspension of the kernel thread is done with .Fn kthread_suspend . .Sh RETURN VALUES The .Fn kthread_add , .Fn kthread_resume , and .Fn kthread_suspend functions return zero on success and non-zero on failure. .Sh EXAMPLES This example demonstrates the use of a .Vt "struct kthread_desc" and the functions .Fn kthread_start , .Fn kthread_shutdown , and .Fn kthread_suspend_check to run the .Nm bufdaemon process. .Bd -literal -offset indent static struct thread *bufdaemonthread; static struct kthread_desc buf_kp = { "bufdaemon", buf_daemon, &bufdaemonthread }; SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start, &buf_kp) static void buf_daemon() { ... /* * This process needs to be suspended prior to shutdown sync. */ EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown, bufdaemonthread, SHUTDOWN_PRI_LAST); ... for (;;) { kthread_suspend_check(bufdaemonthread); ... } } .Ed .Sh ERRORS The .Fn kthread_resume and .Fn kthread_suspend functions will fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa td argument does not reference a kernel thread. .El .Pp The .Fn kthread_add function will fail if: .Bl -tag -width Er .It Bq Er ENOMEM Memory for a thread's stack could not be allocated. .El .Sh SEE ALSO .Xr kproc 9 , .Xr SYSINIT 9 , .Xr wakeup 9 .Sh HISTORY The .Fn kthread_start function first appeared in .Fx 2.2 where it created a whole process. It was converted to create threads in .Fx 8.0 . The .Fn kthread_shutdown , .Fn kthread_exit , .Fn kthread_resume , .Fn kthread_suspend , and .Fn kthread_suspend_check functions were introduced in .Fx 4.0 and were converted to threads in .Fx 8.0 . The .Fn kthread_create call was renamed to .Fn kthread_add in .Fx 8.0 . The old functionality of creating a kernel process was renamed to .Xr kproc_create 9 . Prior to .Fx 5.0 , the .Fn kthread_shutdown , .Fn kthread_resume , .Fn kthread_suspend , and .Fn kthread_suspend_check functions were named .Fn shutdown_kproc , .Fn resume_kproc , .Fn shutdown_kproc , and .Fn kproc_suspend_loop , respectively. Index: stable/9/share/man/man9/lock.9 =================================================================== --- stable/9/share/man/man9/lock.9 (revision 237215) +++ stable/9/share/man/man9/lock.9 (revision 237216) @@ -1,390 +1,390 @@ .\" .\" Copyright (C) 2002 Chad David . 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(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 16, 2009 .Dt LOCK 9 .Os .Sh NAME .Nm lockinit , .Nm lockdestroy , .Nm lockmgr , .Nm lockmgr_args , .Nm lockmgr_args_rw , .Nm lockmgr_disown , .Nm lockmgr_printinfo , .Nm lockmgr_recursed , .Nm lockmgr_rw , .Nm lockmgr_waiters , .Nm lockstatus , .Nm lockmgr_assert .Nd "lockmgr family of functions" .Sh SYNOPSIS .In sys/types.h .In sys/lock.h .In sys/lockmgr.h .Ft void .Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags" .Ft void .Fn lockdestroy "struct lock *lkp" .Ft int .Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *ilk" .Ft int .Fn lockmgr_args "struct lock *lkp" "u_int flags" "struct mtx *ilk" "const char *wmesg" "int prio" "int timo" .Ft int .Fn lockmgr_args_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" "const char *wmesg" "int prio" "int timo" .Ft void .Fn lockmgr_disown "struct lock *lkp" .Ft void .Fn lockmgr_printinfo "struct lock *lkp" .Ft int .Fn lockmgr_recursed "struct lock *lkp" .Ft int .Fn lockmgr_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" .Ft int .Fn lockmgr_waiters "struct lock *lkp" .Ft int .Fn lockstatus "struct lock *lkp" .Pp .Cd "options INVARIANTS" .Cd "options INVARIANT_SUPPORT" .Ft void .Fn lockmgr_assert "struct lock *lkp" "int what" .Sh DESCRIPTION The .Fn lockinit function is used to initialize a lock. It must be called before any operation can be performed on a lock. Its arguments are: .Bl -tag -width ".Fa wmesg" .It Fa lkp A pointer to the lock to initialize. .It Fa prio The priority passed to .Xr sleep 9 . .It Fa wmesg The lock message. This is used for both debugging output and .Xr sleep 9 . .It Fa timo The timeout value passed to .Xr sleep 9 . .It Fa flags The flags the lock is to be initialized with: .Bl -tag -width ".Dv LK_CANRECURSE" .It Dv LK_ADAPTIVE Enable adaptive spinning for this lock if the kernel is compiled with the ADAPTIVE_LOCKMGRS option. .It Dv LK_CANRECURSE Allow recursive exclusive locks. .It Dv LK_NOPROFILE Disable lock profiling for this lock. .It Dv LK_NOSHARE Allow exclusive locks only. .It Dv LK_NOWITNESS Instruct .Xr witness 4 to ignore this lock. .It Dv LK_NODUP .Xr witness 4 should log messages about duplicate locks being acquired. .It Dv LK_QUIET Disable .Xr ktr 4 logging for this lock. .It Dv LK_TIMELOCK Use .Fa timo during a sleep; otherwise, 0 is used. .El .El .Pp The .Fn lockdestroy function is used to destroy a lock, and while it is called in a number of places in the kernel, it currently does nothing. .Pp The .Fn lockmgr and .Fn lockmgr_rw functions handle general locking functionality within the kernel, including support for shared and exclusive locks, and recursion. .Fn lockmgr and .Fn lockmgr_rw are also able to upgrade and downgrade locks. .Pp Their arguments are: .Bl -tag -width ".Fa flags" .It Fa lkp A pointer to the lock to manipulate. .It Fa flags Flags indicating what action is to be taken. .Bl -tag -width ".Dv LK_CANRECURSE" .It Dv LK_SHARED Acquire a shared lock. If an exclusive lock is currently held, it will be downgraded. .It Dv LK_EXCLUSIVE Acquire an exclusive lock. If an exclusive lock is already held, and .Dv LK_CANRECURSE is not set, the system will .Xr panic 9 . .It Dv LK_DOWNGRADE Downgrade exclusive lock to a shared lock. Downgrading a shared lock is not permitted. If an exclusive lock has been recursed, all references will be downgraded. .It Dv LK_UPGRADE Upgrade a shared lock to an exclusive lock. If this call fails, the shared lock is lost. During the upgrade, the shared lock could be temporarily dropped. Attempts to upgrade an exclusive lock will cause a .Xr panic 9 . .It Dv LK_RELEASE Release the lock. Releasing a lock that is not held can cause a .Xr panic 9 . .It Dv LK_DRAIN Wait for all activity on the lock to end, then mark it decommissioned. This is used before freeing a lock that is part of a piece of memory that is about to be freed. (As documented in .In sys/lockmgr.h . ) .It Dv LK_SLEEPFAIL Fail if operation has slept. .It Dv LK_NOWAIT Do not allow the call to sleep. This can be used to test the lock. .It Dv LK_NOWITNESS Skip the .Xr witness 4 checks for this instance. .It Dv LK_CANRECURSE Allow recursion on an exclusive lock. For every lock there must be a release. .It Dv LK_INTERLOCK Unlock the interlock (which should be locked already). .El .It Fa ilk An interlock mutex for controlling group access to the lock. If .Dv LK_INTERLOCK is specified, .Fn lockmgr and .Fn lockmgr_rw assume .Fa ilk is currently owned and not recursed, and will return it unlocked. See .Xr mtx_assert 9 . .El .Pp The .Fn lockmgr_args and .Fn lockmgr_args_rw function work like .Fn lockmgr and .Fn lockmgr_rw but accepting a .Fa wmesg , .Fa timo and .Fa prio on a per-instance basis. The specified values will override the default ones, but this can still be used passing, respectively, .Dv LK_WMESG_DEFAULT , .Dv LK_PRIO_DEFAULT and .Dv LK_TIMO_DEFAULT . .Pp The .Fn lockmgr_disown function switches the owner from the current thread to be .Dv LK_KERNPROC , if the lock is already held. .Pp The .Fn lockmgr_printinfo function prints debugging information about the lock. It is used primarily by .Xr VOP_PRINT 9 functions. .Pp The .Fn lockmgr_recursed function returns true if the lock is recursed, 0 otherwise. .Pp The .Fn lockmgr_waiters function returns true if the lock has waiters, 0 otherwise. .Pp The .Fn lockstatus function returns the status of the lock in relation to the current thread. .Pp When compiled with .Cd "options INVARIANTS" and .Cd "options INVARIANT_SUPPORT" , the .Fn lockmgr_assert function tests .Fa lkp for the assertions specified in .Fa what , and panics if they are not met. One of the following assertions must be specified: .Bl -tag -width ".Dv KA_UNLOCKED" .It Dv KA_LOCKED Assert that the current thread has either a shared or an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_SLOCKED Assert that the current thread has a shared lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_XLOCKED Assert that the current thread has an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_UNLOCKED Assert that the current thread has no lock on the .Vt lkp lock pointed to by the first argument. .El .Pp In addition, one of the following optional assertions can be used with either an .Dv KA_LOCKED , .Dv KA_SLOCKED , or .Dv KA_XLOCKED assertion: .Bl -tag -width ".Dv KA_NOTRECURSED" .It Dv KA_RECURSED Assert that the current thread has a recursed lock on .Fa lkp . .It Dv KA_NOTRECURSED Assert that the current thread does not have a recursed lock on .Fa lkp . .El .Pp .Sh RETURN VALUES The .Fn lockmgr and .Fn lockmgr_rw functions return 0 on success and non-zero on failure. .Pp The .Fn lockstatus function returns: .Bl -tag -width ".Dv LK_EXCLUSIVE" .It Dv LK_EXCLUSIVE An exclusive lock is held by the current thread. .It Dv LK_EXCLOTHER An exclusive lock is held by someone other than the current thread. .It Dv LK_SHARED A shared lock is held. .It Li 0 The lock is not held by anyone. .El .Sh ERRORS .Fn lockmgr and .Fn lockmgr_rw fail if: .Bl -tag -width Er .It Bq Er EBUSY .Dv LK_FORCEUPGRADE was requested and another thread had already requested a lock upgrade. .It Bq Er EBUSY .Dv LK_NOWAIT was set, and a sleep would have been required. .It Bq Er ENOLCK .Dv LK_SLEEPFAIL was set and .Fn lockmgr or .Fn lockmgr_rw did sleep. .It Bq Er EINTR .Dv PCATCH was set in the lock priority, and a signal was delivered during a sleep. Note the .Er ERESTART error below. .It Bq Er ERESTART .Dv PCATCH was set in the lock priority, a signal was delivered during a sleep, and the system call is to be restarted. .It Bq Er EWOULDBLOCK a non-zero timeout was given, and the timeout expired. .El .Sh LOCKS If .Dv LK_INTERLOCK is passed in the .Fa flags argument to .Fn lockmgr or .Fn lockmgr_rw , the .Fa ilk must be held prior to calling -.Fn lockmgr +.Fn lockmgr or .Fn lockmgr_rw , and will be returned unlocked. .Pp Upgrade attempts that fail result in the loss of the lock that is currently held. Also, it is invalid to upgrade an exclusive lock, and a .Xr panic 9 will be the result of trying. .Sh SEE ALSO .Xr condvar 9 , .Xr locking 9 , .Xr mutex 9 , .Xr rwlock 9 , .Xr sleep 9 , .Xr sx 9 , .Xr mtx_assert 9 , .Xr panic 9 , .Xr VOP_PRINT 9 .Sh AUTHORS This manual page was written by .An Chad David Aq davidc@acns.ab.ca . Index: stable/9/share/man/man9/locking.9 =================================================================== --- stable/9/share/man/man9/locking.9 (revision 237215) +++ stable/9/share/man/man9/locking.9 (revision 237216) @@ -1,367 +1,367 @@ .\" Copyright (c) 2007 Julian Elischer (julian - freebsd org ) .\" 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. .\" .\" $FreeBSD$ .\" .Dd May 25, 2012 .Dt LOCKING 9 .Os .Sh NAME .Nm locking .Nd kernel synchronization primitives .Sh DESCRIPTION The .Em FreeBSD kernel is written to run across multiple CPUs and as such requires several different synchronization primitives to allow the developers to safely access and manipulate the many data types required. .Ss Mutexes Mutexes (also called "sleep mutexes") are the most commonly used synchronization primitive in the kernel. Thread acquires (locks) a mutex before accessing data shared with other threads (including interrupt threads), and releases (unlocks) it afterwards. If the mutex cannot be acquired, the thread requesting it will sleep. Mutexes fully support priority propagation. .Pp See .Xr mutex 9 for details. .Ss Spin mutexes Spin mutexes are variation of basic mutexes; the main difference between the two is that spin mutexes never sleep - instead, they spin, waiting for the thread holding the lock, which runs on another CPU, to release it. Differently from ordinary mutex, spin mutexes disable interrupts when acquired. Since disabling interrupts is expensive, they are also generally slower. Spin mutexes should be used only when necessary, e.g. to protect data shared with interrupt filter code (see .Xr bus_setup_intr 9 for details). .Ss Pool mutexes With most synchronization primitives, such as mutexes, programmer must provide a piece of allocated memory to hold the primitive. For example, a mutex may be embedded inside the structure it protects. Pool mutex is a variant of mutex without this requirement - to lock or unlock a pool mutex, one uses address of the structure being protected with it, not the mutex itself. Pool mutexes are seldom used. .Pp See .Xr mtx_pool 9 for details. .Ss Reader/writer locks Reader/writer locks allow shared access to protected data by multiple threads, or exclusive access by a single thread. The threads with shared access are known as .Em readers since they should only read the protected data. A thread with exclusive access is known as a .Em writer since it may modify protected data. .Pp Reader/writer locks can be treated as mutexes (see above and .Xr mutex 9 ) with shared/exclusive semantics. -More specifically, regular mutexes can be +More specifically, regular mutexes can be considered to be equivalent to a write-lock on an .Em rw_lock. The .Em rw_lock locks have priority propagation like mutexes, but priority can be propagated only to an exclusive holder. This limitation comes from the fact that shared owners are anonymous. Another important property is that shared holders of .Em rw_lock can recurse, but exclusive locks are not allowed to recurse. -This ability should not be used lightly and +This ability should not be used lightly and .Em may go away. .Pp See .Xr rwlock 9 for details. .Ss Read-mostly locks Mostly reader locks are similar to .Em reader/writer locks but optimized for very infrequent write locking. .Em Read-mostly locks implement full priority propagation by tracking shared owners using a caller-supplied .Em tracker data structure. .Pp See .Xr rmlock 9 for details. .Ss Shared/exclusive locks Shared/exclusive locks are similar to reader/writer locks; the main difference between them is that shared/exclusive locks may be held during unbounded sleep (and may thus perform an unbounded sleep). They are inherently less efficient than mutexes, reader/writer locks and read-mostly locks. They don't support priority propagation. They should be considered to be closely related to .Xr sleep 9 . -In fact it could in some cases be +In fact it could in some cases be considered a conditional sleep. .Pp See .Xr sx 9 for details. .Ss Counting semaphores Counting semaphores provide a mechanism for synchronizing access to a pool of resources. Unlike mutexes, semaphores do not have the concept of an owner, so they can be useful in situations where one thread needs to acquire a resource, and another thread needs to release it. They are largely deprecated. .Pp See .Xr sema 9 for details. .Ss Condition variables Condition variables are used in conjunction with mutexes to wait for conditions to occur. A thread must hold the mutex before calling the .Fn cv_wait* , functions. When a thread waits on a condition, the mutex is atomically released before the thread is blocked, then reacquired before the function call returns. .Pp See .Xr condvar 9 for details. .Ss Giant Giant is an instance of a mutex, with some special characteristics: .Bl -enum .It It is recursive. .It Drivers and filesystems can request that Giant be locked around them by not marking themselves MPSAFE. Note that infrastructure to do this is slowly going away as non-MPSAFE drivers either became properly locked or disappear. .It Giant must be locked first before other locks. .It It is OK to hold Giant while performing unbounded sleep; in such case, Giant will be dropped before sleeping and picked up after wakeup. .It There are places in the kernel that drop Giant and pick it back up again. Sleep locks will do this before sleeping. Parts of the network or VM code may do this as well, depending on the setting of a sysctl. This means that you cannot count on Giant keeping other code from running if your code sleeps, even if you want it to. .El .Ss Sleep/wakeup The functions .Fn tsleep , .Fn msleep , .Fn msleep_spin , .Fn pause , .Fn wakeup , and .Fn wakeup_one handle event-based thread blocking. If a thread must wait for an external event, it is put to sleep by .Fn tsleep , .Fn msleep , .Fn msleep_spin , or .Fn pause . Threads may also wait using one of the locking primitive sleep routines .Xr mtx_sleep 9 , .Xr rw_sleep 9 , or .Xr sx_sleep 9 . .Pp The parameter .Fa chan is an arbitrary address that uniquely identifies the event on which the thread is being put to sleep. All threads sleeping on a single .Fa chan are woken up later by .Fn wakeup , often called from inside an interrupt routine, to indicate that the resource the thread was blocking on is available now. .Pp Several of the sleep functions including .Fn msleep , .Fn msleep_spin , and the locking primitive sleep routines specify an additional lock parameter. The lock will be released before sleeping and reacquired before the sleep routine returns. If .Fa priority includes the .Dv PDROP flag, then the lock will not be reacquired before returning. The lock is used to ensure that a condition can be checked atomically, and that the current thread can be suspended without missing a change to the condition, or an associated wakeup. In addition, all of the sleep routines will fully drop the .Va Giant mutex (even if recursed) while the thread is suspended and will reacquire the .Va Giant mutex before the function returns. .Pp See .Xr sleep 9 for details. .Pp .Ss Lockmanager locks Shared/exclusive locks, used mostly in .Xr VFS 9 , in particular as a .Xr vnode 9 lock. They have features other lock types don't have, such as sleep timeout, writer starvation avoidance, draining, and interlock mutex, but this makes them complicated to implement; for this reason, they are deprecated. .Pp See .Xr lock 9 for details. .Sh INTERACTIONS The primitives interact and have a number of rules regarding how they can and can not be combined. Many of these rules are checked using the .Xr witness 4 code. .Ss Bounded vs. unbounded sleep The following primitives perform bounded sleep: mutexes, pool mutexes, reader/writer locks and read-mostly locks. .Pp The following primitives block (perform unbounded sleep): shared/exclusive locks, counting semaphores, condition variables, sleep/wakeup and lockmanager locks. .Pp It is an error to do any operation that could result in any kind of sleep while holding spin mutex. .Pp As a general rule, it is an error to do any operation that could result in unbounded sleep while holding any primitive from the 'bounded sleep' group. For example, it is an error to try to acquire shared/exclusive lock while holding mutex, or to try to allocate memory with M_WAITOK while holding read-write lock. .Pp As a special case, it is possible to call .Fn sleep or .Fn mtx_sleep while holding a single mutex. It will atomically drop that mutex and reacquire it as part of waking up. This is often a bad idea because it generally relies on the programmer having good knowledge of all of the call graph above the place where .Fn mtx_sleep is being called and assumptions the calling code has made. Because the lock gets dropped during sleep, one must re-test all the assumptions that were made before, all the way up the call graph to the place where the lock was acquired. .Pp It is an error to do any operation that could result in any kind of sleep when running inside an interrupt filter. .Pp It is an error to do any operation that could result in unbounded sleep when running inside an interrupt thread. .Ss Interaction table The following table shows what you can and can not do while holding one of the synchronization primitives discussed: .Bl -column ".Ic xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent .It Xo .Em "You have: You want:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep .Xc .It spin mtx Ta \&ok-1 Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-3 .It mutex Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&ok Ta \&no-3 .It sx Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok Ta \&ok Ta \&ok-4 .It rwlock Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&ok Ta \&no-3 .It rmlock Ta \&ok Ta \&ok Ta \&no-5 Ta \&ok Ta \&ok-2 Ta \&no-5 .El .Pp .Em *1 Recursion is defined per lock. Lock order is important. .Pp .Em *2 Readers can recurse though writers can not. Lock order is important. .Pp .Em *3 There are calls that atomically release this primitive when going to sleep and reacquire it on wakeup (e.g. .Fn mtx_sleep , .Fn rw_sleep and .Fn msleep_spin ) . .Pp .Em *4 Though one can sleep holding an sx lock, one can also use .Fn sx_sleep which will atomically release this primitive when going to sleep and reacquire it on wakeup. .Pp .Em *5 .Em Read-mostly locks can be initialized to support sleeping while holding a write lock. See .Xr rmlock 9 for details. .Ss Context mode table The next table shows what can be used in different contexts. At this time this is a rather easy to remember table. .Bl -column ".Ic Xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent .It Xo .Em "Context:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep .Xc -.It interrupt filter: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no -.It interrupt thread: Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok Ta \&no -.It callout: Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&no Ta \&no -.It syscall: Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok +.It interrupt filter: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no +.It interrupt thread: Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok Ta \&no +.It callout: Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&no Ta \&no +.It syscall: Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok .El .Sh SEE ALSO .Xr witness 4 , .Xr condvar 9 , .Xr lock 9 , .Xr mtx_pool 9 , .Xr mutex 9 , .Xr rmlock 9 , .Xr rwlock 9 , .Xr sema 9 , .Xr sleep 9 , .Xr sx 9 , .Xr BUS_SETUP_INTR 9 , .Xr LOCK_PROFILING 9 .Sh HISTORY These functions appeared in .Bsx 4.1 through .Fx 7.0 . .Sh BUGS There are too many locking primitives to choose from. Index: stable/9/share/man/man9/malloc.9 =================================================================== --- stable/9/share/man/man9/malloc.9 (revision 237215) +++ stable/9/share/man/man9/malloc.9 (revision 237216) @@ -1,283 +1,286 @@ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" 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 NETBSD FOUNDATION, INC. 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. .\" .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ .\" $FreeBSD$ .\" -.Dd October 23, 2008 +.Dd January 28, 2012 .Dt MALLOC 9 .Os .Sh NAME .Nm malloc , .Nm free , .Nm realloc , .Nm reallocf , .Nm MALLOC_DEFINE , .Nm MALLOC_DECLARE .Nd kernel memory management routines .Sh SYNOPSIS .In sys/types.h .In sys/malloc.h .Ft void * .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" .Ft void .Fn free "void *addr" "struct malloc_type *type" .Ft void * .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" .Ft void * .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" .Fn MALLOC_DECLARE type .In sys/param.h .In sys/malloc.h .In sys/kernel.h .Fn MALLOC_DEFINE type shortdesc longdesc .Sh DESCRIPTION The .Fn malloc function allocates uninitialized memory in kernel address space for an object whose size is specified by .Fa size . .Pp The .Fn free function releases memory at address .Fa addr that was previously allocated by .Fn malloc for re-use. The memory is not zeroed. If .Fa addr is .Dv NULL , then .Fn free does nothing. .Pp The .Fn realloc function changes the size of the previously allocated memory referenced by .Fa addr to .Fa size bytes. The contents of the memory are unchanged up to the lesser of the new and old sizes. Note that the returned value may differ from .Fa addr . If the requested memory cannot be allocated, .Dv NULL is returned and the memory referenced by .Fa addr is valid and unchanged. If .Fa addr is .Dv NULL , the .Fn realloc function behaves identically to .Fn malloc for the specified size. .Pp The .Fn reallocf function is identical to .Fn realloc except that it will free the passed pointer when the requested memory cannot be allocated. .Pp Unlike its standard C library counterpart .Pq Xr malloc 3 , the kernel version takes two more arguments. The .Fa flags argument further qualifies .Fn malloc Ns 's operational characteristics as follows: .Bl -tag -width indent .It Dv M_ZERO Causes the allocated memory to be set to all zeros. +.It Dv M_NODUMP +For allocations greater than page size, causes the allocated +memory to be excluded from kernel core dumps. .It Dv M_NOWAIT Causes .Fn malloc , .Fn realloc , and .Fn reallocf to return .Dv NULL if the request cannot be immediately fulfilled due to resource shortage. Note that .Dv M_NOWAIT is required when running in an interrupt context. .It Dv M_WAITOK Indicates that it is OK to wait for resources. If the request cannot be immediately fulfilled, the current process is put to sleep to wait for resources to be released by other processes. The .Fn malloc , .Fn realloc , and .Fn reallocf functions cannot return .Dv NULL if .Dv M_WAITOK is specified. .It Dv M_USE_RESERVE Indicates that the system can dig into its reserve in order to obtain the requested memory. This option used to be called .Dv M_KERNEL but has been renamed to something more obvious. This option has been deprecated and is slowly being removed from the kernel, and so should not be used with any new programming. .El .Pp Exactly one of either .Dv M_WAITOK or .Dv M_NOWAIT must be specified. .Pp The .Fa type argument is used to perform statistics on memory usage, and for basic sanity checks. It can be used to identify multiple allocations. The statistics can be examined by .Sq vmstat -m . .Pp A .Fa type is defined using .Vt "struct malloc_type" via the .Fn MALLOC_DECLARE and .Fn MALLOC_DEFINE macros. .Bd -literal -offset indent /* sys/something/foo_extern.h */ MALLOC_DECLARE(M_FOOBUF); /* sys/something/foo_main.c */ MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); /* sys/something/foo_subr.c */ \&... buf = malloc(sizeof *buf, M_FOOBUF, M_NOWAIT); .Ed .Pp In order to use .Fn MALLOC_DEFINE , one must include .In sys/param.h (instead of .In sys/types.h ) and .In sys/kernel.h . .Sh IMPLEMENTATION NOTES The memory allocator allocates memory in chunks that have size a power of two for requests up to the size of a page of memory. For larger requests, one or more pages is allocated. While it should not be relied upon, this information may be useful for optimizing the efficiency of memory use. .Pp Programmers should be careful not to confuse the malloc flags .Dv M_NOWAIT and .Dv M_WAITOK with the .Xr mbuf 9 flags .Dv M_DONTWAIT and .Dv M_WAIT . .Sh CONTEXT .Fn malloc , .Fn realloc and .Fn reallocf may not be called from fast interrupts handlers. When called from threaded interrupts, .Fa flags must contain .Dv M_NOWAIT . .Pp .Fn malloc , .Fn realloc and .Fn reallocf may sleep when called with .Dv M_WAITOK . .Fn free never sleeps. .Pp Any calls to .Fn malloc (even with .Dv M_NOWAIT ) or .Fn free when holding a .Xr vnode 9 interlock, will cause a LOR (Lock Order Reversal) due to the intertwining of VM Objects and Vnodes. .Sh RETURN VALUES The .Fn malloc , .Fn realloc , and .Fn reallocf functions return a kernel virtual address that is suitably aligned for storage of any type of object, or .Dv NULL if the request could not be satisfied (implying that .Dv M_NOWAIT was set). .Sh DIAGNOSTICS A kernel compiled with the .Dv INVARIANTS configuration option attempts to detect memory corruption caused by such things as writing outside the allocated area and imbalanced calls to the .Fn malloc and .Fn free functions. Failing consistency checks will cause a panic or a system console message. .Sh SEE ALSO .Xr vmstat 8 , .Xr contigmalloc 9 , .Xr memguard 9 , .Xr vnode 9 Index: stable/9/share/man/man9/mi_switch.9 =================================================================== --- stable/9/share/man/man9/mi_switch.9 (revision 237215) +++ stable/9/share/man/man9/mi_switch.9 (revision 237216) @@ -1,158 +1,158 @@ .\" $NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" 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 NETBSD FOUNDATION, INC. 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. .\" .\" $FreeBSD$ .\" .Dd November 24, 1996 .Dt MI_SWITCH 9 .Os .Sh NAME .Nm mi_switch , .Nm cpu_switch , .Nm cpu_throw .Nd switch to another thread context .Sh SYNOPSIS .In sys/param.h .In sys/proc.h .Ft void .Fn mi_switch "void" .Ft void .Fn cpu_switch "void" .Ft void .Fn cpu_throw "void" .Sh DESCRIPTION The .Fn mi_switch function implements the machine independent prelude to a thread context switch. It is called from only a few distinguished places in the kernel code as a result of the principle of non-preemptable kernel mode execution. The various major uses of .Nm can be enumerated as follows: .Bl -enum -offset indent .It From within a function such as .Xr cv_wait 9 , .Xr mtx_lock , or -.Xr tsleep 9 +.Xr tsleep 9 when the current thread voluntarily relinquishes the CPU to wait for some resource or lock to become available. .It After handling a trap (e.g.\& a system call, device interrupt) when the kernel prepares a return to user-mode execution. This case is typically handled by machine dependent trap-handling code after detection of a change in the signal disposition of the current process, or when a higher priority thread might be available to run. The latter event is communicated by the machine independent scheduling routines by calling the machine defined .Fn need_resched . .It In the signal handling code (see .Xr issignal 9 ) if a signal is delivered that causes a process to stop. .It When a thread dies in .Xr thread_exit 9 and control of the processor can be passed to the next runnable thread. .It In .Xr thread_suspend_check 9 where a thread needs to stop execution due to the suspension state of the process as a whole. .El .Pp .Fn mi_switch records the amount of time the current thread has been running in the process structures and checks this value against the CPU time limits allocated to the process (see .Xr getrlimit 2 ) . Exceeding the soft limit results in a .Dv SIGXCPU signal to be posted to the process, while exceeding the hard limit will cause a .Dv SIGKILL . .Pp If the thread is still in the .Dv TDS_RUNNING state, .Fn mi_switch will put it back onto the run queue, assuming that it will want to run again soon. If it is in one of the other states and KSE threading is enabled, the associated .Em KSE will be made available to any higher priority threads from the same group, to allow them to be scheduled next. .Pp After these administrative tasks are done, .Fn mi_switch hands over control to the machine dependent routine .Fn cpu_switch , which will perform the actual thread context switch. .Pp .Fn cpu_switch first saves the context of the current thread. Next, it calls .Fn choosethread to determine which thread to run next. Finally, it reads in the saved context of the new thread and starts to execute the new thread. .Pp .Fn cpu_throw is similar to .Fn cpu_switch except that it does not save the context of the old thread. This function is useful when the kernel does not have an old thread context to save, such as when CPUs other than the boot CPU perform their first task switch, or when the kernel does not care about the state of the old thread, such as in .Fn thread_exit when the kernel terminates the current thread and switches into a new thread. .Pp To protect the .Xr runqueue 9 , all of these functions must be called with the .Va sched_lock mutex held. .Sh SEE ALSO .Xr cv_wait 9 , .Xr issignal 9 , .Xr mutex 9 , .Xr runqueue 9 , .Xr tsleep 9 , .Xr wakeup 9 Index: stable/9/share/man/man9/osd.9 =================================================================== --- stable/9/share/man/man9/osd.9 (revision 237215) +++ stable/9/share/man/man9/osd.9 (revision 237216) @@ -1,390 +1,390 @@ .\" .\" Copyright (c) 2010 Lawrence Stewart .\" 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, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 5, 2011 .Dt OSD 9 .Os .Sh NAME .Nm osd , .Nm osd_register , .Nm osd_deregister , .Nm osd_set , .Nm osd_get , .Nm osd_del , .Nm osd_call , .Nm osd_exit .Nd Object Specific Data .Sh SYNOPSIS .In sys/osd.h .Ft typedef void .Fn "\*(lp*osd_destructor_t\*(rp" "void *value" .Ft typedef int .Fn "\*(lp*osd_method_t\*(rp" "void *obj" "void *data" .Ft int .Fo osd_register .Fa "u_int type" .Fa "osd_destructor_t destructor" .Fa "osd_method_t *methods" .Fc .Ft void .Fo osd_deregister .Fa "u_int type" .Fa "u_int slot" .Fc .Ft int .Fo osd_set .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fa "void *value" .Fc .Ft void * .Fo osd_get .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fc .Ft void .Fo osd_del .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fc .Ft int .Fo osd_call .Fa "u_int type" .Fa "u_int method" .Fa "void *obj" .Fa "void *data" .Fc .Ft void .Fo osd_exit .Fa "u_int type" .Fa "struct osd *osd" .Fc .Sh DESCRIPTION The .Nm framework provides a mechanism to dynamically associate arbitrary data at run-time with any kernel data structure which has been suitably modified for use with .Nm . The one-off modification required involves embedding a .Vt "struct osd" inside the kernel data structure. .Pp An additional benefit is that after the initial change to a structure is made, all subsequent use of .Nm with the structure involves no changes to the structure's layout. By extension, if the data structure is part of the ABI, .Nm provides a way of extending the structure in an ABI preserving manner. .Pp The details of the embedded .Vt "struct osd" are not relevant to consumers of the .Nm framework and should not be manipulated directly. .Pp Data associated with a structure is referenced by the .Nm framework using a type/slot identifier pair. Types are statically defined in .In sys/osd.h and provide a high-level grouping for slots to be registered under. Slot identifiers are dynamically assigned by the framework when a data type is registered using .Fn osd_register and remains valid until a corresponding call to .Fn osd_deregister . .Ss Functions The .Fn osd_register -function registers a type/slot identifier pair with the +function registers a type/slot identifier pair with the .Nm framework for use with a new data type. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier should be allocated under. The .Fa destructor argument specifies an optional osd_destructor_t function pointer that will be called for objects of the type being registered which are later destroyed by the .Fn osd_del function. NULL may be passed if no destructor is required. The .Fa methods argument specifies an optional array of osd_method_t function pointers which can be later invoked by the .Fn osd_call function. NULL may be passed if no methods are required. The .Fa methods argument is currently only useful with the OSD_JAIL type identifier. .Pp The .Fn osd_deregister function deregisters a previously registered type/slot identifier pair. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa slot argument specifies the slot identifier which is being deregistered and should be the value that was returned by .Fn osd_register when the data type was registered. .Pp The .Fn osd_set function associates a data object pointer with a kernel data structure's .Vt struct osd member. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd which will have the .Fa value pointer associated with it. The .Fa slot argument specifies the slot identifier to assign the .Fa value pointer to. The .Fa value argument points to a data object to associate with .Fa osd . .Pp The .Fn osd_get function returns the data pointer associated with a kernel data structure's .Vt struct osd member from the specified type/slot identifier pair. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to retrieve the data pointer from. The .Fa slot argument specifies the slot identifier to retrieve the data pointer from. .Pp The .Fn osd_del function removes the data pointer associated with a kernel data structure's .Vt struct osd member from the specified type/slot identifier pair. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to remove the data pointer from. The .Fa slot argument specifies the slot identifier to remove the data pointer from. If an osd_destructor_t function pointer was specified at registration time, the destructor function will be called and passed the data pointer for the type/slot identifier pair which is being deleted. .Pp The .Fn osd_call function calls the specified osd_method_t function pointer for all currently registered slots of a given type on the specified .Fa obj and .Fa data pointers. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h to call the method for. The .Fa method argument specifies the index into the osd_method_t array that was passed to .Fn osd_register . The .Fa obj and .Fa data arguments are passed to the method function pointer of each slot. .Pp The .Fn osd_exit function removes all data object pointers from all currently registered slots for a given type for the specified kernel data structure's .Vt struct osd member. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h to remove data pointers from. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to remove all data object pointers for all currently registered slots from. .Sh IMPLEMENTATION NOTES .Nm uses a two dimensional matrix (array of arrays) as the data structure to manage the external data associated with a kernel data structure's .Vt struct osd member. The type identifier is used as the index into the outer array, and the slot identifier is used as the index into the inner array. To set or retrieve a data pointer for a given type/slot identifier pair, .Fn osd_set and .Fn osd_get perform the equivalent of array[type][slot], which is both constant time and fast. .Pp If .Fn osd_set is called on a .Vt struct osd for the first time, the array for storing data pointers is dynamically allocated using .Xr malloc 9 with M_NOWAIT to a size appropriate for the slot identifier being set. If a subsequent call to .Fn osd_set attempts to set a slot identifier which is numerically larger than the slot used in the previous .Fn osd_set call, .Xr realloc 9 is used to grow the array to the appropriate size such that the slot identifier can be used. To maximise the efficiency of any code which calls .Fn osd_set sequentially on a number of different slot identifiers (e.g. during an initialisation phase) one should loop through the slot identifiers in descending order from highest to lowest. This will result in only a single .Xr malloc 9 call to create an array of the largest slot size and all subsequent calls to .Fn osd_set will proceed without any .Xr realloc 9 calls. .Pp The .Nm API is geared towards slot identifiers storing pointers to the same underlying data structure type for a given .Nm type identifier. This is not a requirement, and .Xr khelp 9 for example stores completely different data types in slots under the OSD_KHELP type identifier. .Ss Locking .Nm internally uses a mix of .Xr mutex 9 , .Xr rmlock 9 and .Xr sx 9 locks to protect its internal data structures and state. .Pp Responsibility for synchronising access to a kernel data structure's .Vt struct osd member is left to the subsystem that uses the data structure and calls the .Nm API. .Pp .Fn osd_get only acquires an .Xr rmlock in read mode, therefore making it safe to use in the majority of contexts within the kernel including most fast paths. .Sh RETURN VALUES .Fn osd_register returns the slot identifier for the newly registered data type. .Pp .Fn osd_set returns zero on success or ENOMEM if the specified type/slot identifier pair triggered an internal .Xr realloc 9 which failed. .Pp .Fn osd_get returns the data pointer for the specified type/slot identifier pair, or NULL if the slot has not been initialised yet. .Pp .Fn osd_call returns zero if no method is run or the method for each slot runs successfully. If a method for a slot returns non-zero, .Fn osd_call terminates prematurely and returns the method's error to the caller. .Sh SEE ALSO .Xr khelp 9 .Sh HISTORY The Object Specific Data (OSD) facility first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . .Pp This manual page was written by .An Lawrence Stewart Aq lstewart@FreeBSD.org . Index: stable/9/share/man/man9/rmlock.9 =================================================================== --- stable/9/share/man/man9/rmlock.9 (revision 237215) +++ stable/9/share/man/man9/rmlock.9 (revision 237216) @@ -1,256 +1,256 @@ .\" Copyright (c) 2007 Stephan Uphoff .\" Copyright (c) 2006 Gleb Smirnoff .\" 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. .\" .\" $FreeBSD$ .\" .\" Based on rwlock.9 man page .Dd November 10, 2007 .Dt RMLOCK 9 .Os .Sh NAME .Nm rmlock , .Nm rm_init , .Nm rm_init_flags , .Nm rm_destroy , .Nm rm_rlock , .Nm rm_try_rlock , .Nm rm_wlock , .Nm rm_runlock , .Nm rm_wunlock , .Nm rm_wowned , .Nm RM_SYSINIT .Nd kernel reader/writer lock optimized for mostly read access patterns .Sh SYNOPSIS .In sys/param.h .In sys/lock.h .In sys/rmlock.h .Ft void .Fn rm_init "struct rmlock *rm" "const char *name" .Ft void .Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" .Ft void .Fn rm_destroy "struct rmlock *rm" .Ft void .Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" .Ft int .Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" .Ft void .Fn rm_wlock "struct rmlock *rm" .Ft void .Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" .Ft void .Fn rm_wunlock "struct rmlock *rm" .Ft int .Fn rm_wowned "struct rmlock *rm" .In sys/kernel.h .Fn RM_SYSINIT "name" "struct rmlock *rm" "const char *desc" "int opts" .Sh DESCRIPTION Mostly reader locks allow shared access to protected data by multiple threads, or exclusive access by a single thread. The threads with shared access are known as .Em readers since they only read the protected data. A thread with exclusive access is known as a .Em writer since it can modify protected data. .Pp Read mostly locks are designed to be efficient for locks almost exclusively used as reader locks and as such should be used for protecting data that rarely changes. Acquiring an exclusive lock after the lock had been locked for shared access -is an expensive operation. +is an expensive operation. .Pp Although reader/writer locks look very similar to .Xr sx 9 locks, their usage pattern is different. Reader/writer locks can be treated as mutexes (see .Xr mutex 9 ) with shared/exclusive semantics unless initialized with .Dv RM_SLEEPABLE . Unlike .Xr sx 9 , an .Nm can be locked while holding a non-spin mutex, and an .Nm cannot be held while sleeping, again unless initialized with .Dv RM_SLEEPABLE . The .Nm locks have full priority propagation like mutexes. The .Va rm_priotracker structure argument supplied in .Fn rm_rlock and .Fn rm_runlock is used to keep track of the read owner(s). Another important property is that shared holders of .Nm can recurse if the lock has been initialized with the .Dv LO_RECURSABLE option, however exclusive locks are not allowed to recurse. .Ss Macros and Functions .Bl -tag -width indent .It Fn rm_init "struct rmlock *rm" "const char *name" Initialize structure located at .Fa rm as mostly reader lock, described by .Fa name . The name description is used solely for debugging purposes. This function must be called before any other operations on the lock. .It Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" Initialize the rm lock just like the .Fn rm_init function, but specifying a set of optional flags to alter the behaviour of .Fa rm , through the .Fa opts argument. It contains one or more of the following flags: .Bl -tag -width ".Dv RM_NOWITNESS" .It Dv RM_NOWITNESS Instruct .Xr witness 4 to ignore this lock. .It Dv RM_RECURSE Allow threads to recursively acquire exclusive locks for .Fa rm . .It Dv RM_SLEEPABLE Allow writers to sleep while holding the lock. Readers must not sleep while holding the lock and can avoid to sleep on taking the lock by using .Fn rm_try_rlock instead of .Fn rm_rlock . .El .It Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" Lock .Fa rm as a reader. Using .Fa tracker to track read owners of a lock for priority propagation. This data structure is only used internally by .Nm and must persist until .Fn rm_runlock has been called. This data structure can be allocated on the stack since rmlocks cannot be held while sleeping. If any thread holds this lock exclusively, the current thread blocks, and its priority is propagated to the exclusive holder. If the lock was initialized with the .Dv LO_RECURSABLE option the .Fn rm_rlock function can be called when the thread has already acquired reader access on .Fa rm . This is called .Dq "recursing on a lock" . .It Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" Try to lock .Fa rm as a reader. .Fn rm_try_rlock will return 0 if the lock cannot be acquired immediately; otherwise the lock will be acquired and a non-zero value will be returned. Note that .Fn rm_try_rlock may fail even while the lock is not currently held by a writer. .It Fn rm_wlock "struct rmlock *rm" Lock .Fa rm as a writer. If there are any shared owners of the lock, the current thread blocks. The .Fn rm_wlock function cannot be called recursively. .It Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" This function releases a shared lock previously acquired by .Fn rm_rlock . The .Fa tracker -argument must match the -.Fa tracker -argument used for acquiring the shared lock +argument must match the +.Fa tracker +argument used for acquiring the shared lock .It Fn rm_wunlock "struct rmlock *rm" This function releases an exclusive lock previously acquired by .Fn rm_wlock . .It Fn rm_destroy "struct rmlock *rm" This functions destroys a lock previously initialized with .Fn rm_init . The .Fa rm lock must be unlocked. .It Fn rm_wowned "struct rmlock *rm" This function returns a non-zero value if the current thread owns an exclusive lock on .Fa rm . .El .Sh SEE ALSO .Xr locking 9 , .Xr mutex 9 , .Xr panic 9 , .Xr rwlock 9 , .Xr sema 9 , .Xr sx 9 .Sh HISTORY These functions appeared in .Fx 7.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An "Stephan Uphoff" . This manual page was written by .An "Gleb Smirnoff" for rwlock and modified to reflect rmlock by .An "Stephan Uphoff" . .Sh BUGS The .Nm implementation is currently not optimized for single processor systems. .Pp .Fn rm_try_rlock can fail transiently even when there is no writer, while another reader updates the state on the local CPU. .Pp The .Nm implementation uses a single per CPU list shared by all rmlocks in the system. If rmlocks become popular, hashing to multiple per CPU queues may -be needed to speed up the writer lock process. +be needed to speed up the writer lock process. .Pp The .Nm can currently not be used as a lock argument for condition variable wait functions. Index: stable/9/share/man/man9/shm_map.9 =================================================================== --- stable/9/share/man/man9/shm_map.9 (revision 237215) +++ stable/9/share/man/man9/shm_map.9 (revision 237216) @@ -1,186 +1,186 @@ .\" .\" Copyright (c) 2011 Advanced Computing Technologies LLC .\" Written by: John H. Baldwin .\" 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. .\" .\" $FreeBSD$ .\" .Dd December 14, 2011 .Dt SHM_MAP 9 .Os .Sh NAME .Nm shm_map , shm_unmap .Nd "map shared memory objects into the kernel's address space" .Sh SYNOPSIS .In sys/types.h .In sys/mman.h .Ft int .Fn shm_map "struct file *fp" "size_t size" "off_t offset" "void **memp" .Ft int .Fn shm_unmap "struct file *fp" "void *mem" "size_t size" .Sh DESCRIPTION The .Fn shm_map and .Fn shm_unmap functions provide an API for mapping shared memory objects into the kernel. Shared memory objects are created by .Xr shm_open 2 . These objects can then be passed into the kernel via file descriptors. .Pp A shared memory object cannot be shrunk while it is mapped into the kernel. This is to avoid invalidating any pages that may be wired into the kernel's address space. Shared memory objects can still be grown while mapped into the kernel. .Pp To simplify the accounting needed to enforce the above requirement, callers of this API are required to unmap the entire region mapped by .Fn shm_map when calling .Fn shm_unmap . Unmapping only a portion of the region is not permitted. .Pp The .Fn shm_map function locates the shared memory object associated with the open file .Fa fp . It maps the region of that object described by .Fa offset and .Fa size into the kernel's address space. If it succeeds, .Fa *memp will be set to the start of the mapping. All pages for the range will be wired into memory upon successful return. .Pp The .Fn shm_unmap function unmaps a region previously mapped by .Fn shm_map . The .Fa mem argument should match the value previously returned in .Fa *memp , and the .Fa size argument should match the value passed to .Fn shm_map . .Pp Note that .Fn shm_map will not hold an extra reference on the open file .Fa fp for the lifetime of the mapping. Instead, the calling code is required to do this if it wishes to use .Fn shm_unmap on the region in the future. .Sh RETURN VALUES The .Fn shm_map and .Fn shm_unmap functions return zero on success or an error on failure. .Sh EXAMPLES The following function accepts a file descriptor for a shared memory object. It maps the first sixteen kilobytes of the object into the kernel, performs some work on that address, and then unmaps the address before returning. .Bd -literal -offset indent int shm_example(int fd) { struct file *fp; void *mem; int error; error = fget(curthread, fd, CAP_MMAP, &fp); if (error) return (error); error = shm_map(fp, 16384, 0, &mem); if (error) { fdrop(fp, curthread); return (error); } - + /* Do something with 'mem'. */ error = shm_unmap(fp, mem, 16384); fdrop(fp, curthread); return (error); } .Ed .Sh ERRORS The .Fn shm_map function returns the following errors on failure: .Bl -tag -width Er .It Bq Er EINVAL The open file .Fa fp is not a shared memory object. .It Bq Er EINVAL The requested region described by .Fa offset and .Fa size extends beyond the end of the shared memory object. .It Bq Er ENOMEM Insufficient address space was available. .It Bq Er EACCES The shared memory object could not be mapped due to a protection error. .It Bq Er EINVAL The shared memory object could not be mapped due to some other VM error. .El .Pp The .Fn shm_unmap function returns the following errors on failure: .Bl -tag -width Er .It Bq Er EINVAL The open file .Fa fp is not a shared memory object. .It Bq Er EINVAL The address range described by .Fa mem and .Fa size is not a valid address range. .It Bq Er EINVAL The address range described by .Fa mem and .Fa size is not backed by the shared memory object associated with the open file .Fa fp , or the address range does not cover the entire mapping of the object. .El .Sh SEE ALSO .Xr shm_open 2 .Sh HISTORY This API was first introduced in .Fx 10.0 . Index: stable/9/share/man/man9/sleep.9 =================================================================== --- stable/9/share/man/man9/sleep.9 (revision 237215) +++ stable/9/share/man/man9/sleep.9 (revision 237216) @@ -1,346 +1,346 @@ .\" .\" Copyright (c) 1996 Joerg Wunsch .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 December 12, 2009 .Dt SLEEP 9 .Os .Sh NAME .Nm msleep , .Nm msleep_spin , .Nm pause , .Nm tsleep , .Nm wakeup .Nd wait for events .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In sys/proc.h .Ft int .Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" .Ft int .Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo" .Ft void .Fn pause "const char *wmesg" "int timo" .Ft int .Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo" .Ft void .Fn wakeup "void *chan" .Ft void .Fn wakeup_one "void *chan" .Sh DESCRIPTION The functions .Fn tsleep , .Fn msleep , .Fn msleep_spin , .Fn pause , .Fn wakeup , and .Fn wakeup_one handle event-based thread blocking. If a thread must wait for an external event, it is put to sleep by .Fn tsleep , .Fn msleep , .Fn msleep_spin , or .Fn pause . Threads may also wait using one of the locking primitive sleep routines .Xr mtx_sleep 9 , .Xr rw_sleep 9 , or .Xr sx_sleep 9 . .Pp The parameter .Fa chan is an arbitrary address that uniquely identifies the event on which the thread is being put to sleep. All threads sleeping on a single .Fa chan are woken up later by .Fn wakeup , often called from inside an interrupt routine, to indicate that the resource the thread was blocking on is available now. .Pp The parameter .Fa priority specifies a new priority for the thread as well as some optional flags. If the new priority is not 0, then the thread will be made runnable with the specified .Fa priority when it resumes. -.Dv PZERO +.Dv PZERO should never be used, as it is for compatibility only. A new priority of 0 means to use the thread's current priority when it is made runnable again. .Pp If .Fa priority includes the .Dv PCATCH flag, signals are checked before and after sleeping, otherwise signals are not checked. If .Dv PCATCH is set and a signal needs to be delivered, .Er ERESTART is returned if the current system call should be restarted if possible, and .Er EINTR is returned if the system call should be interrupted by the signal (return .Er EINTR ) . If .Dv PBDRY flag is specified in addition to .Dv PCATCH , then the sleeping thread is not stopped while sleeping upon delivery of .Dv SIGSTOP or other stop action. Instead, it is waken up, assuming that stop occurs on reaching a stop point when returning to usermode. The flag should be used when sleeping thread owns resources, for instance vnode locks, that should be freed timely. .Pp The parameter .Fa wmesg is a string describing the sleep condition for tools like .Xr ps 1 . Due to the limited space of those programs to display arbitrary strings, this message should not be longer than 6 characters. .Pp The parameter .Fa timo specifies a timeout for the sleep. If .Fa timo is not 0, then the thread will sleep for at most .Fa timo No / Va hz seconds. If the timeout expires, then the sleep function will return .Er EWOULDBLOCK . .Pp Several of the sleep functions including .Fn msleep , .Fn msleep_spin , and the locking primitive sleep routines specify an additional lock parameter. The lock will be released before sleeping and reacquired before the sleep routine returns. If .Fa priority includes the .Dv PDROP flag, then the lock will not be reacquired before returning. The lock is used to ensure that a condition can be checked atomically, and that the current thread can be suspended without missing a change to the condition, or an associated wakeup. In addition, all of the sleep routines will fully drop the .Va Giant mutex (even if recursed) while the thread is suspended and will reacquire the .Va Giant mutex before the function returns. Note that the .Va Giant mutex may be specified as the lock to drop. In that case, however, the .Dv PDROP flag is not allowed. .Pp To avoid lost wakeups, either a lock should be used to protect against races, or a timeout should be specified to place an upper bound on the delay due to a lost wakeup. As a result, the .Fn tsleep function should only be invoked with a timeout of 0 when the .Va Giant mutex is held. .Pp The .Fn msleep function requires that .Fa mtx reference a default, i.e. non-spin, mutex. Its use is deprecated in favor of .Xr mtx_sleep 9 which provides identical behavior. .Pp The .Fn msleep_spin function requires that .Fa mtx reference a spin mutex. The .Fn msleep_spin function does not accept a .Fa priority parameter and thus does not support changing the current thread's priority, the .Dv PDROP flag, or catching signals via the .Dv PCATCH flag. .Pp The .Fn pause function is a wrapper around .Fn tsleep that suspends execution of the current thread for the indicated timeout. The thread can not be awakened early by signals or calls to .Fn wakeup or .Fn wakeup_one . .Pp The .Fn wakeup_one function makes the first thread in the queue that is sleeping on the parameter .Fa chan runnable. This reduces the load when a large number of threads are sleeping on the same address, but only one of them can actually do any useful work when made runnable. .Pp Due to the way it works, the .Fn wakeup_one function requires that only related threads sleep on a specific .Fa chan address. It is the programmer's responsibility to choose a unique .Fa chan value. The older .Fn wakeup -function did not require this, though it was never good practice +function did not require this, though it was never good practice for threads to share a .Fa chan value. When converting from .Fn wakeup to .Fn wakeup_one , pay particular attention to ensure that no other threads wait on the same .Fa chan . .Sh RETURN VALUES When awakened by a call to .Fn wakeup or .Fn wakeup_one , if a signal is pending and .Dv PCATCH is specified, a non-zero error code is returned. If the thread is awakened by a call to .Fn wakeup or .Fn wakeup_one , the .Fn msleep , .Fn msleep_spin , .Fn tsleep , and locking primitive sleep functions return 0. Otherwise, a non-zero error code is returned. .Sh ERRORS .Fn msleep , .Fn msleep_spin , .Fn tsleep , and the locking primitive sleep functions will fail if: .Bl -tag -width Er .It Bq Er EINTR The .Dv PCATCH flag was specified, a signal was caught, and the system call should be interrupted. .It Bq Er ERESTART The .Dv PCATCH flag was specified, a signal was caught, and the system call should be restarted. .It Bq Er EWOULDBLOCK A non-zero timeout was specified and the timeout expired. .El .Sh SEE ALSO .Xr ps 1 , .Xr locking 9 , .Xr malloc 9 , .Xr mi_switch 9 , .Xr mtx_sleep 9 , .Xr rw_sleep 9 , .Xr sx_sleep 9 .Sh HISTORY The functions .Fn sleep and .Fn wakeup were present in .At v1 . They were probably also present in the preceding PDP-7 version of .Ux . They were the basic process synchronization model. .Pp The .Fn tsleep function appeared in .Bx 4.4 and added the parameters .Fa wmesg and .Fa timo . The .Fn sleep function was removed in .Fx 2.2 . The .Fn wakeup_one function appeared in .Fx 2.2 . The .Fn msleep function appeared in .Fx 5.0 , and the .Fn msleep_spin function appeared in .Fx 6.2 . The .Fn pause function appeared in .Fx 7.0 . .Sh AUTHORS .An -nosplit This manual page was written by .An J\(:org Wunsch Aq joerg@FreeBSD.org . Index: stable/9/share/man/man9/spl.9 =================================================================== --- stable/9/share/man/man9/spl.9 (revision 237215) +++ stable/9/share/man/man9/spl.9 (revision 237216) @@ -1,228 +1,228 @@ .\" .\" Copyright (c) 1996 Joerg Wunsch .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 July 21, 1996 .Dt SPL 9 .Os .Sh NAME .Nm splbio , .Nm splclock , .Nm splhigh , .Nm splimp , .Nm splnet , .Nm splsoftclock , .Nm splsofttty , .Nm splstatclock , .Nm spltty , .Nm splvm , .Nm spl0 , .Nm splx .Nd manipulate interrupt priorities .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .Ft intrmask_t .Fn splbio "void" .Ft intrmask_t .Fn splclock "void" .Ft intrmask_t .Fn splhigh "void" .Ft intrmask_t .Fn splimp "void" .Ft intrmask_t .Fn splnet "void" .Ft intrmask_t .Fn splsoftclock "void" .Ft intrmask_t .Fn splsofttty "void" .Ft intrmask_t .Fn splstatclock "void" .Ft intrmask_t .Fn spltty "void" .Ft void .Fn spl0 "void" .Ft void .Fn splx "intrmask_t ipl" .Sh DESCRIPTION .Bf -symbolic This API is deprecated. Use mutexes to protect data structures instead. See .Xr mutex 9 for more information. The API is now a complete NOP. This man page documents historical behavior so you can understand the code locking that the spl did when converting code from versions of the kernel prior to .Fx 5.0 . The examples in this man page are also obsolete and should not be viewed -as documenting -.Fx 5.0 +as documenting +.Fx 5.0 and newer. .Ef .Pp The .Fn spl function family sets the interrupt priority .Dq level of the CPU. This prevents interrupt handlers of the blocked priority level from being run. This is used in the .Dq synchronous part of a driver (the part that runs on behalf of the user process) to examine or modify data areas that might be examined or modified by interrupt handlers. .Pp Each driver that uses interrupts is normally assigned to an interrupt priority group by a keyword in its config line. For example: .Bd -literal -offset indent device foo0 at isa? port 0x0815 irq 12 tty .Ed .Pp assigns interrupt 12 to the .Dq tty priority group. The system automatically arranges for interrupts in the .Em xxx group to be called at a priority >= .Em spl Ns Fn xxx .Pp The function .Fn splx sets the interrupt priority to an absolute value. The intent is that the value returned by the other functions should be saved in a local variable, and later passed to .Fn splx in order to restore the previous priority. .Pp The function .Fn spl0 lowers the priority to a value where all interrupt handlers are unblocked, but ASTs (asynchronous system traps) remain blocked until the system is about to return to user mode. .Pp The traditional assignment of the various device drivers to the interrupt priority groups can be roughly classified as: .Bl -tag -width Fn .It Fn splnet Software part of the network interface drivers. .It Fn splimp All network interface drivers. .It Fn splbio All .Em buffered IO (i.e., disk and the like) drivers. .It Fn spltty Basically, all non-network communications devices, but effectively used for all drivers that are neither network nor disks. .El .Sh RETURN VALUES All functions except .Fn splx and .Fn spl0 return the previous priority value. .Sh EXAMPLES This is a typical example demonstrating the usage: .Bd -literal struct foo_softc { ... int flags; #define FOO_ASLEEP 1 #define FOO_READY 2 } foo_softc[NFOO]; int foowrite(...) { struct foo_softc *sc; int s, error; ... s = spltty(); if (!(sc->flags & FOO_READY)) { /* Not ready, must sleep on resource. */ sc->flags |= FOO_ASLEEP; error = tsleep(sc, PZERO, "foordy", 0); sc->flags &= ~FOO_ASLEEP; } sc->flags &= ~FOO_READY; splx(s); ... } void foointr(...) { struct foo_softc *sc; ... sc->flags |= FOO_READY; if (sc->flags & FOO_ASLEEP) /* Somebody was waiting for us, awake him. */ wakeup(sc); ... } .Ed Note that the interrupt handler should .Em never reduce the priority level. It is automatically called as it had raised the interrupt priority to its own level, i.e., further interrupts of the same group are being blocked. .Sh HISTORY The interrupt priority levels appeared in a very early version of .Ux . They have been traditionally known by number instead of by names, and were inclusive up to higher priority levels (i.e., priority 5 has been blocking everything up to level 5). This is no longer the case in .Fx . The traditional name .Ql level for them is still reflected in the letter .Ql l of the respective functions and variables, although they are not really levels anymore, but rather different (partially inclusive) sets of functions to be blocked during some periods of the life of the system. The historical number scheme can be considered as a simple linearly ordered set of interrupt priority groups. .Pp .Fx 5.0 eliminated spl entirely in favor of locking primitives which scale to more than one processor. .Sh AUTHORS This manual page was written by .An J\(:org Wunsch . Index: stable/9/share/man/man9/sysctl_ctx_init.9 =================================================================== --- stable/9/share/man/man9/sysctl_ctx_init.9 (revision 237215) +++ stable/9/share/man/man9/sysctl_ctx_init.9 (revision 237216) @@ -1,247 +1,247 @@ .\" .\" Copyright (c) 2000, Andrzej Bialecki .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd July 15, 2000 .Dt SYSCTL_CTX_INIT 9 .Os .Sh NAME .Nm sysctl_ctx_init , .Nm sysctl_ctx_free , .Nm sysctl_ctx_entry_add , .Nm sysctl_ctx_entry_find , .Nm sysctl_ctx_entry_del .Nd "sysctl context for managing dynamically created sysctl oids" .Sh SYNOPSIS .In sys/types.h .In sys/sysctl.h .Ft int .Fo sysctl_ctx_init .Fa "struct sysctl_ctx_list *clist" .Fc .Ft int .Fo sysctl_ctx_free .Fa "struct sysctl_ctx_list *clist" .Fc .Ft struct sysctl_ctx_entry * .Fo sysctl_ctx_entry_add .Fa "struct sysctl_ctx_list *clist" .Fa "struct sysctl_oid *oidp" .Fc .Ft struct sysctl_ctx_entry * .Fo sysctl_ctx_entry_find .Fa "struct sysctl_ctx_list *clist" .Fa "struct sysctl_oid *oidp" .Fc .Ft int .Fo sysctl_ctx_entry_del .Fa "struct sysctl_ctx_list *clist" .Fa "struct sysctl_oid *oidp" .Fc .Sh DESCRIPTION These functions provide an interface for managing dynamically created oids. The sysctl context is responsible for keeping track of created oids, as well as their proper removal when needed. It adds a simple transactional aspect to oid removal operations; i.e., if a removal operation fails part way, it is possible to roll back the sysctl tree to its previous state. .Pp The .Fn sysctl_ctx_init function initializes a sysctl context. The .Fa clist argument must point to an already allocated variable. A context .Em must be initialized before use. Once it is initialized, a pointer to the context can be passed as an argument to all the .Fa SYSCTL_ADD_* macros (see .Xr sysctl_add_oid 9 ) , and it will be updated with entries pointing to newly created oids. .Pp Internally, the context is represented as a .Xr queue 3 TAILQ linked list. The list consists of .Li struct sysctl_ctx_entry entries: .Bd -literal -offset indent struct sysctl_ctx_entry { struct sysctl_oid *entry; TAILQ_ENTRY(sysctl_ctx_entry) link; }; TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry); .Ed .Pp Each context entry points to one dynamic oid that it manages. Newly created oids are always inserted in the front of the list. .Pp The .Fn sysctl_ctx_free function removes the context and associated oids it manages. If the function completes successfully, all managed oids have been unregistered (removed from the tree) and freed, together with all their allocated memory, and the entries of the context have been freed as well. .Pp The removal operation is performed in two steps. First, for each context entry, the function .Xr sysctl_remove_oid 9 is executed, with parameter .Fa del set to 0, which inhibits the freeing of resources. If there are no errors during this step, .Fn sysctl_ctx_free proceeds to the next step. If the first step fails, all unregistered oids associated with the context are registered again. .Pp .Em Note : in most cases, the programmer specifies .Dv OID_AUTO as the oid number when creating an oid. However, during registration of the oid in the tree, this number is changed to the first available number -greater than or equal to +greater than or equal to .Dv CTL_AUTO_START . If the first step of context deletion fails, re-registration of the oid does not change the already assigned oid number (which is different from OID_AUTO). This ensures that re-registered entries maintain their original positions in the tree. .Pp The second step actually performs the deletion of the dynamic oids. .Xr sysctl_remove_oid 9 iterates through the context list, starting from beginning (i.e., the newest entries). .Em Important : this time, the function not only deletes the oids from the tree, but also frees their memory (provided that oid_refcnt == 0), as well as the memory of all context entries. .Pp The .Fn sysctl_ctx_entry_add function allows the addition of an existing dynamic oid to a context. .Pp The .Fn sysctl_ctx_entry_del function removes an entry from the context. .Em Important : in this case, only the corresponding .Li struct sysctl_ctx_entry is freed, but the .Fa oidp pointer remains intact. Thereafter, the programmer is responsible for managing the resources allocated to this oid. .Pp The .Fn sysctl_ctx_entry_find function searches for a given .Fa oidp within a context list, either returning a pointer to the .Fa struct sysctl_ctx_entry found, or .Dv NULL . .Sh EXAMPLES The following is an example of how to create a new top-level category and how to hook up another subtree to an existing static node. This example uses contexts to keep track of the oids. .Bd -literal #include ... struct sysctl_ctx_list clist; struct sysctl_oid *oidp; int a_int; const char *string = "dynamic sysctl"; ... sysctl_ctx_init(&clist); oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(/* tree top */), OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); oidp = SYSCTL_ADD_INT(&clist, SYSCTL_CHILDREN(oidp), OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); ... oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug), OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); oidp = SYSCTL_ADD_STRING(&clist, SYSCTL_CHILDREN(oidp), OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); ... /* Now we can free up the oids */ if (sysctl_ctx_free(&clist)) { printf("can't free this context - other oids depend on it"); return (ENOTEMPTY); } else { printf("Success!\\n"); return (0); } .Ed .Pp This example creates the following subtrees: .Bd -literal -offset indent debug.newtree.newstring newtree.newint .Ed .Pp Note that both trees are removed, and their resources freed, through one .Fn sysctl_ctx_free call, which starts by freeing the newest entries (leaves) and then proceeds to free the older entries (in this case the nodes). .Sh SEE ALSO .Xr queue 3 , .Xr sysctl 8 , .Xr sysctl 9 , .Xr sysctl_add_oid 9 , .Xr sysctl_remove_oid 9 .Sh HISTORY These functions first appeared in .Fx 4.2 . .Sh AUTHORS .An Andrzej Bialecki Aq abial@FreeBSD.org .Sh BUGS The current removal algorithm is somewhat heavy. In the worst case, all oids need to be unregistered, registered again, and then unregistered and deleted. However, the algorithm does guarantee transactional properties for removal operations. .Pp All operations on contexts involve linked list traversal. For this reason, creation and removal of entries is relatively costly. Index: stable/9/share/man/man9/taskqueue.9 =================================================================== --- stable/9/share/man/man9/taskqueue.9 (revision 237215) +++ stable/9/share/man/man9/taskqueue.9 (revision 237216) @@ -1,382 +1,382 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2000 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 26, 2011 .Dt TASKQUEUE 9 .Os .Sh NAME .Nm taskqueue .Nd asynchronous task execution .Sh SYNOPSIS .In sys/param.h .In sys/kernel.h .In sys/malloc.h .In sys/queue.h .In sys/taskqueue.h .Bd -literal typedef void (*task_fn_t)(void *context, int pending); typedef void (*taskqueue_enqueue_fn)(void *context); struct task { STAILQ_ENTRY(task) ta_link; /* link for queue */ u_short ta_pending; /* count times queued */ u_short ta_priority; /* priority of task in queue */ task_fn_t ta_func; /* task handler */ void *ta_context; /* argument for handler */ }; struct timeout_task; .Ed .Ft struct taskqueue * .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" .Ft struct taskqueue * .Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" .Ft void .Fn taskqueue_free "struct taskqueue *queue" .Ft int .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task" .Ft int .Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task" .Ft int .Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks" .Ft int .Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp" .Ft int .Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp" .Ft void .Fn taskqueue_drain "struct taskqueue *queue" "struct task *task" .Ft void .Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" .Ft int .Fn taskqueue_member "struct taskqueue *queue" "struct thread *td" .Ft void .Fn taskqueue_run "struct taskqueue *queue" .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context" .Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context" .Fn TASKQUEUE_DECLARE "name" .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" .Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" .Fn TASKQUEUE_DEFINE_THREAD "name" .Fn TASKQUEUE_FAST_DEFINE_THREAD "name" .Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context" .Sh DESCRIPTION These functions provide a simple interface for asynchronous execution of code. .Pp The function .Fn taskqueue_create is used to create new queues. The arguments to .Fn taskqueue_create include a name that should be unique, a set of .Xr malloc 9 flags that specify whether the call to .Fn malloc is allowed to sleep, a function that is called from .Fn taskqueue_enqueue when a task is added to the queue, and a pointer to the memory location where the identity of the thread that services the queue is recorded. .\" XXX The rest of the sentence gets lots in relation to the first part. The function called from .Fn taskqueue_enqueue must arrange for the queue to be processed (for instance by scheduling a software interrupt or waking a kernel thread). The memory location where the thread identity is recorded is used to signal the service thread(s) to terminate--when this value is set to zero and the thread is signaled it will terminate. -If the queue is intended for use in fast interrupt handlers -.Fn taskqueue_create_fast +If the queue is intended for use in fast interrupt handlers +.Fn taskqueue_create_fast should be used in place of .Fn taskqueue_create . .Pp The function .Fn taskqueue_free should be used to free the memory used by the queue. Any tasks that are on the queue will be executed at this time after which the thread servicing the queue will be signaled that it should exit. .Pp To add a task to the list of tasks queued on a taskqueue, call .Fn taskqueue_enqueue with pointers to the queue and task. If the task's .Va ta_pending field is non-zero, then it is simply incremented to reflect the number of times the task was enqueued, up to a cap of USHRT_MAX. Otherwise, the task is added to the list before the first task which has a lower .Va ta_priority value or at the end of the list if no tasks have a lower priority. Enqueueing a task does not perform any memory allocation which makes it suitable for calling from an interrupt handler. This function will return .Er EPIPE if the queue is being freed. .Pp The function .Fn taskqueue_enqueue_fast should be used in place of .Fn taskqueue_enqueue when the enqueuing must happen from a fast interrupt handler. This method uses spin locks to avoid the possibility of sleeping in the fast interrupt context. .Pp When a task is executed, first it is removed from the queue, the value of .Va ta_pending is recorded and then the field is zeroed. The function .Va ta_func from the task structure is called with the value of the field .Va ta_context as its first argument and the value of .Va ta_pending as its second argument. After the function .Va ta_func returns, .Xr wakeup 9 is called on the task pointer passed to .Fn taskqueue_enqueue . .Pp The .Fn taskqueue_enqueue_timeout is used to schedule the enqueue after the specified amount of .Va ticks . Only non-fast task queues can be used for .Va timeout_task scheduling. .Pp The .Fn taskqueue_cancel function is used to cancel a task. The .Va ta_pending count is cleared, and the old value returned in the reference parameter .Fa pendp , if it is .Pf non- Dv NULL . If the task is currently running, .Dv EBUSY is returned, otherwise 0. To implement a blocking .Fn taskqueue_cancel that waits for a running task to finish, it could look like: .Bd -literal -offset indent while (taskqueue_cancel(tq, task, NULL) != 0) taskqueue_drain(tq, task); .Ed .Pp Note that, as with .Fn taskqueue_drain , the caller is responsible for ensuring that the task is not re-enqueued after being canceled. .Pp Similarly, the .Fn taskqueue_cancel_timeout function is used to cancel the scheduled task execution. .Pp The .Fn taskqueue_drain function is used to wait for the task to finish, and the .Fn taskqueue_drain_timeout function is used to wait for the scheduled task to finish. There is no guarantee that the task will not be enqueued after call to .Fn taskqueue_drain . .Pp The .Fn taskqueue_member function returns .No 1 if the given thread .Fa td is part of the given taskqueue .Fa queue and .No 0 otherwise. .Pp The .Fn taskqueue_run function will run all pending tasks in the specified .Fa queue . Normally this function is only used internally. .Pp A convenience macro, .Fn TASK_INIT "task" "priority" "func" "context" is provided to initialise a .Va task structure. The .Fn TASK_INITIALIZER macro generates an initializer for a task structure. A macro .Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context" initializes the .Va timeout_task structure. The values of .Va priority , .Va func , and .Va context are simply copied into the task structure fields and the .Va ta_pending field is cleared. .Pp Five macros .Fn TASKQUEUE_DECLARE "name" , .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" , .Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" , and .Fn TASKQUEUE_DEFINE_THREAD "name" .Fn TASKQUEUE_FAST_DEFINE_THREAD "name" are used to declare a reference to a global queue, to define the implementation of the queue, and declare a queue that uses its own thread. The .Fn TASKQUEUE_DEFINE macro arranges to call .Fn taskqueue_create with the values of its .Va name , .Va enqueue and .Va context arguments during system initialisation. After calling .Fn taskqueue_create , the .Va init argument to the macro is executed as a C statement, allowing any further initialisation to be performed (such as registering an interrupt handler etc.) .Pp The .Fn TASKQUEUE_DEFINE_THREAD macro defines a new taskqueue with its own kernel thread to serve tasks. The variable .Vt struct taskqueue *taskqueue_name is used to enqueue tasks onto the queue. .Pp .Fn TASKQUEUE_FAST_DEFINE -and +and .Fn TASKQUEUE_FAST_DEFINE_THREAD -act just like +act just like .Fn TASKQUEUE_DEFINE and .Fn TASKQUEUE_DEFINE_THREAD respectively but taskqueue is created with .Fn taskqueue_create_fast . .Ss Predefined Task Queues The system provides four global taskqueues, .Va taskqueue_fast , .Va taskqueue_swi , .Va taskqueue_swi_giant , and .Va taskqueue_thread . The .Va taskqueue_fast queue is for swi handlers dispatched from fast interrupt handlers, where sleep mutexes cannot be used. The swi taskqueues are run via a software interrupt mechanism. The .Va taskqueue_swi queue runs without the protection of the .Va Giant kernel lock, and the .Va taskqueue_swi_giant queue runs with the protection of the .Va Giant kernel lock. The thread taskqueue .Va taskqueue_thread runs in a kernel thread context, and tasks run from this thread do not run under the .Va Giant kernel lock. If the caller wants to run under .Va Giant , he should explicitly acquire and release .Va Giant in his taskqueue handler routine. .Pp To use these queues, call .Fn taskqueue_enqueue with the value of the global taskqueue variable for the queue you wish to use .Va ( taskqueue_swi , .Va taskqueue_swi_giant , or .Va taskqueue_thread ) . Use .Fn taskqueue_enqueue_fast for the global taskqueue variable .Va taskqueue_fast . .Pp The software interrupt queues can be used, for instance, for implementing interrupt handlers which must perform a significant amount of processing in the handler. The hardware interrupt handler would perform minimal processing of the interrupt and then enqueue a task to finish the work. This reduces to a minimum the amount of time spent with interrupts disabled. .Pp The thread queue can be used, for instance, by interrupt level routines that need to call kernel functions that do things that can only be done from a thread context. (e.g., call malloc with the M_WAITOK flag.) .Pp Note that tasks queued on shared taskqueues such as .Va taskqueue_swi may be delayed an indeterminate amount of time before execution. If queueing delays cannot be tolerated then a private taskqueue should be created with a dedicated processing thread. .Sh SEE ALSO .Xr ithread 9 , .Xr kthread 9 , .Xr swi 9 .Sh HISTORY This interface first appeared in .Fx 5.0 . There is a similar facility called work_queue in the Linux kernel. .Sh AUTHORS This manual page was written by .An Doug Rabson . Index: stable/9/share/man/man9/timeout.9 =================================================================== --- stable/9/share/man/man9/timeout.9 (revision 237215) +++ stable/9/share/man/man9/timeout.9 (revision 237216) @@ -1,561 +1,561 @@ .\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" 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 NETBSD FOUNDATION, INC. 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. .\" .\" $FreeBSD$ .\" .Dd August 2, 2008 .Dt TIMEOUT 9 .Os .Sh NAME .Nm timeout , .Nm untimeout , .Nm callout_handle_init , .Nm callout_init , .Nm callout_init_mtx , .Nm callout_init_rw , .Nm callout_stop , .Nm callout_drain , .Nm callout_reset , .Nm callout_schedule , .Nm callout_pending , .Nm callout_active , .Nm callout_deactivate .Nd execute a function after a specified length of time .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .Bd -literal typedef void timeout_t (void *); .Ed .Ft struct callout_handle .Fn timeout "timeout_t *func" "void *arg" "int ticks" .Ft void .Fn callout_handle_init "struct callout_handle *handle" .Bd -literal struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle) .Ed .Ft void .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle" .Ft void .Fn callout_init "struct callout *c" "int mpsafe" .Ft void .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags" .Ft void .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags" .Ft int .Fn callout_stop "struct callout *c" .Ft int .Fn callout_drain "struct callout *c" .Ft int .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" .Ft int .Fn callout_schedule "struct callout *c" "int ticks" .Ft int .Fn callout_pending "struct callout *c" .Ft int .Fn callout_active "struct callout *c" .Fn callout_deactivate "struct callout *c" .Sh DESCRIPTION The function .Fn timeout schedules a call to the function given by the argument .Fa func to take place after .Fa ticks Ns No /hz seconds. Non-positive values of .Fa ticks are silently converted to the value .Sq 1 . .Fa func should be a pointer to a function that takes a .Fa void * argument. Upon invocation, .Fa func will receive .Fa arg as its only argument. The return value from .Fn timeout is a .Ft struct callout_handle which can be used in conjunction with the .Fn untimeout function to request that a scheduled timeout be canceled. The .Fn timeout call is the old style and new code should use the .Fn callout_* functions. .Pp The function .Fn callout_handle_init can be used to initialize a handle to a state which will cause any calls to .Fn untimeout with that handle to return with no side effects. .Pp Assigning a callout handle the value of .Fn CALLOUT_HANDLE_INITIALIZER performs the same function as .Fn callout_handle_init and is provided for use on statically declared or global callout handles. .Pp The function .Fn untimeout cancels the timeout associated with .Fa handle using the .Fa func and .Fa arg arguments to validate the handle. If the handle does not correspond to a timeout with the function .Fa func taking the argument .Fa arg no action is taken. .Fa handle must be initialized by a previous call to .Fn timeout , .Fn callout_handle_init , or assigned the value of .Fn CALLOUT_HANDLE_INITIALIZER "&handle" before being passed to .Fn untimeout . The behavior of calling .Fn untimeout with an uninitialized handle is undefined. The .Fn untimeout call is the old style and new code should use the .Fn callout_* functions. .Pp As handles are recycled by the system, it is possible (although unlikely) that a handle from one invocation of .Fn timeout may match the handle of another invocation of .Fn timeout if both calls used the same function pointer and argument, and the first timeout is expired or canceled before the second call. The timeout facility offers O(1) running time for .Fn timeout and .Fn untimeout . Timeouts are executed from .Fn softclock with the .Va Giant lock held. Thus they are protected from re-entrancy. .Pp The functions .Fn callout_init , .Fn callout_init_mtx , .Fn callout_init_rw , .Fn callout_stop , .Fn callout_drain , .Fn callout_reset and .Fn callout_schedule are low-level routines for clients who wish to allocate their own callout structures. .Pp The function .Fn callout_init initializes a callout so it can be passed to .Fn callout_stop , .Fn callout_drain , -.Fn callout_reset +.Fn callout_reset or -.Fn callout_schedule +.Fn callout_schedule without any side effects. If the .Fa mpsafe argument is zero, the callout structure is not considered to be .Dq multi-processor safe ; that is, the Giant lock will be acquired before calling the callout function, and released when the callout function returns. .Pp The .Fn callout_init_mtx function may be used as an alternative to .Fn callout_init . The parameter .Fa mtx specifies a mutex that is to be acquired by the callout subsystem before calling the callout function, and released when the callout function returns. The following .Fa flags may be specified: .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED" .It Dv CALLOUT_RETURNUNLOCKED The callout function will release .Fa mtx itself, so the callout subsystem should not attempt to unlock it after the callout function returns. .El .Pp The .Fn callout_init_rw function serves the need of using rwlocks in conjunction with callouts. The function does basically the same as .Fn callout_init_mtx with the possibility of specifying an extra .Fa rw argument. The usable lock classes are currently limited to mutexes and rwlocks, because callout handlers run in softclock swi, so they cannot sleep nor acquire sleepable locks like sx or lockmgr. The following .Fa flags may be specified: .Bl -tag -width ".Dv CALLOUT_SHAREDLOCK" .It Dv CALLOUT_SHAREDLOCK The lock is only acquired in read mode when running the callout handler. It has no effects when used in conjunction with .Fa mtx . .El .Pp The function .Fn callout_stop cancels a callout if it is currently pending. If the callout is pending, then .Fn callout_stop will return a non-zero value. If the callout is not set, has already been serviced or is currently being serviced, then zero will be returned. If the callout has an associated mutex, then that mutex must be held when this function is called. .Pp The function .Fn callout_drain is identical to .Fn callout_stop except that it will wait for the callout to be completed if it is already in progress. This function MUST NOT be called while holding any locks on which the callout might block, or deadlock will result. Note that if the callout subsystem has already begun processing this callout, then the callout function may be invoked during the execution of .Fn callout_drain . However, the callout subsystem does guarantee that the callout will be fully stopped before .Fn callout_drain returns. .Pp The function .Fn callout_reset first performs the equivalent of .Fn callout_stop to disestablish the callout, and then establishes a new callout in the same manner as .Fn timeout . If there was already a pending callout and it was rescheduled, then .Fn callout_reset will return a non-zero value. If the callout has an associated mutex, then that mutex must be held when this function is called. The function .Fn callout_schedule (re)schedules an existing callout for a new period of time; it is equivalent to calling .Fn callout_reset with the .Fa func and .Fa arg parameters extracted from the callout structure (though possibly with lower overhead). .Pp The macros .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate provide access to the current state of the callout. Careful use of these macros can avoid many of the race conditions that are inherent in asynchronous timer facilities; see .Sx "Avoiding Race Conditions" below for further details. The .Fn callout_pending macro checks whether a callout is .Em pending ; a callout is considered .Em pending when a timeout has been set but the time has not yet arrived. Note that once the timeout time arrives and the callout subsystem starts to process this callout, .Fn callout_pending will return .Dv FALSE even though the callout function may not have finished (or even begun) executing. The .Fn callout_active macro checks whether a callout is marked as .Em active , and the .Fn callout_deactivate macro clears the callout's .Em active flag. The callout subsystem marks a callout as .Em active when a timeout is set and it clears the .Em active flag in .Fn callout_stop and .Fn callout_drain , but it .Em does not clear it when a callout expires normally via the execution of the callout function. .Ss "Avoiding Race Conditions" The callout subsystem invokes callout functions from its own timer context. Without some kind of synchronization it is possible that a callout function will be invoked concurrently with an attempt to stop or reset the callout by another thread. In particular, since callout functions typically acquire a mutex as their first action, the callout function may have already been invoked, but be blocked waiting for that mutex at the time that another thread tries to reset or stop the callout. .Pp The callout subsystem provides a number of mechanisms to address these synchronization concerns: .Bl -enum -offset indent .It If the callout has an associated mutex that was specified using the .Fn callout_init_mtx function (or implicitly specified as the .Va Giant mutex using .Fn callout_init with .Fa mpsafe set to .Dv FALSE ) , then this mutex is used to avoid the race conditions. The associated mutex must be acquired by the caller before calling .Fn callout_stop or .Fn callout_reset and it is guaranteed that the callout will be correctly stopped or reset as expected. Note that it is still necessary to use .Fn callout_drain before destroying the callout or its associated mutex. .It The return value from .Fn callout_stop and .Fn callout_reset indicates whether or not the callout was removed. If it is known that the callout was set and the callout function has not yet executed, then a return value of .Dv FALSE indicates that the callout function is about to be called. For example: .Bd -literal -offset indent if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) { if (callout_stop(&sc->sc_callout)) { sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING; /* successfully stopped */ } else { /* * callout has expired and callout * function is about to be executed */ } } .Ed .It The .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate macros can be used together to work around the race conditions. When a callout's timeout is set, the callout subsystem marks the callout as both .Em active and .Em pending . When the timeout time arrives, the callout subsystem begins processing the callout by first clearing the .Em pending flag. It then invokes the callout function without changing the .Em active flag, and does not clear the .Em active flag even after the callout function returns. The mechanism described here requires the callout function itself to clear the .Em active flag using the .Fn callout_deactivate macro. The .Fn callout_stop and .Fn callout_drain functions always clear both the .Em active and .Em pending flags before returning. .Pp The callout function should first check the .Em pending flag and return without action if .Fn callout_pending returns .Dv TRUE . This indicates that the callout was rescheduled using .Fn callout_reset just before the callout function was invoked. If .Fn callout_active returns .Dv FALSE then the callout function should also return without action. This indicates that the callout has been stopped. Finally, the callout function should call .Fn callout_deactivate to clear the .Em active flag. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); if (callout_pending(&sc->sc_callout)) { /* callout was reset */ mtx_unlock(&sc->sc_mtx); return; } if (!callout_active(&sc->sc_callout)) { /* callout was stopped */ mtx_unlock(&sc->sc_mtx); return; } callout_deactivate(&sc->sc_callout); /* rest of callout function */ .Ed .Pp Together with appropriate synchronization, such as the mutex used above, this approach permits the .Fn callout_stop and .Fn callout_reset functions to be used at any time without races. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); callout_stop(&sc->sc_callout); /* The callout is effectively stopped now. */ .Ed .Pp If the callout is still pending then these functions operate normally, but if processing of the callout has already begun then the tests in the callout function cause it to return without further action. Synchronization between the callout function and other code ensures that stopping or resetting the callout will never be attempted while the callout function is past the .Fn callout_deactivate call. .Pp The above technique additionally ensures that the .Em active flag always reflects whether the callout is effectively enabled or disabled. If .Fn callout_active returns false, then the callout is effectively disabled, since even if the callout subsystem is actually just about to invoke the callout function, the callout function will return without action. .El .Pp There is one final race condition that must be considered when a callout is being stopped for the last time. In this case it may not be safe to let the callout function itself detect that the callout was stopped, since it may need to access data objects that have already been destroyed or recycled. To ensure that the callout is completely finished, a call to .Fn callout_drain should be used. .Sh RETURN VALUES The .Fn timeout function returns a .Ft struct callout_handle that can be passed to .Fn untimeout . The .Fn callout_stop and .Fn callout_drain functions return non-zero if the callout was still pending when it was called or zero otherwise. .Sh HISTORY The current timeout and untimeout routines are based on the work of .An Adam M. Costello and .An George Varghese , published in a technical report entitled .%T "Redesigning the BSD Callout and Timer Facilities" and modified slightly for inclusion in .Fx by .An Justin T. Gibbs . The original work on the data structures used in this implementation was published by .An G. Varghese and .An A. Lauck in the paper .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" in the .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . The current implementation replaces the long standing .Bx linked list callout mechanism which offered O(n) insertion and removal running time but did not generate or require handles for untimeout operations. Index: stable/9/share/man/man9/usbdi.9 =================================================================== --- stable/9/share/man/man9/usbdi.9 (revision 237215) +++ stable/9/share/man/man9/usbdi.9 (revision 237216) @@ -1,641 +1,641 @@ .\" .\" Copyright (c) 2005 Ian Dowse .\" 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. .\" .\" $FreeBSD$ .Dd June 24, 2009 .Dt USBDI 9 .Os .Sh NAME .Nm usb_fifo_alloc_buffer , .Nm usb_fifo_attach , .Nm usb_fifo_detach , .Nm usb_fifo_free_buffer , .Nm usb_fifo_get_data , .Nm usb_fifo_get_data_buffer , .Nm usb_fifo_get_data_error , .Nm usb_fifo_get_data_linear , .Nm usb_fifo_put_bytes_max , .Nm usb_fifo_put_data , .Nm usb_fifo_put_data_buffer , .Nm usb_fifo_put_data_error , .Nm usb_fifo_put_data_linear , .Nm usb_fifo_reset , .Nm usb_fifo_softc , .Nm usb_fifo_wakeup , .Nm usbd_do_request , .Nm usbd_do_request_flags , .Nm usbd_errstr , .Nm usbd_lookup_id_by_info , .Nm usbd_lookup_id_by_uaa , .Nm usbd_transfer_clear_stall , .Nm usbd_transfer_drain , .Nm usbd_transfer_pending , .Nm usbd_transfer_poll , .Nm usbd_transfer_setup , .Nm usbd_transfer_start , .Nm usbd_transfer_stop , .Nm usbd_transfer_submit , .Nm usbd_transfer_unsetup , .Nm usbd_xfer_clr_flag , .Nm usbd_xfer_frame_data , .Nm usbd_xfer_frame_len , .Nm usbd_xfer_get_frame , .Nm usbd_xfer_get_priv , .Nm usbd_xfer_is_stalled , .Nm usbd_xfer_max_framelen , .Nm usbd_xfer_max_frames , .Nm usbd_xfer_max_len , .Nm usbd_xfer_set_flag , .Nm usbd_xfer_set_frame_data , .Nm usbd_xfer_set_frame_len , .Nm usbd_xfer_set_frame_offset , .Nm usbd_xfer_set_frames , .Nm usbd_xfer_set_interval , .Nm usbd_xfer_set_priv , .Nm usbd_xfer_set_stall , .Nm usbd_xfer_set_timeout , .Nm usbd_xfer_softc , .Nm usbd_xfer_state , .Nm usbd_xfer_status .Nd Universal Serial Bus driver programming interface .Sh SYNOPSIS .In dev/usb/usb.h .In dev/usb/usbdi.h .In dev/usb/usbdi_util.h .Sh DESCRIPTION The Universal Serial Bus (USB) driver programming interface provides USB peripheral drivers with a host controller independent API for controlling and communicating with USB peripherals. The .Nm usb module supports both USB Host and USB Device side mode. . .Sh USB KERNEL PROGRAMMING Here is a list of commonly used functions: .Pp . .Ft "usb_error_t" .Fo "usbd_transfer_setup" .Fa "udev" .Fa "ifaces" .Fa "pxfer" .Fa "setup_start" .Fa "n_setup" .Fa "priv_sc" .Fa "priv_mtx" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_unsetup" .Fa "pxfer" .Fa "n_setup" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_start" .Fa "xfer" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_stop" .Fa "xfer" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_drain" .Fa "xfer" .Fc . . . .Sh USB TRANSFER MANAGEMENT FUNCTIONS The USB standard defines four types of USB transfers. . Control transfers, Bulk transfers, Interrupt transfers and Isochronous transfers. . All the transfer types are managed using the following five functions: . .Pp . .Fn usbd_transfer_setup This function will allocate memory for and initialise an array of USB transfers and all required DMA memory. . This function can sleep or block waiting for resources to become available. .Fa udev is a pointer to "struct usb_device". .Fa ifaces is an array of interface index numbers to use. See "if_index". .Fa pxfer is a pointer to an array of USB transfer pointers that are initialized to NULL, and then pointed to allocated USB transfers. .Fa setup_start is a pointer to an array of USB config structures. .Fa n_setup is a number telling the USB system how many USB transfers should be setup. .Fa priv_sc is the private softc pointer, which will be used to initialize "xfer->priv_sc". .Fa priv_mtx is the private mutex protecting the transfer structure and the softc. This pointer is used to initialize "xfer->priv_mtx". This function returns zero upon success. A non-zero return value indicates failure. . .Pp . .Fn usbd_transfer_unsetup This function will release the given USB transfers and all allocated -resources associated with these USB transfers. +resources associated with these USB transfers. .Fa pxfer is a pointer to an array of USB transfer pointers, that may be NULL, that should be freed by the USB system. .Fa n_setup is a number telling the USB system how many USB transfers should be unsetup. . This function can sleep waiting for USB transfers to complete. . This function is NULL safe with regard to the USB transfer structure pointer. . It is not allowed to call this function from the USB transfer callback. . .Pp . .Fn usbd_transfer_start This function will start the USB transfer pointed to by .Fa xfer, if not already started. . This function is always non-blocking and must be called with the so-called private USB mutex locked. . This function is NULL safe with regard to the USB transfer structure pointer. . .Pp . .Fn usbd_transfer_stop This function will stop the USB transfer pointed to by .Fa xfer, if not already stopped. . This function is always non-blocking and must be called with the so-called private USB mutex locked. . This function can return before the USB callback has been called. . This function is NULL safe with regard to the USB transfer structure pointer. . If the transfer was in progress, the callback will called with "USB_ST_ERROR" and "error = USB_ERR_CANCELLED". . .Pp . .Fn usbd_transfer_drain This function will stop an USB transfer, if not already stopped and wait for any additional USB hardware operations to complete. . Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can safely be freed after that this function has returned. . This function can block the caller and will not return before the USB callback has been called. . This function is NULL safe with regard to the USB transfer structure pointer. . .Sh USB TRANSFER CALLBACK . The USB callback has three states. . USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the initial state. . After the callback has been called with this state it will always be called back at a later stage in one of the other two states. . The USB callback should not restart the USB transfer in case the error cause is USB_ERR_CANCELLED. . The USB callback is protected from recursion. . That means one can start and stop whatever transfer from the callback of another transfer one desires. . Also the transfer that is currently called back. . Recursion is handled like this that when the callback that wants to recurse returns it is called one more time. . . .Pp . .Fn usbd_transfer_submit This function should only be called from within the USB callback and is used to start the USB hardware. . An USB transfer can have multiple frames consisting of one or more USB packets making up an I/O vector for all USB transfer types. . .Bd -literal -offset indent void usb_default_callback(struct usb_xfer *xfer, usb_error_t error) { int actlen; usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL); switch (USB_GET_STATE(xfer)) { - case USB_ST_SETUP: + case USB_ST_SETUP: /* * Setup xfer frame lengths/count and data */ usbd_transfer_submit(xfer); break; - case USB_ST_TRANSFERRED: - /* + case USB_ST_TRANSFERRED: + /* * Read usb frame data, if any. * "actlen" has the total length for all frames * transferred. */ break; default: /* Error */ /* - * Print error message and clear stall + * Print error message and clear stall * for example. */ break; } - /* - * Here it is safe to do something without the private + /* + * Here it is safe to do something without the private * USB mutex locked. */ return; } .Ed . .Sh USB CONTROL TRANSFERS An USB control transfer has three parts. . First the SETUP packet, then DATA packet(s) and then a STATUS packet. . The SETUP packet is always pointed to by frame 0 and the -length is set by +length is set by .Fn usbd_xfer_frame_len also if there should not be sent any SETUP packet! If an USB control transfer has no DATA stage, then the number of frames should be set to 1. . Else the default number of frames is 2. . .Bd -literal -offset indent Example1: SETUP + STATUS usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_transfer_submit(xfer); Example2: SETUP + DATA + STATUS usbd_xfer_set_frames(xfer, 2); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_xfer_set_frame_len(xfer, 1, 1); usbd_transfer_submit(xfer); Example3: SETUP + DATA + STATUS - split 1st callback: usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_transfer_submit(xfer); 2nd callback: /* IMPORTANT: frbuffers[0] must still point at the setup packet! */ usbd_xfer_set_frames(xfer, 2); usbd_xfer_set_frame_len(xfer, 0, 0); usbd_xfer_set_frame_len(xfer, 1, 1); usbd_transfer_submit(xfer); Example4: SETUP + STATUS - split 1st callback: usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS); usbd_transfer_submit(xfer); 2nd callback: usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 0); usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS); usbd_transfer_submit(xfer); .Ed .Sh USB TRANSFER CONFIG To simply the search for endpoints the .Nm usb module defines a USB config structure where it is possible to specify the characteristics of the wanted endpoint. .Bd -literal -offset indent -struct usb_config { +struct usb_config { bufsize, callback direction, endpoint, frames, index flags, interval, timeout, type, }; .Ed . .Pp .Fa type field selects the USB pipe type. . Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK, UE_ISOCHRONOUS. . The special value UE_BULK_INTR will select BULK and INTERRUPT pipes. . This field is mandatory. . .Pp .Fa endpoint field selects the USB endpoint number. . A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching endpoint. . This field is mandatory. . .Pp .Fa direction field selects the USB endpoint direction. . A value of "UE_DIR_ANY" will select the first matching endpoint. . Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT". . "UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which means that the direction will be swapped in case of USB_MODE_DEVICE. . Note that "UE_DIR_IN" refers to the data transfer direction of the "IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of the "OUT" tokens. . This field is mandatory. . .Pp .Fa interval field selects the interrupt interval. . The value of this field is given in milliseconds and is independent of device speed. . Depending on the endpoint type, this field has different meaning: .Bl -tag -width "UE_ISOCHRONOUS" .It UE_INTERRUPT "0" use the default interrupt interval based on endpoint descriptor. "Else" use the given value for polling rate. .It UE_ISOCHRONOUS "0" use default. "Else" the value is ignored. .It UE_BULK .It UE_CONTROL "0" no transfer pre-delay. "Else" a delay as given by this field in milliseconds is inserted before the hardware is started when "usbd_transfer_submit()" is called. .Pp NOTE: The transfer timeout, if any, is started after that the pre-delay has elapsed! .El . .Pp .Fa timeout field, if non-zero, will set the transfer timeout in milliseconds. If the "timeout" field is zero and the transfer type is ISOCHRONOUS a timeout of 250ms will be used. . .Pp .Fa frames field sets the maximum number of frames. If zero is specified it will yield the following results: .Bl -tag -width "UE_INTERRUPT" .It UE_BULK xfer->nframes = 1; .It UE_INTERRUPT xfer->nframes = 1; .It UE_CONTROL xfer->nframes = 2; .It UE_ISOCHRONOUS Not allowed. Will cause an error. .El . .Pp .Fa ep_index field allows you to give a number, in case more endpoints match the description, that selects which matching "ep_index" should be used. . .Pp .Fa if_index field allows you to select which of the interface numbers in the "ifaces" array parameter passed to "usbd_transfer_setup" that should be used when setting up the given USB transfer. . .Pp .Fa flags field has type "struct usb_xfer_flags" and allows one to set initial flags an USB transfer. Valid flags are: .Bl -tag -width "force_short_xfer" .It force_short_xfer This flag forces the last transmitted USB packet to be short. A short packet has a length of less than "xfer->max_packet_size", which derives from "wMaxPacketSize". This flag can be changed during operation. .It short_xfer_ok This flag allows the received transfer length, "xfer->actlen" to be less than "xfer->sumlen" upon completion of a transfer. This flag can be changed during operation. .It short_frames_ok This flag allows the reception of multiple short USB frames. This flag only has effect for BULK and INTERRUPT endpoints and if the number of frames received is greater than 1. This flag can be changed during operation. .It pipe_bof This flag causes a failing USB transfer to remain first in the PIPE queue except in the case of "xfer->error" equal to "USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue will be started until either: .Bl -tag -width "1" .It 1 The failing USB transfer is stopped using "usbd_transfer_stop()". .It 2 The failing USB transfer performs a successful transfer. .El The purpose of this flag is to avoid races when multiple transfers are queued for execution on an USB endpoint, and the first executing transfer fails leading to the need for clearing of stall for example. . In this case this flag is used to prevent the following USB transfers from being executed at the same time the clear-stall command is executed on the USB control endpoint. . This flag can be changed during operation. .Pp "BOF" is short for "Block On Failure". .Pp NOTE: This flag should be set on all BULK and INTERRUPT USB transfers which use an endpoint that can be shared between userland and kernel. . . .It proxy_buffer Setting this flag will cause that the total buffer size will be rounded up to the nearest atomic hardware transfer size. . The maximum data length of any USB transfer is always stored in the "xfer->max_data_length". . For control transfers the USB kernel will allocate additional space for the 8-bytes of SETUP header. . These 8-bytes are not counted by the "xfer->max_data_length" variable. . This flag can not be changed during operation. . . .It ext_buffer Setting this flag will cause that no data buffer will be allocated. . Instead the USB client must supply a data buffer. . This flag can not be changed during operation. . . .It manual_status Setting this flag prevents an USB STATUS stage to be appended to the end of the USB control transfer. . If no control data is transferred this flag must be cleared. . Else an error will be returned to the USB callback. . This flag is mostly useful for the USB device side. . This flag can be changed during operation. . . .It no_pipe_ok Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This flag can not be changed during operation. . . .It stall_pipe .Bl -tag -width "Device Side Mode" .It Device Side Mode Setting this flag will cause STALL pids to be sent to the endpoint belonging to this transfer before the transfer is started. . The transfer is started at the moment the host issues a clear-stall command on the STALL'ed endpoint. . This flag can be changed during operation. .It Host Side Mode Setting this flag will cause a clear-stall control request to be executed on the endpoint before the USB transfer is started. .El .Pp If this flag is changed outside the USB callback function you have to use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()" functions! This flag is automatically cleared after that the stall or clear stall has been executed. . .It pre_scale_frames If this flag is set the number of frames specified is assumed to give the buffering time in milliseconds instead of frames. During transfer setup the frames field is pre scaled with the corresponding value for the endpoint and rounded to the nearest number of frames greater than zero. This option only has effect for ISOCHRONOUS transfers. .El .Pp .Fa bufsize field sets the total buffer size in bytes. . If this field is zero, "wMaxPacketSize" will be used, multiplied by the "frames" field if the transfer type is ISOCHRONOUS. . This is useful for setting up interrupt pipes. . This field is mandatory. .Pp NOTE: For control transfers "bufsize" includes the length of the request structure. . .Pp .Fa callback pointer sets the USB callback. This field is mandatory. . . .Sh USB LINUX COMPAT LAYER The .Nm usb module supports the Linux USB API. . . .Sh SEE ALSO .Xr libusb 3 , .Xr usb 4 , .Xr usbconfig 8 .Sh STANDARDS The .Nm usb module complies with the USB 2.0 standard. .Sh HISTORY The .Nm usb module has been inspired by the NetBSD USB stack initially written by Lennart Augustsson. The .Nm usb module was written by .An Hans Petter Selasky Aq hselasky@FreeBSD.org . Index: stable/9/share/man/man9/vm_map_find.9 =================================================================== --- stable/9/share/man/man9/vm_map_find.9 (revision 237215) +++ stable/9/share/man/man9/vm_map_find.9 (revision 237216) @@ -1,127 +1,127 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson .\" 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. .\" .\" $FreeBSD$ .\" .Dd May 10, 2008 .Dt VM_MAP_FIND 9 .Os .Sh NAME .Nm vm_map_find .Nd find a free region within a map, and optionally map a vm_object .Sh SYNOPSIS .In sys/param.h .In vm/vm.h .In vm/vm_map.h .Ft int .Fo vm_map_find .Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" .Fa "vm_offset_t *addr" "vm_size_t length" "int find_space" .Fa "vm_prot_t prot" "vm_prot_t max" "int cow" .Fc .Sh DESCRIPTION The .Fn vm_map_find function attempts to find a free region in the target .Fa map , with the given .Fa length , and will also optionally create a mapping of .Fa object . .Pp The arguments .Fa offset , .Fa prot , .Fa max , and .Fa cow are passed unchanged to .Xr vm_map_insert 9 when creating the mapping, if and only if a free region is found. .Pp If .Fa object is .Pf non- Dv NULL , the reference count on the object must be incremented by the caller before calling this function to account for the new entry. .Pp If .Fa find_space is either -.Dv VMFS_ALIGNED_SPACE +.Dv VMFS_ALIGNED_SPACE or .Dv VMFS_ANY_SPACE , the function will call .Xr vm_map_findspace 9 to discover a free region. Moreover, if .Fa find_space is .Dv VMFS_ALIGNED_SPACE , the address of the free region will be optimized for the use of superpages. Otherwise, if .Fa find_space is .Dv VMFS_NO_SPACE , .Xr vm_map_insert 9 is called with the given address, .Fa addr . .Sh IMPLEMENTATION NOTES This function acquires a lock on .Fa map by calling .Xr vm_map_lock 9 , and holds it until the function returns. .Pp The search for a free region is defined to be first-fit, from the address .Fa addr onwards. .Sh RETURN VALUES The .Fn vm_map_find function returns .Dv KERN_SUCCESS if the mapping was successfully created. If space could not be found or .Fa find_space was .Dv VMFS_NO_SPACE and the given address, .Fa addr , was already mapped, .Dv KERN_NO_SPACE will be returned. If the discovered range turned out to be bogus, .Dv KERN_INVALID_ADDRESS will be returned. .Sh SEE ALSO .Xr vm_map 9 , .Xr vm_map_findspace 9 , .Xr vm_map_insert 9 , .Xr vm_map_lock 9 .Sh AUTHORS This manual page was written by .An Bruce M Simpson Aq bms@spc.org . Index: stable/9/share/man/man9/watchdog.9 =================================================================== --- stable/9/share/man/man9/watchdog.9 (revision 237215) +++ stable/9/share/man/man9/watchdog.9 (revision 237216) @@ -1,81 +1,81 @@ .\" .\" Copyright (c) 2004 Poul-Henning Kamp .\" 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 DEVELOPERS ``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 DEVELOPERS 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 28, 2004 .Dt WATCHDOG 9 .Os .Sh NAME .Nm watchdog .Nd "software and hardware watchdog facility" .Sh SYNOPSIS .In sys/watchdog.h .Ft void .Fn watchdog_fn "void *private" "u_int cmd" "int *error" .Fn EVENTHANDLER_REGISTER watchdog_list watchdog_fn private 0 .Fn EVENTHANDLER_DEREGISTER watchdog_list eventhandler_tag .Sh DESCRIPTION To implement a watchdog in software or hardware, only a single function needs to be written and registered on the global .Va watchdog_list . .Pp The function must examine the .Fa cmd argument and act on it as follows: .Pp If .Fa cmd is zero, the watchdog must be disabled and the .Fa error argument left untouched. If the watchdog cannot be disabled, the .Fa error -argument must be set to +argument must be set to .Dv EOPNOTSUPP . .Pp Else the watchdog should be reset and configured to a timeout of .Pq 1 << Pq Fa cmd No & Dv WD_INTERVAL nanoseconds or larger and the .Fa error argument be set to zero to signal arming of a watchdog. .Pp If the watchdog cannot be configured to the proposed timeout, it must be disabled and the .Fa error argument left as is (to avoid hiding the arming of another watchdog). .Pp There is no specification of what the watchdog should do when it times out, but a hardware reset or similar .Dq "drastic but certain" behaviour is recommended. .Sh SEE ALSO .Xr watchdog 4 .Sh AUTHORS .An -nosplit The .Nm facility and this manual page was written .An Poul-Henning Kamp Aq phk@FreeBSD.org . Index: stable/9/share/man/man9 =================================================================== --- stable/9/share/man/man9 (revision 237215) +++ stable/9/share/man/man9 (revision 237216) Property changes on: stable/9/share/man/man9 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/share/man/man9:r233648 Index: stable/9/sys/boot/common/loader.8 =================================================================== --- stable/9/sys/boot/common/loader.8 (revision 237215) +++ stable/9/sys/boot/common/loader.8 (revision 237216) @@ -1,1067 +1,1067 @@ .\" Copyright (c) 1999 Daniel C. Sobral .\" 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. .\" .\" $FreeBSD$ .\" .Dd January 7, 2012 .Dt LOADER 8 .Os .Sh NAME .Nm loader .Nd kernel bootstrapping final stage .Sh DESCRIPTION The program called .Nm is the final stage of .Fx Ns 's kernel bootstrapping process. On IA32 (i386) architectures, it is a .Pa BTX client. It is linked statically to .Xr libstand 3 and usually located in the directory .Pa /boot . .Pp It provides a scripting language that can be used to automate tasks, do pre-configuration or assist in recovery procedures. This scripting language is roughly divided in two main components. The smaller one is a set of commands designed for direct use by the casual user, called "builtin commands" for historical reasons. The main drive behind these commands is user-friendliness. The bigger component is an .Tn ANS Forth compatible Forth interpreter based on FICL, by .An John Sadler . .Pp During initialization, .Nm will probe for a console and set the .Va console variable, or set it to serial console .Pq Dq Li comconsole if the previous boot stage used that. If multiple consoles are selected, they will be listed separated by spaces. Then, devices are probed, .Va currdev and .Va loaddev are set, and .Va LINES is set to 24. Next, .Tn FICL is initialized, the builtin words are added to its vocabulary, and .Pa /boot/boot.4th is processed if it exists. No disk switching is possible while that file is being read. The inner interpreter .Nm will use with .Tn FICL is then set to .Ic interpret , which is .Tn FICL Ns 's default. After that, .Pa /boot/loader.rc is processed if available, and, failing that, .Pa /boot/boot.conf is read for historical reasons. These files are processed through the .Ic include command, which reads all of them into memory before processing them, making disk changes possible. .Pp At this point, if an .Ic autoboot has not been tried, and if .Va autoboot_delay is not set to .Dq Li NO (not case sensitive), then an .Ic autoboot will be tried. If the system gets past this point, .Va prompt will be set and .Nm will engage interactive mode. Please note that historically even when .Va autoboot_delay is set to .Dq Li 0 user will be able to interrupt autoboot process by pressing some key on the console while kernel and modules are being loaded. In some cases such behaviour may be undesirable, to prevent it set .Va autoboot_delay to .Dq Li -1 , in this case .Nm will engage interactive mode only if .Ic autoboot has failed. .Sh BUILTIN COMMANDS In .Nm , builtin commands take parameters from the command line. Presently, the only way to call them from a script is by using .Pa evaluate on a string. If an error condition occurs, an exception will be generated, which can be intercepted using .Tn ANS Forth exception handling words. If not intercepted, an error message will be displayed and the interpreter's state will be reset, emptying the stack and restoring interpreting mode. .Pp The builtin commands available are: .Pp .Bl -tag -width Ds -compact .It Ic autoboot Op Ar seconds Op Ar prompt Proceeds to bootstrap the system after a number of seconds, if not interrupted by the user. Displays a countdown prompt warning the user the system is about to be booted, unless interrupted by a key press. The kernel will be loaded first if necessary. Defaults to 10 seconds. .Pp .It Ic bcachestat Displays statistics about disk cache usage. For debugging only. .Pp .It Ic boot .It Ic boot Ar kernelname Op Cm ... .It Ic boot Fl flag Cm ... Immediately proceeds to bootstrap the system, loading the kernel if necessary. Any flags or arguments are passed to the kernel, but they must precede the kernel name, if a kernel name is provided. .Pp .Em WARNING : The behavior of this builtin is changed if .Xr loader.4th 8 is loaded. .Pp .It Ic echo Xo .Op Fl n .Op Aq message .Xc Displays text on the screen. A new line will be printed unless .Fl n is specified. .Pp .It Ic heap Displays memory usage statistics. For debugging purposes only. .Pp .It Ic help Op topic Op subtopic Shows help messages read from .Pa /boot/loader.help . The special topic .Em index will list the topics available. .Pp .It Ic include Ar file Op Ar Process script files. Each file, in turn, is completely read into memory, and then each of its lines is passed to the command line interpreter. If any error is returned by the interpreter, the include command aborts immediately, without reading any other files, and returns an error itself (see .Sx ERRORS ) . .Pp .It Ic load Xo .Op Fl t Ar type .Ar file Cm ... .Xc Loads a kernel, kernel loadable module (kld), or file of opaque contents tagged as being of the type .Ar type . Kernel and modules can be either in a.out or ELF format. Any arguments passed after the name of the file to be loaded will be passed as arguments to that file. Currently, argument passing does not work for the kernel. .Pp .It Ic load_geli Xo .Op Fl n Ar keyno .Ar prov Ar file .Xc Loads a .Xr geli 8 encryption keyfile for the given provider name. The key index can be specified via -.Ar keyno +.Ar keyno or will default to zero. .Pp .It Ic ls Xo .Op Fl l .Op Ar path .Xc Displays a listing of files in the directory .Ar path , or the root directory if .Ar path is not specified. If .Fl l is specified, file sizes will be shown too. .Pp .It Ic lsdev Op Fl v Lists all of the devices from which it may be possible to load modules. If .Fl v is specified, more details are printed. .Pp .It Ic lsmod Op Fl v Displays loaded modules. If .Fl v is specified, more details are shown. .Pp .It Ic more Ar file Op Ar Display the files specified, with a pause at each .Va LINES displayed. .Pp .It Ic pnpscan Op Fl v Scans for Plug-and-Play devices. This is not functional at present. .Pp .It Ic read Xo .Op Fl t Ar seconds .Op Fl p Ar prompt .Op Va variable .Xc Reads a line of input from the terminal, storing it in .Va variable if specified. A timeout can be specified with .Fl t , though it will be canceled at the first key pressed. A prompt may also be displayed through the .Fl p flag. .Pp .It Ic reboot Immediately reboots the system. .Pp .It Ic set Ar variable .It Ic set Ar variable Ns = Ns Ar value Set loader's environment variables. .Pp .It Ic show Op Va variable Displays the specified variable's value, or all variables and their values if .Va variable is not specified. .Pp .It Ic unload Remove all modules from memory. .Pp .It Ic unset Va variable Removes .Va variable from the environment. .Pp .It Ic \&? Lists available commands. .El .Ss BUILTIN ENVIRONMENT VARIABLES The .Nm has actually two different kinds of .Sq environment variables. There are ANS Forth's .Em environmental queries , and a separate space of environment variables used by builtins, which are not directly available to Forth words. It is the latter type that this section covers. .Pp Environment variables can be set and unset through the .Ic set and .Ic unset builtins, and can have their values interactively examined through the use of the .Ic show builtin. Their values can also be accessed as described in .Sx BUILTIN PARSER . .Pp Notice that these environment variables are not inherited by any shell after the system has been booted. .Pp A few variables are set automatically by .Nm . Others can affect the behavior of either .Nm or the kernel at boot. Some options may require a value, while others define behavior just by being set. Both types of builtin variables are described below. .Bl -tag -width bootfile .It Va autoboot_delay Number of seconds .Ic autoboot will wait before booting. If this variable is not defined, .Ic autoboot will default to 10 seconds. .Pp If set to .Dq Li NO , no .Ic autoboot will be automatically attempted after processing .Pa /boot/loader.rc , though explicit .Ic autoboot Ns 's will be processed normally, defaulting to 10 seconds delay. .Pp If set to .Dq Li 0 , no delay will be inserted, but user still will be able to interrupt .Ic autoboot process and escape into the interactive mode by pressing some key on the console while kernel and modules are being loaded. .Pp If set to .Dq Li -1 , no delay will be inserted and .Nm will engage interactive mode only if .Ic autoboot has failed for some reason. .It Va boot_askname Instructs the kernel to prompt the user for the name of the root device when the kernel is booted. .It Va boot_cdrom Instructs the kernel to try to mount the root file system from CD-ROM. .It Va boot_ddb Instructs the kernel to start in the DDB debugger, rather than proceeding to initialize when booted. .It Va boot_dfltroot Instructs the kernel to mount the statically compiled-in root file system. .It Va boot_gdb Selects gdb-remote mode for the kernel debugger by default. .It Va boot_multicons Enables multiple console support in the kernel early on boot. In a running system, console configuration can be manipulated by the .Xr conscontrol 8 utility. .It Va boot_mute All console output is suppressed when console is muted. In a running system, the state of console muting can be manipulated by the .Xr conscontrol 8 utility. .It Va boot_pause During the device probe, pause after each line is printed. .It Va boot_serial Force the use of a serial console even when an internal console is present. .It Va boot_single Prevents the kernel from initiating a multi-user startup; instead, a single-user mode will be entered when the kernel has finished device probing. .It Va boot_verbose Setting this variable causes extra debugging information to be printed by the kernel during the boot phase. .It Va bootfile List of semicolon-separated search path for bootable kernels. The default is .Dq Li kernel . .It Va comconsole_speed Defines the speed of the serial console (i386 and amd64 only). If the previous boot stage indicated that a serial console is in use then this variable is initialized to the current speed of the console serial port. Otherwise it is set to 9600 unless this was overridden using the .Va BOOT_COMCONSOLE_SPEED variable when .Nm was compiled. Changes to the .Va comconsole_speed variable take effect immediately. .It Va comconsole_port Defines the base i/o port used to access console UART (i386 and amd64 only). If the variable is not set, its assumed value is 0x3F8, which corresponds to PC port COM1, unless overriden by .Va BOOT_COMCONSOLE_PORT variable during the compilation of .Nm . Setting the .Va comconsole_port variable automatically set .Va hw.uart.console environment variable to provide a hint to kernel for location of the console. Loader console is changed immediately after variable .Va comconsole_port is set. .It Va comconsole_pcidev Defines the location of a PCI device of the 'simple communication' class to be used as the serial console UART (i386 and amd64 only). The syntax of the variable is .Li 'bus:device:function[:bar]' , where all members must be numeric, with possible .Li 0x prefix to indicate a hexadecimal value. The .Va bar member is optional and assumed to be 0x10 if omitted. The bar must decode i/o space. Setting the variable .Va comconsole_pcidev automatically sets the variable .Va comconsole_port to the base of the selected bar, and hint .Va hw.uart.console . Loader console is changed immediately after variable .Va comconsole_pcidev is set. .It Va console Defines the current console or consoles. Multiple consoles may be specified. In that case, the first listed console will become the default console for userland output (e.g.\& from .Xr init 8 ) . .It Va currdev Selects the default device. Syntax for devices is odd. .It Va init_chroot If set to a valid directory in the root file system, it causes .Xr init 8 to perform a .Xr chroot 2 operation on that directory, making it the new root directory. That happens before entering single-user mode or multi-user mode (but after executing the .Va init_script if enabled). .It Va init_path Sets the list of binaries which the kernel will try to run as the initial process. The first matching binary is used. The default list is .Dq Li /sbin/init:/sbin/oinit:/sbin/init.bak:\:/rescue/init:/stand/sysinstall . .It Va init_script If set to a valid file name in the root file system, instructs .Xr init 8 to run that script as the very first action, before doing anything else. Signal handling and exit code interpretation is similar to running the .Pa /etc/rc script. In particular, single-user operation is enforced if the script terminates with a non-zero exit code, or if a SIGTERM is delivered to the .Xr init 8 process (PID 1). .It Va init_shell Defines the shell binary to be used for executing the various shell scripts. The default is .Dq Li /bin/sh . It is used for running the .Va init_script if set, as well as for the .Pa /etc/rc and .Pa /etc/rc.shutdown scripts. The value of the corresponding .Xr kenv 2 variable is evaluated every time .Xr init 8 calls a shell script, so it can be changed later on using the .Xr kenv 1 utility. In particular, if a non-default shell is used for running an .Va init_script , it might be desirable to have that script reset the value of .Va init_shell back to the default, so that the .Pa /etc/rc script is executed with the standard shell .Pa /bin/sh . .It Va interpret Has the value .Dq Li OK if the Forth's current state is interpreting. .It Va LINES Define the number of lines on the screen, to be used by the pager. .It Va module_path Sets the list of directories which will be searched for modules named in a load command or implicitly required by a dependency. The default value for this variable is .Dq Li /boot/kernel;/boot/modules . .It Va num_ide_disks Sets the number of IDE disks as a workaround for some problems in finding the root disk at boot. This has been deprecated in favor of .Va root_disk_unit . .It Va prompt Value of .Nm Ns 's prompt. Defaults to .Dq Li "${interpret}" . If variable .Va prompt is unset, the default prompt is .Ql > . .It Va root_disk_unit If the code which detects the disk unit number for the root disk is confused, e.g.\& by a mix of SCSI and IDE disks, or IDE disks with gaps in the sequence (e.g.\& no primary slave), the unit number can be forced by setting this variable. .It Va rootdev By default the value of .Va currdev is used to set the root file system when the kernel is booted. This can be overridden by setting .Va rootdev explicitly. .El .Pp Other variables are used to override kernel tunable parameters. The following tunables are available: .Bl -tag -width Va .It Va hw.physmem Limit the amount of physical memory the system will use. By default the size is in bytes, but the .Cm k , K , m , M , g and .Cm G suffixes are also accepted and indicate kilobytes, megabytes and gigabytes respectively. An invalid suffix will result in the variable being ignored by the kernel. .It Va hw.pci.host_start_mem , hw.acpi.host_start_mem When not otherwise constrained, this limits the memory start address. The default is 0x80000000 and should be set to at least size of the memory and not conflict with other resources. Typically, only systems without PCI bridges need to set this variable since PCI bridges typically constrain the memory starting address (and the variable is only used when bridges do not constrain this address). .It Va hw.pci.enable_io_modes Enable PCI resources which are left off by some BIOSes or are not enabled correctly by the device driver. Tunable value set to ON (1) by default, but this may cause problems with some peripherals. .It Va kern.maxusers Set the size of a number of statically allocated system tables; see .Xr tuning 7 for a description of how to select an appropriate value for this tunable. When set, this tunable replaces the value declared in the kernel compile-time configuration file. .It Va kern.ipc.nmbclusters Set the number of mbuf clusters to be allocated. The value cannot be set below the default determined when the kernel was compiled. .It Va kern.ipc.nsfbufs Set the number of .Xr sendfile 2 buffers to be allocated. Overrides .Dv NSFBUFS . Not all architectures use such buffers; see .Xr sendfile 2 for details. .It Va kern.maxswzone Limits the amount of KVM to be used to hold swap meta information, which directly governs the maximum amount of swap the system can support. This value is specified in bytes of KVA space and defaults to 32MBytes on i386 and amd64. Care should be taken to not reduce this value such that the actual amount of configured swap exceeds 1/2 the kernel-supported swap. The default of 32MB allows the kernel to support a maximum of ~7GB of swap. Only change this parameter if you need to greatly extend the KVM reservation for other resources such as the buffer cache or .Va kern.ipc.nmbclusters . Modifies kernel option .Dv VM_SWZONE_SIZE_MAX . .It Va kern.maxbcache Limits the amount of KVM reserved for use by the buffer cache, specified in bytes. The default maximum is 200MB on i386, and 400MB on amd64 and sparc64. This parameter is used to prevent the buffer cache from eating too much KVM in large-memory machine configurations. Only mess around with this parameter if you need to greatly extend the KVM reservation for other resources such as the swap zone or .Va kern.ipc.nmbclusters . Note that the NBUF parameter will override this limit. Modifies .Dv VM_BCACHE_SIZE_MAX . .It Va kern.msgbufsize Sets the size of the kernel message buffer. The default limit of 64KB is usually sufficient unless large amounts of trace data need to be collected between opportunities to examine the buffer or dump it to a file. Overrides kernel option .Dv MSGBUF_SIZE . .It Va machdep.disable_mtrrs Disable the use of i686 MTRRs (x86 only). .It Va net.inet.tcp.tcbhashsize Overrides the compile-time set value of .Dv TCBHASHSIZE or the preset default of 512. Must be a power of 2. .It Va vm.kmem_size Sets the size of kernel memory (bytes). This overrides the value determined when the kernel was compiled. Modifies .Dv VM_KMEM_SIZE . .It Va vm.kmem_size_min .It Va vm.kmem_size_max Sets the minimum and maximum (respectively) amount of kernel memory that will be automatically allocated by the kernel. These override the values determined when the kernel was compiled. Modifies .Dv VM_KMEM_SIZE_MIN and .Dv VM_KMEM_SIZE_MAX . .El .Ss BUILTIN PARSER When a builtin command is executed, the rest of the line is taken by it as arguments, and it is processed by a special parser which is not used for regular Forth commands. .Pp This special parser applies the following rules to the parsed text: .Bl -enum .It All backslash characters are preprocessed. .Bl -bullet .It \eb , \ef , \er , \en and \et are processed as in C. .It \es is converted to a space. .It \ev is converted to .Tn ASCII 11. .It \ez is just skipped. Useful for things like .Dq \e0xf\ez\e0xf . .It \e0xN and \e0xNN are replaced by the hex N or NN. .It \eNNN is replaced by the octal NNN .Tn ASCII character. .It \e" , \e' and \e$ will escape these characters, preventing them from receiving special treatment in Step 2, described below. .It \e\e will be replaced with a single \e . .It In any other occurrence, backslash will just be removed. .El .It Every string between non-escaped quotes or double-quotes will be treated as a single word for the purposes of the remaining steps. .It Replace any .Li $VARIABLE or .Li ${VARIABLE} with the value of the environment variable .Va VARIABLE . .It Space-delimited arguments are passed to the called builtin command. Spaces can also be escaped through the use of \e\e . .El .Pp An exception to this parsing rule exists, and is described in .Sx BUILTINS AND FORTH . .Ss BUILTINS AND FORTH All builtin words are state-smart, immediate words. If interpreted, they behave exactly as described previously. If they are compiled, though, they extract their arguments from the stack instead of the command line. .Pp If compiled, the builtin words expect to find, at execution time, the following parameters on the stack: .D1 Ar addrN lenN ... addr2 len2 addr1 len1 N where .Ar addrX lenX are strings which will compose the command line that will be parsed into the builtin's arguments. Internally, these strings are concatenated in from 1 to N, with a space put between each one. .Pp If no arguments are passed, a 0 .Em must be passed, even if the builtin accepts no arguments. .Pp While this behavior has benefits, it has its trade-offs. If the execution token of a builtin is acquired (through .Ic ' or .Ic ['] ) , and then passed to .Ic catch or .Ic execute , the builtin behavior will depend on the system state .Bf Em at the time .Ic catch or .Ic execute is processed! .Ef This is particularly annoying for programs that want or need to handle exceptions. In this case, the use of a proxy is recommended. For example: .Dl : (boot) boot ; .Sh FICL .Tn FICL is a Forth interpreter written in C, in the form of a forth virtual machine library that can be called by C functions and vice versa. .Pp In .Nm , each line read interactively is then fed to .Tn FICL , which may call .Nm back to execute the builtin words. The builtin .Ic include will also feed .Tn FICL , one line at a time. .Pp The words available to .Tn FICL can be classified into four groups. The .Tn ANS Forth standard words, extra .Tn FICL words, extra .Fx words, and the builtin commands; the latter were already described. The .Tn ANS Forth standard words are listed in the .Sx STANDARDS section. The words falling in the two other groups are described in the following subsections. .Ss FICL EXTRA WORDS .Bl -tag -width wid-set-super .It Ic .env .It Ic .ver .It Ic -roll .It Ic 2constant .It Ic >name .It Ic body> .It Ic compare This is the STRING word set's .Ic compare . .It Ic compile-only .It Ic endif .It Ic forget-wid .It Ic parse-word .It Ic sliteral This is the STRING word set's .Ic sliteral . .It Ic wid-set-super .It Ic w@ .It Ic w! .It Ic x. .It Ic empty .It Ic cell- .It Ic -rot .El .Ss FREEBSD EXTRA WORDS .Bl -tag -width XXXXXXXX .It Ic \&$ Pq -- Evaluates the remainder of the input buffer, after having printed it first. .It Ic \&% Pq -- Evaluates the remainder of the input buffer under a .Ic catch exception guard. .It Ic .# Works like .Ic "." but without outputting a trailing space. .It Ic fclose Pq Ar fd -- Closes a file. .It Ic fkey Pq Ar fd -- char Reads a single character from a file. .It Ic fload Pq Ar fd -- Processes a file .Em fd . .It Ic fopen Pq Ar addr len mode Li -- Ar fd Opens a file. Returns a file descriptor, or \-1 in case of failure. The .Ar mode parameter selects whether the file is to be opened for read access, write access, or both. The constants .Dv O_RDONLY , O_WRONLY , and .Dv O_RDWR are defined in .Pa /boot/support.4th , indicating read only, write only, and read-write access, respectively. .It Xo .Ic fread .Pq Ar fd addr len -- len' .Xc Tries to read .Em len bytes from file .Em fd into buffer .Em addr . Returns the actual number of bytes read, or -1 in case of error or end of file. .It Ic heap? Pq -- Ar cells Return the space remaining in the dictionary heap, in cells. This is not related to the heap used by dynamic memory allocation words. .It Ic inb Pq Ar port -- char Reads a byte from a port. .It Ic key Pq -- Ar char Reads a single character from the console. .It Ic key? Pq -- Ar flag Returns .Ic true if there is a character available to be read from the console. .It Ic ms Pq Ar u -- Waits .Em u microseconds. .It Ic outb Pq Ar port char -- Writes a byte to a port. .It Ic seconds Pq -- Ar u Returns the number of seconds since midnight. .It Ic tib> Pq -- Ar addr len Returns the remainder of the input buffer as a string on the stack. .It Ic trace! Pq Ar flag -- Activates or deactivates tracing. Does not work with .Ic catch . .El .Ss FREEBSD DEFINED ENVIRONMENTAL QUERIES .Bl -tag -width Ds .It arch-i386 .Ic TRUE if the architecture is IA32. .It FreeBSD_version .Fx version at compile time. .It loader_version .Nm version. .El .Ss SYSTEM DOCUMENTATION .Sh FILES .Bl -tag -width /boot/defaults/loader.conf -compact .It Pa /boot/loader .Nm itself. .It Pa /boot/boot.4th Additional .Tn FICL initialization. .It Pa /boot/boot.conf .Nm bootstrapping script. Deprecated. .It Pa /boot/defaults/loader.conf .It Pa /boot/loader.conf .It Pa /boot/loader.conf.local .Nm configuration files, as described in .Xr loader.conf 5 . .It Pa /boot/loader.rc .Nm bootstrapping script. .It Pa /boot/loader.help Loaded by .Ic help . Contains the help messages. .El .Sh EXAMPLES Boot in single user mode: .Pp .Dl boot -s .Pp Load the kernel, a splash screen, and then autoboot in five seconds. Notice that a kernel must be loaded before any other .Ic load command is attempted. .Bd -literal -offset indent load kernel load splash_bmp load -t splash_image_data /boot/chuckrulez.bmp autoboot 5 .Ed .Pp Set the disk unit of the root device to 2, and then boot. This would be needed in a system with two IDE disks, with the second IDE disk hardwired to ad2 instead of ad1. .Bd -literal -offset indent set root_disk_unit=2 boot /boot/kernel/kernel .Ed .Pp See also: .Bl -tag -width /usr/share/examples/bootforth/X .It Pa /boot/loader.4th Extra builtin-like words. .It Pa /boot/support.4th .Pa loader.conf processing words. .It Pa /usr/share/examples/bootforth/ Assorted examples. .El .Sh ERRORS The following values are thrown by .Nm : .Bl -tag -width XXXXX -offset indent .It 100 Any type of error in the processing of a builtin. .It -1 .Ic Abort executed. .It -2 .Ic Abort" executed. .It -56 .Ic Quit executed. .It -256 Out of interpreting text. .It -257 Need more text to succeed -- will finish on next run. .It -258 .Ic Bye executed. .It -259 Unspecified error. .El .Sh SEE ALSO .Xr libstand 3 , .Xr loader.conf 5 , .Xr tuning 7 , .Xr boot 8 , .Xr btxld 8 .Sh STANDARDS For the purposes of ANS Forth compliance, loader is an .Bf Em ANS Forth System with Environmental Restrictions, Providing .Ef .Bf Li .No .( , .No :noname , .No ?do , parse, pick, roll, refill, to, value, \e, false, true, .No <> , .No 0<> , compile\&, , erase, nip, tuck .Ef .Em and .Li marker .Bf Em from the Core Extensions word set, Providing the Exception Extensions word set, Providing the Locals Extensions word set, Providing the Memory-Allocation Extensions word set, Providing .Ef .Bf Li \&.s, bye, forget, see, words, \&[if], \&[else] .Ef .Em and .Li [then] .Bf Em from the Programming-Tools extension word set, Providing the Search-Order extensions word set. .Ef .Sh HISTORY The .Nm first appeared in .Fx 3.1 . .Sh AUTHORS .An -nosplit The .Nm was written by .An Michael Smith Aq msmith@FreeBSD.org . .Pp .Tn FICL was written by .An John Sadler Aq john_sadler@alum.mit.edu . .Sh BUGS The .Ic expect and .Ic accept words will read from the input buffer instead of the console. The latter will be fixed, but the former will not. Index: stable/9/sys/boot/forth/loader.conf.5 =================================================================== --- stable/9/sys/boot/forth/loader.conf.5 (revision 237215) +++ stable/9/sys/boot/forth/loader.conf.5 (revision 237216) @@ -1,272 +1,272 @@ .\" Copyright (c) 1999 Daniel C. Sobral .\" 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. .\" .\" $FreeBSD$ .Dd July 20, 2011 .Dt LOADER.CONF 5 .Os .Sh NAME .Nm loader.conf .Nd "system bootstrap configuration information" .Sh DESCRIPTION The file .Nm contains descriptive information on bootstrapping the system. Through it you can specify the kernel to be booted, parameters to be passed to it, and additional modules to be loaded; and generally set all variables described in .Xr loader 8 . .Pp The file .Pa /boot/loader.rc must contain the following two lines for .Nm to be automatically processed: .Pp .Dl include /boot/loader.4th .Dl start .Pp If no .Pa /boot/loader.rc exists at installworld time, one with the above lines will be installed. .Sh SYNTAX Though .Nm Ns 's format was defined explicitly to resemble .Xr rc.conf 5 , and can be sourced by .Xr sh 1 , some settings are treated in a special fashion. Also, the behavior of some settings is defined by the setting's suffix; the prefix identifies which module the setting controls. .Pp The general parsing rules are: .Bl -bullet .It Spaces and empty lines are ignored. .It A # sign will mark the remainder of the line as a comment. .It Only one setting can be present on each line. .El .Pp All settings have the following format: .Pp .Dl variable="value" .Pp Unless it belongs to one of the classes of settings that receive special treatment, a setting will set the value of a .Xr loader 8 environment variable. The settings that receive special treatment are listed below. Settings beginning with .Qq * below define the modules to be loaded and may have any prefix; the prefix identifies a module. All such settings sharing a common prefix refer to the same module. .Bl -tag -width Ar .It Ar exec Immediately executes a .Xr loader 8 command. This type of setting cannot be processed by programs other than .Xr loader 8 , so its use should be avoided. Multiple instances of it will be processed independently. .It Ar loader_conf_files Defines additional configuration files to be processed right after the present file. .It Ar kernel Name of the kernel to be loaded. If no kernel name is set, no additional modules will be loaded. The name must be a subdirectory of .Pa /boot that contains a kernel. .It Ar kernel_options Flags to be passed to the kernel. .It Ar password Provides a password to be required by check-password before execution is allowed to continue. .It Ar verbose_loading If set to .Dq YES , module names will be displayed as they are loaded. .It Ar *_load If set to .Dq YES , that module will be loaded. If no name is defined (see below), the module's name is taken to be the same as the prefix. .It Ar *_name Defines the name of the module. .It Ar *_type Defines the module's type. If none is given, it defaults to a kld module. .It Ar *_flags Flags and parameters to be passed to the module. .It Ar *_before Commands to be executed before the module is loaded. Use of this setting should be avoided. .It Ar *_after Commands to be executed after the module is loaded. Use of this setting should be avoided. .It Ar *_error Commands to be executed if the loading of a module fails. Except for the special value .Dq abort , which aborts the bootstrap process, use of this setting should be avoided. .El .Pp .Em WARNING: developers should never use these suffixes for any kernel environment variables (tunables) or conflicts will result. .Sh DEFAULT SETTINGS Most of .Nm Ns 's default settings can be ignored. The few of them which are important or useful are: .Bl -tag -width bootfile -offset indent .It Va bitmap_load .Pq Dq NO If set to .Dq YES , a bitmap will be loaded to be displayed on screen while booting. .It Va bitmap_name .Pq Dq Pa /boot/splash.bmp Name of the bitmap to be loaded. Any other name can be used. .It Va comconsole_speed .Dq ( 9600 or the value of the .Va BOOT_COMCONSOLE_SPEED variable when .Xr loader 8 was compiled). Sets the speed of the serial console. If the previous boot loader stage specified that a serial console is in use then the default speed is determined from the current serial port speed setting. .It Va console .Pq Dq vidconsole .Dq comconsole selects serial console, .Dq vidconsole selects the video console, .Dq nullconsole selects a mute console (useful for systems with neither a video console nor a serial port), and .Dq spinconsole selects the video console which prevents any input and hides all output replacing it with .Dq spinning character (useful for embedded products and such). .It Va kernel .Pq Dq kernel .It Va loader_conf_files .Pq Dq Pa /boot/loader.conf /boot/loader.conf.local .It Va splash_bmp_load .Pq Dq NO If set to .Dq YES , will load the splash screen module, making it possible to display a bmp image on the screen while booting. .It Va splash_pcx_load .Pq Dq NO If set to .Dq YES , will load the splash screen module, making it possible to display a pcx image on the screen while booting. .It Va vesa_load .Pq Dq NO If set to .Dq YES , the vesa module will be loaded, enabling bitmaps above VGA resolution to be displayed. .It Va beastie_disable If set to .Dq YES , the beastie boot menu will be skipped. .It Va loader_logo Pq Dq Li orbbw Selects a desired logo in the beastie boot menu. Possible values are: .Dq Li orbbw , .Dq Li orb , .Dq Li fbsdbw , .Dq Li beastiebw , .Dq Li beastie , and .Dq Li none . .It Va loader_color If set to .Dq YES , the beastie boot menu will be displayed using ANSI coloring where possible. .El .Sh FILES .Bl -tag -width /boot/defaults/loader.conf -compact .It Pa /boot/defaults/loader.conf default settings -- do not change this file. .It Pa /boot/loader.4th defines the commands used by loader to read and process .Nm . .It Pa /boot/loader.conf user defined settings. .It Pa /boot/loader.conf.local machine-specific settings for sites with a common loader.conf. .It Pa /boot/loader.rc contains the instructions to automatically process .Nm . .El .Sh SEE ALSO .Xr boot 8 , .Xr loader 8 , .Xr loader.4th 8 .Sh HISTORY The file .Nm first appeared in .Fx 3.2 . .Sh AUTHORS This manual page was written by .An Daniel C. Sobral Aq dcs@FreeBSD.org . .Sh BUGS The .Xr loader 8 stops reading .Nm when it encounters a syntax error, so any options which are vital for -booting a particular system (i.e.\& +booting a particular system (i.e.\& .Dq Va hw.ata.ata_dma Ns "=0" ) should precede any experimental additions to .Nm . Index: stable/9/sys/boot =================================================================== --- stable/9/sys/boot (revision 237215) +++ stable/9/sys/boot (revision 237216) Property changes on: stable/9/sys/boot ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sys/boot:r233648 Index: stable/9/sys =================================================================== --- stable/9/sys (revision 237215) +++ stable/9/sys (revision 237216) Property changes on: stable/9/sys ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/sys:r233648 Index: stable/9/tools/tools/ath/athrd/athrd.1 =================================================================== --- stable/9/tools/tools/ath/athrd/athrd.1 (revision 237215) +++ stable/9/tools/tools/ath/athrd/athrd.1 (revision 237216) @@ -1,172 +1,172 @@ .\"- .\" Copyright (c) 2002-2009 Sam Leffler, Errno Consulting .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any .\" redistribution must be conditioned upon including a substantially .\" similar Disclaimer requirement for further binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. .\" .\" $FreeBSD$ .\"/ .Dd January 27, 2009 .Dt ATHRD 1 .Os .Sh NAME .Nm athrd .Nd list channels and transmit power for a country/regulatory domain .Sh SYNOPSIS .Nm .Op Fl aedlpcfr4ABGT .Op Fl m Ar mode .Bk .Op Ar country .Ek .Sh DESCRIPTION .Nm displays the list of frequencies and the associated maximum transmit power permitted within a regulatory domain and/or country. .Pp If no command line options are given, a default country (\c .Ql US ) is used. Country and regulatory names are case insensitive. .Pp The following options are available: .Bl -tag -width indent .It Fl a By default .Nm will display B channels only if they are not also marked as available for use as G channels and similary for A and T channels. With this option .Nm will list all channels. .It Fl e Calculate channels not assuming extended channel mode. .It Fl d Enabling debugging in the HAL code that calculates the available channels and transmit power values. .It Fl l Provide a list of all known country and regulatory domain names. .It Fl m Ar mode Calculate channels and transmit power for operation in .Ql mode ; one of .Ql station , .Ql ibss , .Ql monitor , and .Ql ap (or the first two letters). .It Fl p Mark passive scan channels with lower case letters and active scan channels with upper case letters. .It Fl r -Mark channels that require DFS with a +Mark channels that require DFS with a .Ql * . .It Fl 4 -Mark channels that have a 4ms packet limit with a +Mark channels that have a 4ms packet limit with a .Ql 4 . .It Fl c Display IEEE channel numbers instead of frequencies. .It Fl f Display frequencies (default). .It Fl A Display only 11A channels. .It Fl B Display only 11B channels. .It Fl G Display only 11G channels. .It Fl T Display only Turbo channels. .El .Sh EXAMPLES The following demonstrates how to list the permissible frequencies and maximum transport power per channel for use in Spain: .Pp .nf tubby% athrd es \& SPAIN (ES, 0x2d4, 724) NULL1_WORLD (0x3, 3) 2412G 14.0 2417G 14.0 2422G 14.0 2427G 17.0 2432G 14.0 2437G 17.0 2442G 14.0 2447G 17.0 2452G 17.0 2457G 14.0 2462G 17.0 .fi .Pp Each frequency has a suffix that is one of: .Ql G , .Ql B , .Ql A , or -.Ql T +.Ql T according to whether the channel is usable with 802.11g, 802.11b, 802.11a, or Atheros Turbo mode. -All channels listed as +All channels listed as .Ql G are also usable in .Ql B . Likewise, all channels listed as .Ql A are usable in .Ql T . Channels listed as .Ql B or .Ql T are only usable in those modes. (Note that when the .Fl p option is specified passive scan channels are marked with a lower case .Ql g , .Ql b , .Ql a , or .Ql t .) The transmit power is given in units of dbM. .Sh DIAGNOSTICS Various diagnostics about unknown regulatory domains and/or country codes may be encountered. Use the .Fl l option for a list of valid names. .Sh SEE ALSO .Xr ath 4 , .Xr ath_hal 4 .Sh STANDARDS Lots belong here. .Sh NOTES .Nm use the HAL to calculate the set of channels. The transmit power calculations are done by emulating how the HAL works. -Because +Because .Nm does not read the actual EEPROM contents from a device this emulation may lag behind current practice. .Sh BUGS The HAL reset logic should be used to calculate the transmit power for each channel instead of using a separate copy of the code. The data presented by .Nm are the expected values; for compliance testing one must measure the actual operation of the driver and the HAL. Index: stable/9/tools/tools/ath =================================================================== --- stable/9/tools/tools/ath (revision 237215) +++ stable/9/tools/tools/ath (revision 237216) Property changes on: stable/9/tools/tools/ath ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /vendor/resolver/dist/tools/tools/ath:r1540-186085 Merged /projects/quota64/tools/tools/ath:r184125-207707 Merged /head/tools/tools/ath:r225778,227006,227538,227636,228177,228259,228409,228561,228594,229000-229001,233110,233648,235129-235130 Merged /projects/largeSMP/tools/tools/ath:r221273-222812,222815-223757 Index: stable/9/tools/tools/ether_reflect/ether_reflect.1 =================================================================== --- stable/9/tools/tools/ether_reflect/ether_reflect.1 (revision 237215) +++ stable/9/tools/tools/ether_reflect/ether_reflect.1 (revision 237216) @@ -1,108 +1,108 @@ .\" Copyright (c) 2008 George V. Neville-Neil .\" 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. .\" .\" $FreeBSD$ .\" .Dd December 23, 2008 .Dt ETHER_REFLECT 1 .Os .Sh NAME .Nm ether_reflect .Nd "reflect ethernet packets" .Sh SYNOPSIS .Nm .Op Fl a Ar ethernet address .Op Fl e Ar ethertype .Op Fl i Ar interface .Op Fl t Ar timeout .Op Fl p .Op Fl d .Sh DESCRIPTION -The +The .Nm command implements a simple ethernet packet reflector using the .Xr PCAP 3 library and .Xr bpf 4 , the Berkeley Packet Filter. The program is useful primarily to test the low level round trip time of packets through an Ethernet interface and/or a switch. Network protocols, such as IP, and the network stack in general are never invoked, only the device driver that implements the particular interface is executed. As the .Nm command uses the .Xr bpf 4 device the user must have root privileges to execute this program. .Pp The options are as follows: .Bl -tag -width ".Fl d Ar argument" .It Fl a Ar address Instead of reversing the ethernet destination and source addresses supply a different destination ethernet address for each packet received. .It Fl e Ar ether type Use a different ethertype than the default, 0x8822, which is the IEEE ether type for driver testing. .It Fl i Ar interface Network interface, which can be found with ifconfig(1). .It Fl t Ar timeout The time, in milliseconds, to wait for a packet. Lower times decrease latency at the cost of CPU. .It Fl p Set the device into promiscuous mode before testing. This is not usually necessary. .It Fl d Debug output. Print various small pieces of debug information. .El .Sh EXAMPLES The following is an example of a typical usage of the .Nm command: .Pp .Dl "ether_reflect -i em0 -t 1" .Pp Reflect all test packets, those with an ether type of 0x8822, which are seen on ineterface em0. The timeout is 1 millisecond. .Pp .Dl "ether_reflect -i em0 -a 00:00:00:aa:bb:cc -t 1" .Pp Rewrite the destination address in each packet to 00:00:00:aa:bb:cc before reflecting the packet. .Sh SEE ALSO .Xr ifconfig 8 , .Xr tcpdump 1 , .Xr pcap 4 , .Xr bpf 2 . .Sh HISTORY The .Nm program first appeared in .Fx 8.0 . .Sh AUTHORS This manual page was written by .An George V. Neville-Neil Aq gnn@FreeBSD.org . .Sh BUGS Should be reported to the author or to net@FreeBSD.org. Index: stable/9/tools/tools/ether_reflect =================================================================== --- stable/9/tools/tools/ether_reflect (revision 237215) +++ stable/9/tools/tools/ether_reflect (revision 237216) Property changes on: stable/9/tools/tools/ether_reflect ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /vendor/resolver/dist/tools/tools/ether_reflect:r1540-186085 Merged /projects/quota64/tools/tools/ether_reflect:r184125-207707 Merged /projects/largeSMP/tools/tools/ether_reflect:r221273-222812,222815-223757 Merged /head/tools/tools/ether_reflect:r225778,227006,227538,227636,228177,228259,228409,228561,228594,229000-229001,233110,233648,235129-235130 Index: stable/9/tools/tools/vimage/vimage.8 =================================================================== --- stable/9/tools/tools/vimage/vimage.8 (revision 237215) +++ stable/9/tools/tools/vimage/vimage.8 (revision 237216) @@ -1,195 +1,195 @@ .\" Copyright (c) 2002, 2003 Marko Zec .\" Copyright (c) 2009 University of Zagreb .\" Copyright (c) 2009 FreeBSD Foundation .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 25, 2009 .Dt VIMAGE 8 .Os .Sh NAME .Nm vimage .Nd manage virtual network stacks .Sh SYNOPSIS .Nm .Op Fl c | m .Ar vname .Op Ar param=value ... .Nm .Fl d .Ar vname .Nm .Fl l .Op Fl rvj .Op Ar vname .Nm .Fl i .Ar vname ifname .Op Ar newifname .Nm .Ar vi_name .Op command ... .Sh DESCRIPTION The .Nm utility is an alternative user interface for controlling virtual network stacks in FreeBSD, aimed primarily at supporting legacy applications which are not yet converted to using .Xr jail 8 , .Xr jexec 8 , and .Xr jls 8 . . .Ss Overview A virtual image or vimage is a jail with its own independent network stack instance. Every process, socket and network interface present in the system is always attached to one, and only one, virtual network stack instance (vnet). During system bootup sequence a default vnet is created to which all the configured interfaces and user processes are initially attached. Assuming that enough system resources are are available, a user with sufficient privileges can create and manage a hierarchy of subordinated virtual images. The .Nm command allows for creation, deletion and monitoring of virtual images, as well as for execution of arbitrary processes in a targeted virtual image. .Ss Invocation If invoked with no modifiers, the .Nm -command spawns a new interactive shell in virtual image +command spawns a new interactive shell in virtual image .Ar vname . If optional additional arguments following .Ar vname are provided, the first of those will be executed in place of the interactive shell, and the rest of the arguments will be passed as arguments to the executed command. .Pp The following modifiers are available: .Bl -tag -width indent .It Fl c Create a new virtual image named .Ar vname . Additional arguments, if provided, may be used to specify operating parameters different from defaults, in format .Ar param=value . See .Xr jail 8 for an extensive list of available parameters. .It Fl m Modify the parameters of a virtual image named .Ar vname , using the same syntax as with the -c form of the command. .It Fl d -Delete the virtual image +Delete the virtual image .Ar vname . No processes and/or sockets should exist in the target virtual image in order for the delete request to succeed. Non-loopback interfaces residing in the target virtual image will be reassigned to the virtual image's parent. .It Fl l List the properties and statistics for virtual images one level below the current one in the hierarchy. If an optional argument .Ar vname is provided, only the information regarding the target virtual image .Ar vname is displayed. With the optional .Op Ar -r switch enabled the list will include all virtual images below the current level in the vimage hierarchy. Enabling the optional .Op Ar -v or .Op Ar -j switches results in a more detailed output. .It Fl i Move interface .Ar ifname to the target virtual image .Ar vname . Interfaces will be automatically renamed to .So ethXX .Sc , unless an optional argument specifying the desired interface name .Op Ar newifname is provided. .El .Sh EXAMPLES -Create a new virtual image named +Create a new virtual image named .So v1 .Sc , which is allowed to create and manage an own subhierarchy of vimages: .Pp .Dl vimage -c v1 children.max=100 .Pp Execute the .So ifconfig .Sc command in the virtual image .So v1 .Sc : .Pp .Dl vimage v1 ifconfig .Pp Move the interface .So vlan0 .Sc to the virtual image .So v1 .Sc while renaming the interface as .So ve0 .Sc : .Pp .Dl vimage -i v1 vlan0 ve0 .Pp Show the status information for virtual image .So v1 .Sc : .Pp .Dl vimage -lv v1 .Sh DIAGNOSTICS The .Nm command exits 0 on success, and >0 if an error occurs. .Sh SEE ALSO .Xr jail 8 .Xr jexec 8 .Xr jls 8 .Sh HISTORY Network stack virtualization framework first appeared as a patchset against the FreeBSD 4.7 kernel in 2002, and was maintained outside of the main FreeBSD tree. As a result of a project sponsored by the FreeBSD Foundation and Stiching NLNet, integrated virtualized network stack first appeared in FreeBSD 8.0. .Sh BUGS Deletion of vimages / vnets is known to leak kernel memory and fail at stopping various timers, hence may lead to system crashes. .Sh AUTHOR .An "Marko Zec" Aq zec@fer.hr Index: stable/9/tools/tools/vimage =================================================================== --- stable/9/tools/tools/vimage (revision 237215) +++ stable/9/tools/tools/vimage (revision 237216) Property changes on: stable/9/tools/tools/vimage ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /head/tools/tools/vimage:r225778,227006,227538,227636,228177,228259,228409,228561,228594,229000-229001,233110,233648,235129-235130 Merged /projects/largeSMP/tools/tools/vimage:r221273-222812,222815-223757 Merged /vendor/resolver/dist/tools/tools/vimage:r1540-186085 Merged /projects/quota64/tools/tools/vimage:r184125-207707 Index: stable/9/usr.bin/bsdiff/bsdiff/bsdiff.1 =================================================================== --- stable/9/usr.bin/bsdiff/bsdiff/bsdiff.1 (revision 237215) +++ stable/9/usr.bin/bsdiff/bsdiff/bsdiff.1 (revision 237216) @@ -1,88 +1,88 @@ .\"- .\" Copyright 2003-2005 Colin Percival .\" All rights reserved .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted providing 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 ``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 May 18, 2003 .Dt BSDIFF 1 .Os .Sh NAME .Nm bsdiff .Nd "generate a patch between two binary files" .Sh SYNOPSIS .Nm .Ar oldfile newfile patchfile .Sh DESCRIPTION The .Nm utility compares .Ar oldfile to .Ar newfile and writes to .Ar patchfile a binary patch suitable for use by .Xr bspatch 1 . When .Ar oldfile and .Ar newfile are two versions of an executable program, the patches produced are on average a factor of five smaller than those produced by any other binary patch tool known to the author. .Pp The .Nm utility uses memory equal to 17 times the size of .Ar oldfile , and requires an absolute minimum working set size of 8 times the size of .Ar oldfile . .Sh SEE ALSO .Xr bspatch 1 .Sh AUTHORS .An Colin Percival Aq cperciva@FreeBSD.org .Sh BUGS The .Nm utility does not store the hashes of .Ar oldfile -or +or .Ar newfile in .Ar patchfile . As a result, it is possible to apply a patch to the wrong file; this will usually produce garbage. It is recommended that users of .Nm store the hashes of .Ar oldfile and .Ar newfile and compare against them before and after applying .Ar patchfile . Index: stable/9/usr.bin/bsdiff =================================================================== --- stable/9/usr.bin/bsdiff (revision 237215) +++ stable/9/usr.bin/bsdiff (revision 237216) Property changes on: stable/9/usr.bin/bsdiff ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/bsdiff:r233648 Index: stable/9/usr.bin/calendar/calendar.1 =================================================================== --- stable/9/usr.bin/calendar/calendar.1 (revision 237215) +++ stable/9/usr.bin/calendar/calendar.1 (revision 237216) @@ -1,319 +1,327 @@ .\" Copyright (c) 1989, 1990, 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. .\" 4. 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. .\" .\" @(#)calendar.1 8.1 (Berkeley) 6/29/93 .\" $FreeBSD$ .\" .Dd June 13, 2002 .Dt CALENDAR 1 .Os .Sh NAME .Nm calendar .Nd reminder service .Sh SYNOPSIS .Nm -.Op Fl a .Op Fl A Ar num +.Op Fl a .Op Fl B Ar num +.Op Fl D Ar moon|sun +.Op Fl d .Op Fl F Ar friday .Op Fl f Ar calendarfile +.Op Fl l Ar longitude .Oo .Bk -words .Fl t Ar dd Ns .Sm off .Op . Ar mm Op . Ar year .Sm on .Ek .Oc -.Op Fl W Ar num .Op Fl U Ar UTC-offset -.Op Fl l Ar longitude +.Op Fl W Ar num .Sh DESCRIPTION The .Nm utility checks the current directory for a file named .Pa calendar -and displays lines that begin with either today's date -or tomorrow's. +and displays lines that fall into the specified date range. On the day before a weekend (normally Friday), events for the next three days are displayed. .Pp The following options are available: .Bl -tag -width Ds .It Fl A Ar num Print lines from today and the next .Ar num days (forward, future). .It Fl a Process the ``calendar'' files of all users and mail the results to them. This requires super-user privileges. .It Fl B Ar num Print lines from today and the previous .Ar num days (backward, past). +.It Fl D Ar moon|sun +Print UTC offset, longitude and moon or sun information. +.It Fl d +Debug option: print current date information. .It Fl F Ar friday Specify which day of the week is ``Friday'' (the day before the weekend begins). Default is 5. .It Fl f Pa calendarfile Use .Pa calendarfile as the default calendar file. +.It Fl l Ar longitude +Perform lunar and solar calculations from this longitude. +If neither longitude nor UTC offset is specified, the calculations will +be based on the difference between UTC time and localtime. +If both are specified, UTC offset overrides longitude. .It Xo Fl t .Sm off .Ar dd .Op . Ar mm Op . Ar year .Sm on .Xc For test purposes only: set date directly to argument values. -.It Fl l Ar longitude , Fl U Ar UTC-offset -Only one is needed: -Perform lunar and solar calculations from this longitude or from -this UTC offset. -If neither is specified, the calculations will be based on the -difference between UTC time and localtime. +.It Fl U Ar UTC-offset +Perform lunar and solar calculations from this UTC offset. +If neither UTC offset nor longitude is specified, the calculations +will be based on the difference between UTC time and localtime. +If both are specified, UTC offset overrides longitude. .It Fl W Ar num Print lines from today and the next .Ar num days (forward, future). Ignore weekends when calculating the number of days. .El .Sh FILE FORMAT -.Pp To handle calendars in your national code table you can specify .Dq LANG= in the calendar file as early as possible. .Pp To handle the local name of sequences, you can specify them as: .Dq SEQUENCE= in the calendar file as early as possible. .Pp The names of the following special days are recognized: .Bl -tag -width 123456789012345 -compact .It Easter Catholic Easter. .It Paskha Orthodox Easter. .It NewMoon The lunar New Moon. .It FullMoon The lunar Full Moon. .It MarEquinox The solar equinox in March. .It JunSolstice The solar solstice in June. .It SepEquinox The solar equinox in September. .It DecSolstice The solar solstice in December. .It ChineseNewYear The first day of the Chinese year. .El These names may be reassigned to their local names via an assignment like .Dq Easter=Pasen in the calendar file. .Pp Other lines should begin with a month and day. They may be entered in almost any format, either numeric or as character strings. If the proper locale is set, national month and weekday names can be used. A single asterisk (``*'') matches every month. A day without a month matches that day of every week. A month without a day matches the first of that month. Two numbers default to the month followed by the day. Lines with leading tabs default to the last entered date, allowing multiple line specifications for a single date. .Pp The names of the recognized special days may be followed by a positive or negative integer, like: .Dq Easter+3 or .Dq Paskha-4 . .Pp Weekdays may be followed by ``-4'' ...\& ``+5'' (aliases for last, first, second, third, fourth) for moving events like ``the last Monday in April''. .Pp By convention, dates followed by an asterisk are not fixed, i.e., change from year to year. .Pp Day descriptions start after the first character in the line; if the line does not contain a character, it is not displayed. If the first character in the line is a character, it is treated as a continuation of the previous line. .Pp The ``calendar'' file is preprocessed by .Xr cpp 1 , allowing the inclusion of shared files such as lists of company holidays or meetings. If the shared file is not referenced by a full pathname, .Xr cpp 1 searches in the current (or home) directory first, and then in the directory .Pa /usr/share/calendar . Empty lines and lines protected by the C commenting syntax .Pq Li /* ... */ are ignored. .Pp Some possible calendar entries ( characters highlighted by \fB\et\fR sequence) .Bd -unfilled -offset indent LANG=C Easter=Ostern #include #include 6/15\fB\et\fRJune 15 (if ambiguous, will default to month/day). Jun. 15\fB\et\fRJune 15. 15 June\fB\et\fRJune 15. Thursday\fB\et\fREvery Thursday. June\fB\et\fREvery June 1st. 15 *\fB\et\fR15th of every month. 2010/4/15\fB\et\fR15 April 2010 May Sun+2\fB\et\fRsecond Sunday in May (Muttertag) 04/SunLast\fB\et\fRlast Sunday in April, \fB\et\fRsummer time in Europe Easter\fB\et\fREaster Ostern-2\fB\et\fRGood Friday (2 days before Easter) Paskha\fB\et\fROrthodox Easter .Ed .Sh FILES .Bl -tag -width calendar.christian -compact .It Pa calendar -file in current directory. +file in current directory .It Pa ~/.calendar .Pa calendar HOME directory. A chdir is done into this directory if it exists. .It Pa ~/.calendar/calendar calendar file to use if no calendar file exists in the current directory. .It Pa ~/.calendar/nomail do not send mail if this file exists. .El .Pp The following default calendar files are provided in .Pa /usr/share/calendars: .Pp .Bl -tag -width calendar.southafrica -compact .It Pa calendar.all File which includes all the default files. .It Pa calendar.australia Calendar of events in Australia. .It Pa calendar.birthday Births and deaths of famous (and not-so-famous) people. .It Pa calendar.christian Christian holidays. This calendar should be updated yearly by the local system administrator so that roving holidays are set correctly for the current year. .It Pa calendar.computer Days of special significance to computer people. .It Pa calendar.croatian Calendar of events in Croatia. .It Pa calendar.dutch Calendar of events in the Netherlands. .It Pa calendar.freebsd Birthdays of .Fx committers. .It Pa calendar.french Calendar of events in France. .It Pa calendar.german Calendar of events in Germany. .It Pa calendar.history Everything else, mostly U.S.\& historical events. .It Pa calendar.holiday Other holidays, including the not-well-known, obscure, and .Em really obscure. .It Pa calendar.judaic Jewish holidays. The entries for this calendar have been obtained from the port deskutils/hebcal. .It Pa calendar.music Musical events, births, and deaths. Strongly oriented toward rock 'n' roll. .It Pa calendar.newzealand Calendar of events in New Zealand. .It Pa calendar.russian Russian calendar. .It Pa calendar.southafrica Calendar of events in South Africa. .It Pa calendar.usholiday U.S.\& holidays. This calendar should be updated yearly by the local system administrator so that roving holidays are set correctly for the current year. .It Pa calendar.world Includes all calendar files except for national files. .El .Sh COMPATIBILITY The .Nm program previously selected lines which had the correct date anywhere in the line. This is no longer true, the date is only recognized when it occurs at the beginning of a line. .Sh SEE ALSO .Xr at 1 , .Xr cpp 1 , .Xr mail 1 , .Xr cron 8 .Sh HISTORY A .Nm command appeared in .At v7 . .Sh NOTES Chinese New Year is calculated at 120 degrees east of Greenwich, which roughly corresponds with the east coast of China. For people west of China, this might result that the start of Chinese New Year and the day of the related new moon might differ. .Pp The phases of the moon and the longitude of the sun are calculated against the local position which corresponds with 30 degrees times the time-difference towards Greenwich. .Pp The new and full moons are happening on the day indicated: They might happen in the time period in the early night or in the late evening. It doesn't indicate that they are starting in the night on that date. .Pp Because of minor differences between the output of the formulas used and other sources on the Internet, Druids and Werewolves should double-check the start and end time of solar and lunar events. .Sh BUGS The .Nm utility does not handle Jewish holidays. .Pp There is no possibility to properly specify the local position needed for solar and lunar calculations. Index: stable/9/usr.bin/calendar =================================================================== --- stable/9/usr.bin/calendar (revision 237215) +++ stable/9/usr.bin/calendar (revision 237216) Property changes on: stable/9/usr.bin/calendar ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/calendar:r233648 Index: stable/9/usr.bin/comm/comm.1 =================================================================== --- stable/9/usr.bin/comm/comm.1 (revision 237215) +++ stable/9/usr.bin/comm/comm.1 (revision 237216) @@ -1,116 +1,118 @@ .\" Copyright (c) 1989, 1990, 1993 .\" 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. .\" 4. 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. .\" .\" From: @(#)comm.1 8.1 (Berkeley) 6/6/93 .\" $FreeBSD$ .\" .Dd December 12, 2009 .Dt COMM 1 .Os .Sh NAME .Nm comm .Nd select or reject lines common to two files .Sh SYNOPSIS .Nm .Op Fl 123i .Ar file1 file2 .Sh DESCRIPTION The .Nm utility reads .Ar file1 and .Ar file2 , which should be sorted lexically, and produces three text columns as output: lines only in .Ar file1 ; lines only in .Ar file2 ; and lines in both files. .Pp The filename ``-'' means the standard input. .Pp The following options are available: .Bl -tag -width indent .It Fl 1 -Suppress printing of column 1. +Suppress printing of column 1, lines only in +.Ar file1 . .It Fl 2 -Suppress printing of column 2. +Suppress printing of column 2, lines only in +.Ar file2 . .It Fl 3 -Suppress printing of column 3. +Suppress printing of column 3, lines common to both. .It Fl i Case insensitive comparison of lines. .El .Pp Each column will have a number of tab characters prepended to it equal to the number of lower numbered columns that are being printed. For example, if column number two is being suppressed, lines printed in column number one will not have any tabs preceding them, and lines printed in column number three will have one. .Pp The .Nm utility assumes that the files are lexically sorted; all characters participate in line comparisons. .Sh ENVIRONMENT The .Ev LANG , .Ev LC_ALL , .Ev LC_COLLATE , and .Ev LC_CTYPE environment variables affect the execution of .Nm as described in .Xr environ 7 . .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr cmp 1 , .Xr diff 1 , .Xr sort 1 , .Xr uniq 1 .Sh STANDARDS The .Nm utility conforms to .St -p1003.2-92 . .Pp The .Fl i option is an extension to the .Tn POSIX standard. .Sh HISTORY A .Nm command appeared in .At v4 . Index: stable/9/usr.bin/comm =================================================================== --- stable/9/usr.bin/comm (revision 237215) +++ stable/9/usr.bin/comm (revision 237216) Property changes on: stable/9/usr.bin/comm ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /vendor/resolver/dist/usr.bin/comm:r1540-186085 Merged /projects/largeSMP/usr.bin/comm:r221273-222812,222815-223757 Merged /projects/quota64/usr.bin/comm:r184125-207707 Merged /head/usr.bin/comm:r226702,227006,228761,228857,229067,229538,229997,230127,230555,231544,232322,232994,233121,233648,234206,234772,234782,235915,236338,236346,236365 Index: stable/9/usr.bin/csup/cpasswd.1 =================================================================== --- stable/9/usr.bin/csup/cpasswd.1 (revision 237215) +++ stable/9/usr.bin/csup/cpasswd.1 (revision 237216) @@ -1,119 +1,119 @@ .\" Copyright 1999-2003 John D. Polstra. .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgment: .\" This product includes software developed by John D. Polstra. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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. .\" .\" $Id: cvpasswd.1,v 1.4 2003/03/04 18:24:42 jdp Exp $ .\" $FreeBSD$ .\" .Dd June 27, 2007 .Dt CPASSWD 1 .Os FreeBSD .Sh NAME .Nm cpasswd .Nd scramble passwords for csup authentication .Sh SYNOPSIS .Nm .Ar clientName .Ar serverName .Sh DESCRIPTION The .Nm utility creates scrambled passwords for the .Nm CVSup server's authentication database. It is invoked with a client name and a server name. .Ar ClientName is the name the client uses to gain access to the server. By convention, e-mail addresses are used for all client names, e.g., .Ql BillyJoe@FreeBSD.org . Client names are case-insensitive. -.Pp +.Pp .Ar ServerName is the name of the .Nm CVSup server which the client wishes to access. By convention, it is the canonical fully-qualified domain name of the server, e.g., .Ql CVSup.FreeBSD.ORG . This must agree with the server's own idea of its name. The name is case-insensitive. .Pp To set up authentication for a given server, one must perform the following steps: .Bl -enum .It Obtain the official .Ar serverName from the administrator of the server or from some other source. .It Choose an appropriate .Ar clientName . It should be in the form of a valid e-mail address, to make it easy for the server administrator to contact the user if necessary. .It Choose an arbitrary secret .Ar password . .It Run .Nm cpasswd , and type in the .Ar password when prompted for it. The utility will print out a line to send to the server administrator, and instruct you how to modify your .Li $ Ns Ev HOME Ns Pa /.csup/auth file. You should use a secure channel to send the line to the server administrator. .El .Pp Since .Li $ Ns Ev HOME Ns Pa /.csup/auth contains passwords, you should ensure that it is not readable by anyone except yourself. .Sh FILES .Bl -tag -width $HOME/.csup/authxx -compact .It Li $ Ns Ev HOME Ns Pa /.csup/auth Authentication password file. .El .Sh SEE ALSO .Xr csup 1 , .Xr cvsup 1 , .Xr cvsupd 8 . .Bd -literal http://www.cvsup.org/ .Ed .Sh AUTHORS .An -nosplit .An Petar Zhivkov Petrov Aq pesho.petrov@gmail.com is the author of .Nm , the rewrite of .Nm cvpasswd . .An John Polstra Aq jdp@polstra.com is the author of .Nm CVSup . .Sh LEGALITIES CVSup is a registered trademark of John D. Polstra. Index: stable/9/usr.bin/csup/csup.1 =================================================================== --- stable/9/usr.bin/csup/csup.1 (revision 237215) +++ stable/9/usr.bin/csup/csup.1 (revision 237216) @@ -1,996 +1,996 @@ .\" Copyright 1996-2003 John D. Polstra. .\" 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 ``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. .\" .\" $Id: cvsup.1,v 1.70 2003/03/04 18:23:46 jdp Exp $ .\" $FreeBSD$ .\" .Dd February 1, 2006 .Dt CSUP 1 .Os FreeBSD .Sh NAME .Nm csup .Nd network distribution package for CVS repositories .Sh SYNOPSIS .Nm .Op Fl 146aksvzZ .Op Fl A Ar addr .Op Fl b Ar base .Op Fl c Ar collDir .Op Fl d Ar delLimit .Op Fl h Ar host .Op Fl i Ar pattern .Op Fl l Ar lockfile .Op Fl L Ar verbosity .Op Fl p Ar port .Op Fl r Ar maxRetries .Ar supfile .Sh DESCRIPTION .Nm is a software package for updating collections of files across a network. It is a rewrite of the .Nm CVSup software in C. This manual page describes the usage of the .Nm client program. .Pp Unlike more traditional network distribution packages, such as .Nm rdist and .Nm sup , .Nm has specific optimizations for distributing CVS repositories. .Nm takes advantage of the properties of CVS repositories and the files they contain (in particular, RCS files), enabling it to perform updates much faster than traditional systems. .Pp .Nm is a general-purpose network file updating package. It is extremely fast, even for collections of files which have nothing to do with CVS or RCS. .Sh OPTIONS The client program .Nm requires at least a single argument, .Ar supfile . It names a file describing one or more collections of files to be transferred and/or updated from the server. The .Ar supfile has a format similar to the corresponding file used by .Nm sup . In most cases, .Nm can use existing .Nm sup Ar supfiles . .Pp The following options are supported by .Nm : .Bl -tag -width Fl .It Fl 1 Disables automatic retries when transient failures occur. Without this option, a transient failure such as a dropped network connection causes .Nm to retry repeatedly, using randomized exponential backoff to space the retries. This option is equivalent to .Fl r Cm 0 . .It Fl 4 Forces .Nm to use IPv4 addresses only. .It Fl 6 Forces .Nm to use IPv6 addresses only. .It Fl a Requires the server to authenticate itself (prove its identity) to the client. If authentication of the server fails, the update is canceled. See .Sx AUTHENTICATION , below. .It Fl A Ar addr Specifies a local address to bind to when connecting to the server. The local address might be a hostname or a numeric host address string consisting of a dotted decimal IPv4 address or an IPv6 address. This may be useful on hosts which have multiple IP addresses. .It Fl b Ar base Specifies the base directory under which .Nm will maintain its bookkeeping files, overriding any .Cm base specifications in the .Ar supfile . .It Fl c Ar collDir Specifies the subdirectory of .Ar base where the information about the collections is maintained. The default is .Pa sup . .It Fl d Ar delLimit Specifies the maximum number of files that may be deleted in a single update run. Any attempt to exceed the limit results in a fatal error. This can provide some protection against temporary configuration mistakes on the server. The default limit is infinity. .It Fl h Ar host Specifies the server host to contact, overriding any .Cm host specifications in the .Ar supfile . .It Fl i Ar pattern Causes .Nm to include only files and directories matching .Ar pattern in the update. If a directory matches the pattern, then the entire subtree rooted at the directory is included. If this option is specified multiple times, the patterns are combined using the .Ql or operation. If no .Fl i options are given, the default is to update all files in each collection. .Pp The .Ar pattern is a standard file name pattern. It is interpreted relative to the collection's prefix directory. Slash characters are matched only by explicit slashes in the pattern. Leading periods in file name are not treated specially. .It Fl k Causes .Nm to keep the temporary copies of any incorrectly edited files, in the event of checksum mismatches. This option is for debugging, to help determine why the files were edited incorrectly. Regardless of whether this option is specified, the permanent versions of faulty files are replaced with correct versions obtained by transferring the files in their entirety. Such transfers are called fixups. .It Fl l Ar lockfile Creates and locks the .Ar lockfile while the update is in progress. If .Ar lockfile is already locked, .Nm fails without performing automatic retries. This option is useful when .Nm is executed periodically from .Nm cron . It prevents a job from interfering with an earlier job that is perhaps taking extra long because of network problems. .Pp The process-ID is written to the lock file in text form when the lock is successfully acquired. Upon termination of the update, the lock file is removed. .It Fl L Ar verbosity Sets the verbosity level for output. A level of 0 causes .Nm to be completely silent unless errors occur. A level of 1 (the default) causes each updated file to be listed. A level of 2 provides more detailed information about the updates performed on each file. All messages are directed to the standard output. .It Fl p Ar port Sets the TCP port to which .Nm attempts to connect on the server host. The default port is 5999. .It Fl r Ar maxRetries Limits the number of automatic retries that will be attempted when transient errors such as lost network connections are encountered. By default, .Nm will retry indefinitely until an update is successfully completed. The retries are spaced using randomized exponential backoff. Note that .Fl r Cm 0 is equivalent to the .Fl 1 option. .It Fl s Suppresses the check of each client file's status against what is recorded in the list file. Instead, the list file is assumed to be accurate. This option greatly reduces the amount of disk activity and results in faster updates with less load on the client host. However it should only be used if client's files are never modified locally in any way. Mirror sites may find this option beneficial to reduce the disk load on their systems. For safety, even mirror sites should run .Nm occasionally (perhaps once a day) without the .Fl s option. .Pp Without the .Fl s option, .Nm performs a .Xr stat 2 call on each file and verifies that its attributes match those recorded in the list file. This ensures that any file changes made outside of .Nm are detected and corrected. .Pp If the .Fl s option is used when one or more files have been modified locally, the results are undefined. Local file damage may remain uncorrected, updates may be missed, or .Nm may abort prematurely. .It Fl v Prints the version number and exits, without contacting the server. .It Fl z Enables compression for all collections, as if the .Cm compress keyword were added to every collection in the .Ar supfile . .It Fl Z Disables compression for all collections, as if the .Cm compress keyword were removed from every collection in the .Ar supfile . .El .Pp The .Ar supfile is a text file which specifies the file collections to be updated. Comments begin with .Ql # and extend to the end of the line. Lines that are empty except for comments and white space are ignored. Each remaining line begins with the name of a server-defined collection of files. Following the collection name on the line are zero or more keywords or keyword=value pairs. .Pp Default settings may be specified in lines whose collection name is .Cm *default . Such defaults will apply to subsequent lines in the .Ar supfile . Multiple .Cm *default lines may be present. New values augment or override any defaults specified earlier in the .Ar supfile . Values specified explicitly for a collection override any default values. .Pp The most commonly used keywords are: .Bl -tag -width Fl .It Cm release= Ns Ar releaseName This specifies the release of the files within a collection. Like collection names, release names are defined by the server configuration files. Usually there is only one release in each collection, but there may be any number. Collections which come from a CVS repository often use .Cm release=cvs by convention. Non-CVS collections conventionally use .Cm release=current . .It Cm base= Ns Ar base This specifies a directory under which .Nm will maintain its bookkeeping files, describing the state of each collection on the client machine. The .Ar base directory must already exist; .Nm will not create it. The default .Ar base directory is .Pa /usr/local/etc/cvsup . .It Cm prefix= Ns Ar prefix This is the directory under which updated files will be placed. By default, it is the same as .Ar base . If it is not an absolute pathname, it is interpreted relative to .Ar base . The .Ar prefix directory must already exist; .Nm will not create it. .Pp As a special case, if .Ar prefix is a symbolic link pointing to a nonexistent file named .Ql SKIP , then .Nm will skip the collection. The parameters associated with the collection are still checked for validity, but none of its files will be updated. This feature allows a site to use a standard .Ar supfile on several machines, yet control which collections get updated on a per-machine basis. .It Cm host= Ns Ar hostname This specifies the server machine from which all files will be taken. .Nm requires that all collections in a single run come from the same host. If you wish to update collections from several different hosts, you must run .Nm several times. .It Cm delete The presence of this keyword gives .Nm permission to delete files. If it is missing, no files will be deleted. .Pp The presence of the .Cm delete keyword puts .Nm into so-called .Em exact mode. In exact mode, .Nm does its best to make the client's files correspond to those on the server. This includes deleting individual deltas and symbolic tags from RCS files, as well as deleting entire files. In exact mode, .Nm verifies every edited file with a checksum, to ensure that the edits have produced a file identical to the master copy on the server. If the checksum test fails for a file, then .Nm falls back upon transferring the entire file. .Pp In general, .Nm deletes only files which are known to the server. Extra files present in the client's tree are left alone, even in exact mode. More precisely, .Nm is willing to delete two classes of files: .Bl -bullet -compact .It Files that were previously created or updated by .Nm itself. .It Checked-out versions of files which are marked as dead on the server. .El .It Cm use-rel-suffix Causes .Nm to append a suffix constructed from the release and tag to the name of each list file that it maintains. See .Sx THE LIST FILE for details. .It Cm compress This enables compression of all data sent across the network. Compression is quite effective, normally eliminating 65% to 75% of the bytes that would otherwise need to be transferred. However, it is costly in terms of CPU time on both the client and the server. On local area networks, compression is generally counter-productive; it actually slows down file updates. On links with speeds of 56K bits/second or less, compression is almost always beneficial. For network links with speeds between these two extremes, let experimentation be your guide. .Pp The .Fl z command line option enables the .Cm compress keyword for all collections, regardless of what is specified in the supfile. Likewise, the .Fl Z command line option disables the .Cm compress option for all collections. .Nm uses a looser checksum for RCS files, which ignores harmless differences in white space. Different versions of CVS and RCS produce a variety of differences in white space for the same RCS files. Thus the strict checksum can report spurious mismatches for files which are logically identical. This can lead to numerous unneeded .Dq fixups , and thus to slow updates. .It Cm umask= Ns Ar n Causes .Nm to use a umask value of .Ar n (an octal number) when updating the files in the collection. This option is ignored if .Cm preserve is specified. .El .Pp Some additional, more specialized keywords are described below. Unrecognized keywords are silently ignored for backward compatibility with .Nm sup . .Sh CVS MODE .Nm CVSup supports two primary modes of operation. They are called .Em CVS mode and .Em checkout mode. .Pp In CVS mode, the client receives copies of the actual RCS files making up the master CVS repository. CVS mode is the default mode of operation. It is appropriate when the user wishes to maintain a full copy of the CVS repository on the client machine. .Pp CVS mode is also appropriate for file collections which are not based upon a CVS repository. The files are simply transferred verbatim, without interpretation. .Sh CHECKOUT MODE In checkout mode, the client receives specific revisions of files, checked out directly from the server's CVS repository. Checkout mode allows the client to receive any version from the repository, without requiring any extra disk space on the server for storing multiple versions in checked-out form. Checkout mode provides much flexibility beyond that basic functionality, however. The client can specify any CVS symbolic tag, or any date, or both, and .Nm will provide the corresponding checked-out versions of the files in the repository. .Pp Checkout mode is selected on a per-collection basis, by the presence of one or both of the following keywords in the .Ar supfile : .Bl -tag -width Fl .It Cm tag= Ns Ar tagname This specifies a symbolic tag that should be used to select the revisions that are checked out from the CVS repository. The tag may refer to either a branch or a specific revision. It must be symbolic; numeric revision numbers are not supported. .Pp For the FreeBSD source repository, the most commonly used tags will be: .Bl -tag -width RELENG_6 .It Li RELENG_6 The .Ql stable branch. .It Li \&. The main branch (the .Ql current release). This is the default, if only the .Cm date keyword is given. .El .Sm off .It Xo Cm date= .Op Ar cc .Ar yy.mm.dd.hh.mm.ss .Xc .Sm on This specifies a date that should be used to select the revisions that are checked out from the CVS repository. The client will receive the revisions that were in effect at the specified date and time. .Pp At present, the date format is inflexible. All 17 or 19 characters must be specified, exactly as shown. For the years 2000 and beyond, specify the century .Ar cc . For earlier years, specify only the last two digits .Ar yy . Dates and times are considered to be GMT. The default date is .Ql \&. , which means .Dq as late as possible . .El .Pp To enable checkout mode, you must specify at least one of these keywords. If both are missing, .Nm defaults to CVS mode. .Pp If both a branch tag and a date are specified, then the revisions on the given branch, as of the given date, will be checked out. It is permitted, but not particularly useful, to specify a date with a specific release tag. .Pp In checkout mode, the tag and/or date may be changed between updates. For example, suppose that a collection has been transferred using the specification .Ql tag=. . The user could later change the specification to .Ql tag=RELENG_3 . This would cause .Nm to edit the checked-out files in such a way as to transform them from the .Ql current versions to the .Ql stable versions. In general, .Nm is willing to transform any tag/date combination into any other tag/date combination, by applying the intervening RCS deltas to the existing files. .Pp When transforming a collection of checked-out files from one tag to another, it is important to specify the .Cm list keyword in the .Ar supfile , to ensure that the same list file is used both before and after the transformation. The list file is described in .Sx THE LIST FILE , below. .Sh THE LIST FILE For efficiency, .Nm maintains a bookkeeping file for each collection, called the list file. The list file contains information about which files and revisions the client currently possesses. It also contains information used for verifying that the list file is consistent with the actual files in the client's tree. .Pp The list file is not strictly necessary. If it is deleted, or becomes inconsistent with the actual client files, .Nm falls back upon a less efficient method of identifying the client's files and performing its updates. Depending on .Nm csup Ns No 's mode of operation, the fallback method employs time stamps, checksums, or analysis of RCS files. .Pp Because the list file is not essential, .Nm is able to .Dq adopt an existing file tree acquired by FTP or from a CD-ROM. .Nm identifies the client's versions of the files, updates them as necessary, and creates a list file for future use. Adopting a foreign file tree is not as fast as performing a normal update. It also produces a heavier load on the server. .Pp The list file is stored in a collection-specific directory; see .Sx FILES for details. Its name always begins with .Ql checkouts . If the keyword .Cm use-rel-suffix is specified in the .Ar supfile , a suffix, formed from the release and tag, is appended to the name. The default suffix can be overridden by specifying an explicit suffix in the .Ar supfile : .Bl -tag -width Fl .It Cm list= Ns Ar suffix This specifies a suffix for the name of the list file. A leading dot is provided automatically. For example, .Ql list=stable would produce a list file named .Pa checkouts.stable , regardless of the release, tag, or .Cm use-rel-suffix keyword. .El .Sh REFUSE FILES The user can specify sets of files that he does not wish to receive. The files are specified as file name patterns in so-called .Em refuse files. The patterns are separated by whitespace, and multiple patterns are permitted on each line. Files and directories matching the patterns are neither updated nor deleted; they are simply ignored. .Pp There is currently no provision for comments in refuse files. .Pp The patterns are similar to those of .Xr sh 1 , except that there is no special treatment for slashes or for filenames that begin with a period. For example, the pattern .Ql *.c will match any file name ending with .Ql \&.c including those in subdirectories, such as .Ql foo/bar/lam.c . All patterns are interpreted relative to the collection's prefix directory. .Pp If the files are coming from a CVS repository, as is usually the case, then they will be RCS files. These have a .Ql \&,v suffix which must be taken into account in the patterns. For example, the FreeBSD documentation files are in a sub-directory of .Ar base called .Ql doc . If .Ql Makefile from that directory is not required then the line -.Pp +.Pp .Bl -item -compact -offset indent -.It +.It .Pa doc/Makefile .El .Pp will not work because the file on the server is called .Ql Makefile,v . A better solution would be .Pp .Bl -item -compact -offset indent .It .Pa doc/Makefile* -.El -.Pp +.El +.Pp which will match whether .Ql Makefile is an RCS file or not. .Pp As another example, to receive the FreeBSD documentation files without the Japanese, Russian, and Chinese translations, create a refuse file containing the following lines: .Pp .Bl -item -compact -offset indent .It .Pa doc/ja* .It .Pa doc/ru* .It .Pa doc/zh* -.El +.El .Pp As many as three refuse files are examined for each .Ar supfile line. There can be a global refuse file named .Sm off .Ar base / Ar collDir Pa /refuse .Sm on which applies to all collections and releases. There can be a per-collection refuse file named .Sm off .Xo Ar base / Ar collDir / Ar collection .Pa /refuse .Xc .Sm on which applies to a specific collection. Finally, there can be a per-release and tag refuse file which applies only to a given release/tag combination within a collection. The name of the latter is formed by suffixing the name of the per-collection refuse file in the same manner as described above for the list file. None of the refuse files are required to exist. .Pp .Nm has a built-in default value of .Ar /usr/local/etc/cvsup for .Ar base and .Ar sup -for +for .Ar collDir but it is possible to override both of these. The value of .Ar base can be changed using the .Fl b option or a .Ar base=pathname entry in the .Ar supfile . -(If both are used the +(If both are used the .Fl b option will override the .Ar supfile -entry.) The value of +entry.) The value of .Ar collDir can only be changed with the .Fl c option; there is no .Ar supfile command to change it. .Pp As an example, suppose that the .Ar base and .Ar collDir both have their default values, and that the collection and release are .Ql src-all and .Ql cvs , respectively. Assume further that checkout mode is being used with .Ql tag=RELENG_3 . The three possible refuse files would then be named: .Pp .Bl -item -compact -offset indent .It .Pa /usr/local/etc/cvsup/sup/refuse .It .Pa /usr/local/etc/cvsup/sup/src-all/refuse .It .Pa /usr/local/etc/cvsup/sup/src-all/refuse.cvs:RELENG_3 .El .Pp If the .Ar supfile includes the command .Ar base=/foo the refuse files would be: .Pp .Bl -item -compact -offset indent .It .Pa /foo/sup/refuse .It .Pa /foo/sup/src-all/refuse .It .Pa /foo/sup/src-all/refuse.cvs:RELENG_3 .El .Pp If .Fl b .Ar /bar is used (even with .Ar base=/foo in the .Ar supfile ) : .Pp .Bl -item -compact -offset indent .It -.Pa /bar/sup/refuse +.Pa /bar/sup/refuse .It -.Pa /bar/sup/src-all/refuse +.Pa /bar/sup/src-all/refuse .It -.Pa /bar/sup/src-all/refuse.cvs:RELENG_3 +.Pa /bar/sup/src-all/refuse.cvs:RELENG_3 .El .Pp and with .Fl c .Ar stool as well: .Pp .Bl -item -compact -offset indent .It .Pa /bar/stool/refuse -.It +.It .Pa /bar/stool/src-all/refuse .It .Pa /bar/stool/src-all/refuse.cvs:RELENG_3 .El .Sh AUTHENTICATION .Nm implements an optional authentication mechanism which can be used by the client and server to verify each other's identities. Public CVSup servers normally do not enable authentication. .Nm users may ignore this section unless they have been informed that authentication is required by the administrator of their server. .Pp The authentication subsystem uses a challenge-response protocol which is immune to packet sniffing and replay attacks. No passwords are sent over the network in either direction. Both the client and the server can independently verify the identities of each other. .Pp The file .Li $ Ns Ev HOME Ns Pa /.csup/auth holds the information used for authentication. This file contains a record for each server that the client is allowed to access. Each record occupies one line in the file. Lines beginning with .Ql # are ignored, as are lines containing only white space. White space is significant everywhere else in the file. Fields are separated by .Ql \&: characters. .Pp Each record of the file has the following form: .Bd -literal -offset indent .Sm off .Xo Ar serverName No : Ar clientName No : .Ar password No : Ar comment .Xc .Sm on .Ed .Pp All fields must be present even if some of them are empty. .Ar ServerName is the name of the server to which the record applies. By convention, it is the canonical fully-qualified domain name of the server, e.g., .Ql CVSup177.FreeBSD.ORG . This must agree with the server's own idea of its name. The name is case-insensitive. .Pp .Ar ClientName is the name the client uses to gain access to the server. By convention, e-mail addresses are used for all client names, e.g., .Ql BillyJoe@FreeBSD.org . Client names are case-insensitive. .Pp .Ar Password is a secret string of characters that the client uses to prove its identity. It may not contain any .Ql \&: or newline characters. .Pp .Ar Comment may contain any additional information to identify the record. It is not interpreted by the program. .Pp To set up authentication for a given server, one must perform the following steps: .Bl -enum .It Obtain the official .Ar serverName from the administrator of the server or from some other source. .It Choose an appropriate .Ar clientName . It should be in the form of a valid e-mail address, to make it easy for the server administrator to contact the user if necessary. .It Choose an arbitrary secret .Ar password . .It Run the .Nm cpasswd utility, and type in the .Ar password when prompted for it. The utility will print out a line to send to the server administrator, and instruct you how to modify your .Li $ Ns Ev HOME Ns Pa /.csup/auth file. You should use a secure channel to send the line to the server administrator. .El .Pp Since .Li $ Ns Ev HOME Ns Pa /.csup/auth contains passwords, you should ensure that it is not readable by anyone except yourself. .Pp Authentication works independently in both directions. The server administrator controls whether you must prove your identity. You control whether to check the server's identity, by means of the .Fl a command line option. .Sh csup AND FIREWALLS In its default mode, .Nm will work through any firewall which permits outbound connections to port 5999 of the server host. .Sh USING csup WITH SOCKS .Nm can be used through a SOCKS proxy server with the standard .Nm runsocks command. Your .Nm executable needs to be dynamically-linked with the system libraries for .Nm runsocks to work properly. .Sh USING ssh PORT FORWARDING As an alternative to SOCKS, a user behind a firewall can penetrate it with the TCP port forwarding provided by the Secure Shell package .Nm ssh . The user must have a login account on the .Nm CVSup server host in order to do this. The procedure is as follows: .Bl -enum .It Establish a connection to the server host with .Nm ssh , like this: .Bd -literal ssh -f -x -L 5999:localhost:5999 serverhost sleep 60 .Ed .Pp Replace .Ar serverhost with the hostname of the CVSup server, but type .Ql localhost literally. This sets up the required port forwarding. You must start .Nm before the 60-second .Nm sleep finishes. Once the update has begun, .Nm ssh will keep the forwarded channels open as long as they are needed. .It Run .Nm on the local host, including the arguments .Ql -h localhost on the command line. .El .Sh FILES .Bl -tag -width base/sup/collection/checkouts*xx -compact .It Pa /usr/local/etc/cvsup Default .Ar base directory. .It Pa sup Default .Ar collDir subdirectory. .Sm off .It Xo Ar base / Ar collDir / Ar collection .Pa /checkouts* .Xc .Sm on List files. .El .Sh SEE ALSO .Xr cpasswd 1 , .Xr cvs 1 , .Xr rcsintro 1 , .Xr ssh 1 . .Sh AUTHORS .An -nosplit .An Maxime Henrion Aq mux@FreeBSD.org is the author of .Nm , the rewrite of .Nm CVSup in C. .An John Polstra Aq jdp@polstra.com is the author of .Nm CVSup . .Sh LEGALITIES CVSup is a registered trademark of John D. Polstra. .Pp .Nm is released under a 2-clauses BSD license. .Sh BUGS An RCS file is not recognized as such unless its name ends with .Ql \&,v . .Pp Any directory named .Ql Attic is assumed to be a CVS Attic, and is treated specially. Index: stable/9/usr.bin/csup =================================================================== --- stable/9/usr.bin/csup (revision 237215) +++ stable/9/usr.bin/csup (revision 237216) Property changes on: stable/9/usr.bin/csup ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/csup:r233648 Index: stable/9/usr.bin/find/find.1 =================================================================== --- stable/9/usr.bin/find/find.1 (revision 237215) +++ stable/9/usr.bin/find/find.1 (revision 237216) @@ -1,1070 +1,1070 @@ .\" Copyright (c) 1990, 1993 .\" 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. .\" 4. 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. .\" .\" @(#)find.1 8.7 (Berkeley) 5/9/95 .\" $FreeBSD$ .\" .Dd March 17, 2010 .Dt FIND 1 .Os .Sh NAME .Nm find .Nd walk a file hierarchy .Sh SYNOPSIS .Nm .Op Fl H | Fl L | Fl P .Op Fl EXdsx .Op Fl f Ar path .Ar path ... .Op Ar expression .Nm .Op Fl H | Fl L | Fl P .Op Fl EXdsx .Fl f Ar path .Op Ar path ... .Op Ar expression .Sh DESCRIPTION The .Nm utility recursively descends the directory tree for each .Ar path listed, evaluating an .Ar expression (composed of the .Dq primaries and .Dq operands listed below) in terms of each file in the tree. .Pp The options are as follows: .Bl -tag -width indent .It Fl E Interpret regular expressions followed by .Ic -regex and .Ic -iregex primaries as extended (modern) regular expressions rather than basic regular expressions (BRE's). The .Xr re_format 7 manual page fully describes both formats. .It Fl H Cause the file information and file type (see .Xr stat 2 ) returned for each symbolic link specified on the command line to be those of the file referenced by the link, not the link itself. If the referenced file does not exist, the file information and type will be for the link itself. File information of all symbolic links not on the command line is that of the link itself. .It Fl L Cause the file information and file type (see .Xr stat 2 ) returned for each symbolic link to be those of the file referenced by the link, not the link itself. If the referenced file does not exist, the file information and type will be for the link itself. .Pp This option is equivalent to the deprecated .Ic -follow primary. .It Fl P Cause the file information and file type (see .Xr stat 2 ) returned for each symbolic link to be those of the link itself. This is the default. .It Fl X Permit .Nm to be safely used in conjunction with .Xr xargs 1 . If a file name contains any of the delimiting characters used by .Xr xargs 1 , a diagnostic message is displayed on standard error, and the file is skipped. The delimiting characters include single .Pq Dq Li " ' " and double .Pq Dq Li " \*q " quotes, backslash .Pq Dq Li \e , space, tab and newline characters. .Pp However, you may wish to consider the .Fl print0 primary in conjunction with .Dq Nm xargs Fl 0 as an effective alternative. .It Fl d Cause .Nm to perform a depth-first traversal, i.e., directories are visited in post-order and all entries in a directory will be acted on before the directory itself. By default, .Nm visits directories in pre-order, i.e., before their contents. Note, the default is .Em not a breadth-first traversal. .Pp This option is equivalent to the .Ic -depth primary of .St -p1003.1-2001 . The .Fl d option can be useful when .Nm is used with .Xr cpio 1 to process files that are contained in directories with unusual permissions. It ensures that you have write permission while you are placing files in a directory, then sets the directory's permissions as the last thing. .It Fl f Specify a file hierarchy for .Nm to traverse. File hierarchies may also be specified as the operands immediately following the options. .It Fl s Cause .Nm to traverse the file hierarchies in lexicographical order, i.e., alphabetical order within each directory. Note: .Ql find -s and .Ql "find | sort" may give different results. .It Fl x Prevent .Nm from descending into directories that have a device number different than that of the file from which the descent began. .Pp This option is equivalent to the deprecated .Ic -xdev primary. .El .Sh PRIMARIES .Pp All primaries which take a numeric argument allow the number to be preceded by a plus sign .Pq Dq Li + or a minus sign .Pq Dq Li - . A preceding plus sign means .Dq more than n , a preceding minus sign means .Dq less than n and neither means .Dq exactly n . .Bl -tag -width indent .It Ic -Bmin Ar n True if the difference between the time of a file's inode creation and the time .Nm was started, rounded up to the next full minute, is .Ar n minutes. .It Ic -Bnewer Ar file Same as .Ic -newerBm . .It Ic -Btime Ar n Ns Op Cm smhdw If no units are specified, this primary evaluates to true if the difference between the time of a file's inode creation and the time .Nm was started, rounded up to the next full 24-hour period, is .Ar n 24-hour periods. .Pp If units are specified, this primary evaluates to true if the difference between the time of a file's inode creation and the time .Nm was started is exactly .Ar n units. Please refer to the .Ic -atime primary description for information on supported time units. .It Ic -acl May be used in conjunction with other primaries to locate files with extended ACLs. See .Xr acl 3 for more information. .It Ic -amin Ar n True if the difference between the file last access time and the time .Nm was started, rounded up to the next full minute, is .Ar n minutes. .It Ic -anewer Ar file Same as .Ic -neweram . .It Ic -atime Ar n Ns Op Cm smhdw If no units are specified, this primary evaluates to true if the difference between the file last access time and the time .Nm was started, rounded up to the next full 24-hour period, is .Ar n 24-hour periods. .Pp If units are specified, this primary evaluates to true if the difference between the file last access time and the time .Nm was started is exactly .Ar n units. Possible time units are as follows: .Pp .Bl -tag -width indent -compact .It Cm s second .It Cm m minute (60 seconds) .It Cm h hour (60 minutes) .It Cm d day (24 hours) .It Cm w week (7 days) .El .Pp Any number of units may be combined in one .Ic -atime argument, for example, .Dq Li "-atime -1h30m" . Units are probably only useful when used in conjunction with the .Cm + or .Cm - modifier. .It Ic -cmin Ar n True if the difference between the time of last change of file status information and the time .Nm was started, rounded up to the next full minute, is .Ar n minutes. .It Ic -cnewer Ar file Same as .Ic -newercm . .It Ic -ctime Ar n Ns Op Cm smhdw If no units are specified, this primary evaluates to true if the difference between the time of last change of file status information and the time .Nm was started, rounded up to the next full 24-hour period, is .Ar n 24-hour periods. .Pp If units are specified, this primary evaluates to true if the difference between the time of last change of file status information and the time .Nm was started is exactly .Ar n units. Please refer to the .Ic -atime primary description for information on supported time units. .It Ic -d -Same as +Same as .Ic depth . GNU find implements this as a primary in mistaken emulation of .Fx .Xr find 1 . .It Ic -delete Delete found files and/or directories. Always returns true. This executes from the current working directory as .Nm recurses down the tree. It will not attempt to delete a filename with a .Dq Pa / character in its pathname relative to .Dq Pa \&. for security reasons. Depth-first traversal processing is implied by this option. Following symlinks is incompatible with this option. .It Ic -depth Always true; same as the .Fl d option. .It Ic -depth Ar n True if the depth of the file relative to the starting point of the traversal is .Ar n . .It Ic -empty True if the current file or directory is empty. .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&; True if the program named .Ar utility returns a zero value as its exit status. Optional .Ar arguments may be passed to the utility. The expression must be terminated by a semicolon .Pq Dq Li \&; . If you invoke .Nm from a shell you may need to quote the semicolon if the shell would otherwise treat it as a control operator. If the string .Dq Li {} appears anywhere in the utility name or the arguments it is replaced by the pathname of the current file. .Ar Utility will be executed from the directory from which .Nm was executed. .Ar Utility and .Ar arguments are not subject to the further expansion of shell patterns and constructs. .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} + Same as .Ic -exec , except that .Dq Li {} is replaced with as many pathnames as possible for each invocation of .Ar utility . This behaviour is similar to that of .Xr xargs 1 . .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&; The .Ic -execdir primary is identical to the .Ic -exec primary with the exception that .Ar utility will be executed from the directory that holds the current file. The filename substituted for the string .Dq Li {} is not qualified. .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} + Same as .Ic -execdir , except that .Dq Li {} is replaced with as many pathnames as possible for each invocation of .Ar utility . This behaviour is similar to that of .Xr xargs 1 . .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags The flags are specified using symbolic names (see .Xr chflags 1 ) . Those with the .Qq Li no prefix (except .Qq Li nodump ) are said to be .Ar notflags . Flags in .Ar flags are checked to be set, and flags in .Ar notflags are checked to be not set. Note that this is different from .Ic -perm , which only allows the user to specify mode bits that are set. .Pp If flags are preceded by a dash .Pq Dq Li - , this primary evaluates to true if at least all of the bits in .Ar flags and none of the bits in .Ar notflags are set in the file's flags bits. If flags are preceded by a plus .Pq Dq Li + , this primary evaluates to true if any of the bits in .Ar flags is set in the file's flags bits, or any of the bits in .Ar notflags is not set in the file's flags bits. Otherwise, this primary evaluates to true if the bits in .Ar flags exactly match the file's flags bits, and none of the .Ar flags bits match those of .Ar notflags . .It Ic -fstype Ar type True if the file is contained in a file system of type .Ar type . The .Xr lsvfs 1 command can be used to find out the types of file systems that are available on the system. In addition, there are two pseudo-types, .Dq Li local and .Dq Li rdonly . The former matches any file system physically mounted on the system where the .Nm is being executed and the latter matches any file system which is mounted read-only. .It Ic -gid Ar gname The same thing as -.Ar -group Ar gname +.Ar -group Ar gname for compatibility with GNU find. GNU find imposes a restriction that -.Ar gname +.Ar gname is numeric, while -.Xr find 1 +.Xr find 1 does not. .It Ic -group Ar gname True if the file belongs to the group .Ar gname . If .Ar gname is numeric and there is no such group name, then .Ar gname is treated as a group ID. .It Ic -ignore_readdir_race This option is for GNU find compatibility and is ignored. .It Ic -ilname Ar pattern Like .Ic -lname , but the match is case insensitive. This is a GNU find extension. .It Ic -iname Ar pattern Like .Ic -name , but the match is case insensitive. .It Ic -inum Ar n True if the file has inode number .Ar n . .It Ic -ipath Ar pattern Like .Ic -path , but the match is case insensitive. .It Ic -iregex Ar pattern Like .Ic -regex , but the match is case insensitive. .It Ic -iwholename Ar pattern -The same thing as +The same thing as .Ic -ipath , for GNU find compatibility. .It Ic -links Ar n True if the file has .Ar n links. .It Ic -lname Ar pattern Like .Ic -name , but the contents of the symbolic link are matched instead of the file name. This is a GNU find extension. .It Ic -ls This primary always evaluates to true. The following information for the current file is written to standard output: its inode number, size in 512-byte blocks, file permissions, number of hard links, owner, group, size in bytes, last modification time, and pathname. If the file is a block or character special file, the major and minor numbers will be displayed instead of the size in bytes. If the file is a symbolic link, the pathname of the linked-to file will be displayed preceded by .Dq Li -> . The format is identical to that produced by .Bk -words .Dq Nm ls Fl dgils . .Ek .It Ic -maxdepth Ar n Always true; descend at most .Ar n directory levels below the command line arguments. If any .Ic -maxdepth primary is specified, it applies to the entire expression even if it would not normally be evaluated. .Dq Ic -maxdepth Li 0 limits the whole search to the command line arguments. .It Ic -mindepth Ar n Always true; do not apply any tests or actions at levels less than .Ar n . If any .Ic -mindepth primary is specified, it applies to the entire expression even if it would not normally be evaluated. .Dq Ic -mindepth Li 1 processes all but the command line arguments. .It Ic -mmin Ar n True if the difference between the file last modification time and the time .Nm was started, rounded up to the next full minute, is .Ar n minutes. .It Ic -mnewer Ar file Same as .Ic -newer . .It Ic -mount -The same thing as +The same thing as .Ic -xdev , for GNU find compatibility. .It Ic -mtime Ar n Ns Op Cm smhdw If no units are specified, this primary evaluates to true if the difference between the file last modification time and the time .Nm was started, rounded up to the next full 24-hour period, is .Ar n 24-hour periods. .Pp If units are specified, this primary evaluates to true if the difference between the file last modification time and the time .Nm was started is exactly .Ar n units. Please refer to the .Ic -atime primary description for information on supported time units. .It Ic -name Ar pattern True if the last component of the pathname being examined matches .Ar pattern . Special shell pattern matching characters .Dq ( Li \&[ , .Dq Li \&] , .Dq Li * , and .Dq Li \&? ) may be used as part of .Ar pattern . These characters may be matched explicitly by escaping them with a backslash .Pq Dq Li \e . .It Ic -newer Ar file True if the current file has a more recent last modification time than .Ar file . .It Ic -newer Ns Ar X Ns Ar Y Ar file True if the current file has a more recent last access time .Pq Ar X Ns = Ns Cm a , inode creation time .Pq Ar X Ns = Ns Cm B , change time .Pq Ar X Ns = Ns Cm c , or modification time .Pq Ar X Ns = Ns Cm m than the last access time .Pq Ar Y Ns = Ns Cm a , inode creation time .Pq Ar Y Ns = Ns Cm B , change time .Pq Ar Y Ns = Ns Cm c , or modification time .Pq Ar Y Ns = Ns Cm m of .Ar file . In addition, if .Ar Y Ns = Ns Cm t , then .Ar file is instead interpreted as a direct date specification of the form understood by .Xr cvs 1 . Note that .Ic -newermm is equivalent to .Ic -newer . .It Ic -nogroup True if the file belongs to an unknown group. .It Ic -noignore_readdir_race This option is for GNU find compatibility and is ignored. .It Ic -noleaf This option is for GNU find compatibility. -In GNU find it disables an optimization not relevant to +In GNU find it disables an optimization not relevant to .Xr find 1 , so it is ignored. .It Ic -nouser True if the file belongs to an unknown user. .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&; The .Ic -ok primary is identical to the .Ic -exec primary with the exception that .Nm requests user affirmation for the execution of the .Ar utility by printing a message to the terminal and reading a response. If the response is not affirmative .Ql ( y in the .Dq Li POSIX locale), the command is not executed and the value of the .Ic -ok expression is false. .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&; The .Ic -okdir primary is identical to the .Ic -execdir primary with the same exception as described for the .Ic -ok primary. .It Ic -path Ar pattern True if the pathname being examined matches .Ar pattern . Special shell pattern matching characters .Dq ( Li \&[ , .Dq Li \&] , .Dq Li * , and .Dq Li \&? ) may be used as part of .Ar pattern . These characters may be matched explicitly by escaping them with a backslash .Pq Dq Li \e . Slashes .Pq Dq Li / are treated as normal characters and do not have to be matched explicitly. .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode The .Ar mode may be either symbolic (see .Xr chmod 1 ) or an octal number. If the .Ar mode is symbolic, a starting value of zero is assumed and the .Ar mode sets or clears permissions without regard to the process' file mode creation mask. If the .Ar mode is octal, only bits 07777 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO of the file's mode bits participate in the comparison. If the .Ar mode is preceded by a dash .Pq Dq Li - , this primary evaluates to true if at least all of the bits in the .Ar mode are set in the file's mode bits. If the .Ar mode is preceded by a plus .Pq Dq Li + , this primary evaluates to true if any of the bits in the .Ar mode are set in the file's mode bits. Otherwise, this primary evaluates to true if the bits in the .Ar mode exactly match the file's mode bits. Note, the first character of a symbolic mode may not be a dash .Pq Dq Li - . .It Ic -print This primary always evaluates to true. It prints the pathname of the current file to standard output. If none of .Ic -exec , -ls , -print0 , or .Ic -ok is specified, the given expression shall be effectively replaced by .Cm \&( Ar "given expression" Cm \&) Ic -print . .It Ic -print0 This primary always evaluates to true. It prints the pathname of the current file to standard output, followed by an .Tn ASCII .Dv NUL character (character code 0). .It Ic -prune This primary always evaluates to true. It causes .Nm to not descend into the current file. Note, the .Ic -prune primary has no effect if the .Fl d option was specified. .It Ic -regex Ar pattern True if the whole path of the file matches .Ar pattern using regular expression. To match a file named .Dq Pa ./foo/xyzzy , you can use the regular expression .Dq Li ".*/[xyz]*" or .Dq Li ".*/foo/.*" , but not .Dq Li xyzzy or .Dq Li /foo/ . .It Ic -samefile Ar name True if the file is a hard link to .Ar name . If the command option .Ic -L is specified, it is also true if the file is a symbolic link and -points to +points to .Ar name . .It Ic -size Ar n Ns Op Cm ckMGTP True if the file's size, rounded up, in 512-byte blocks is .Ar n . If .Ar n is followed by a .Cm c , then the primary is true if the file's size is .Ar n bytes (characters). Similarly if .Ar n is followed by a scale indicator then the file's size is compared to .Ar n scaled as: .Pp .Bl -tag -width indent -compact .It Cm k kilobytes (1024 bytes) .It Cm M megabytes (1024 kilobytes) .It Cm G gigabytes (1024 megabytes) .It Cm T terabytes (1024 gigabytes) .It Cm P petabytes (1024 terabytes) .El .It Ic -type Ar t True if the file is of the specified type. Possible file types are as follows: .Pp .Bl -tag -width indent -compact .It Cm b block special .It Cm c character special .It Cm d directory .It Cm f regular file .It Cm l symbolic link .It Cm p FIFO .It Cm s socket .El .It Ic -uid Ar uname The same thing as -.Ar -user Ar uname +.Ar -user Ar uname for compatibility with GNU find. GNU find imposes a restriction that -.Ar uname +.Ar uname is numeric, while -.Xr find 1 +.Xr find 1 does not. .It Ic -user Ar uname True if the file belongs to the user .Ar uname . If .Ar uname is numeric and there is no such user name, then .Ar uname is treated as a user ID. .It Ic -wholename Ar pattern -The same thing as +The same thing as .Ic -path , for GNU find compatibility. .El .Sh OPERATORS The primaries may be combined using the following operators. The operators are listed in order of decreasing precedence. .Pp .Bl -tag -width indent -compact .It Cm \&( Ar expression Cm \&) This evaluates to true if the parenthesized expression evaluates to true. .Pp .It Cm \&! Ar expression .It Cm -not Ar expression This is the unary .Tn NOT operator. It evaluates to true if the expression is false. .Pp .It Cm -false Always false. .It Cm -true Always true. .Pp .It Ar expression Cm -and Ar expression .It Ar expression expression The .Cm -and operator is the logical .Tn AND operator. As it is implied by the juxtaposition of two expressions it does not have to be specified. The expression evaluates to true if both expressions are true. The second expression is not evaluated if the first expression is false. .Pp .It Ar expression Cm -or Ar expression The .Cm -or operator is the logical .Tn OR operator. The expression evaluates to true if either the first or the second expression is true. The second expression is not evaluated if the first expression is true. .El .Pp All operands and primaries must be separate arguments to .Nm . Primaries which themselves take arguments expect each argument to be a separate argument to .Nm . .Sh ENVIRONMENT The .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES and .Ev LC_TIME environment variables affect the execution of the .Nm utility as described in .Xr environ 7 . .Sh EXAMPLES The following examples are shown as given to the shell: .Bl -tag -width indent .It Li "find / \e! -name \*q*.c\*q -print" Print out a list of all the files whose names do not end in .Pa .c . .It Li "find / -newer ttt -user wnj -print" Print out a list of all the files owned by user .Dq wnj that are newer than the file .Pa ttt . .It Li "find / \e! \e( -newer ttt -user wnj \e) -print" Print out a list of all the files which are not both newer than .Pa ttt and owned by .Dq wnj . .It Li "find / \e( -newer ttt -or -user wnj \e) -print" Print out a list of all the files that are either owned by .Dq wnj or that are newer than .Pa ttt . .It Li "find / -newerct '1 minute ago' -print" Print out a list of all the files whose inode change time is more recent than the current time minus one minute. .It Li "find / -type f -exec echo {} \e;" Use the .Xr echo 1 command to print out a list of all the files. .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +" Delete all broken symbolic links in .Pa /usr/ports/packages . .It Li "find /usr/src -name CVS -prune -o -depth +6 -print" Find files and directories that are at least seven levels deep in the working directory .Pa /usr/src . .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print" Is not equivalent to the previous example, since .Ic -prune is not evaluated below level seven. .El .Sh COMPATIBILITY The .Ic -follow primary is deprecated; the .Fl L option should be used instead. See the .Sx STANDARDS section below for details. .Sh SEE ALSO .Xr chflags 1 , .Xr chmod 1 , .Xr cvs 1 , .Xr locate 1 , .Xr lsvfs 1 , .Xr whereis 1 , .Xr which 1 , .Xr xargs 1 , .Xr stat 2 , .Xr acl 3 , .Xr fts 3 , .Xr getgrent 3 , .Xr getpwent 3 , .Xr strmode 3 , .Xr re_format 7 , .Xr symlink 7 .Sh STANDARDS The .Nm utility syntax is a superset of the syntax specified by the .St -p1003.1-2001 standard. .Pp All the single character options except .Fl H and .Fl L as well as .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype , .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin , .Ic -path , -print0 , -regex and all of the .Ic -B* birthtime related primaries are extensions to .St -p1003.1-2001 . .Pp Historically, the .Fl d , L and .Fl x options were implemented using the primaries .Ic -depth , -follow , and .Ic -xdev . These primaries always evaluated to true. As they were really global variables that took effect before the traversal began, some legal expressions could have unexpected results. An example is the expression .Ic -print Cm -o Ic -depth . As .Ic -print always evaluates to true, the standard order of evaluation implies that .Ic -depth would never be evaluated. This is not the case. .Pp The operator .Cm -or was implemented as .Cm -o , and the operator .Cm -and was implemented as .Cm -a . .Pp Historic implementations of the .Ic -exec and .Ic -ok primaries did not replace the string .Dq Li {} in the utility name or the utility arguments if it had preceding or following non-whitespace characters. This version replaces it no matter where in the utility name or arguments it appears. .Pp The .Fl E option was inspired by the equivalent .Xr grep 1 and .Xr sed 1 options. .Sh HISTORY A .Nm command appeared in .At v1 . .Sh BUGS The special characters used by .Nm are also special characters to many shell programs. In particular, the characters .Dq Li * , .Dq Li \&[ , .Dq Li \&] , .Dq Li \&? , .Dq Li \&( , .Dq Li \&) , .Dq Li \&! , .Dq Li \e and .Dq Li \&; may have to be escaped from the shell. .Pp As there is no delimiter separating options and file names or file names and the .Ar expression , it is difficult to specify files named .Pa -xdev or .Pa \&! . These problems are handled by the .Fl f option and the .Xr getopt 3 .Dq Fl Fl construct. .Pp The .Ic -delete primary does not interact well with other options that cause the file system tree traversal options to be changed. .Pp The .Ic -mindepth and .Ic -maxdepth primaries are actually global options (as documented above). They should probably be replaced by options which look like options. Index: stable/9/usr.bin/find =================================================================== --- stable/9/usr.bin/find (revision 237215) +++ stable/9/usr.bin/find (revision 237216) Property changes on: stable/9/usr.bin/find ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /projects/quota64/usr.bin/find:r184125-207707 Merged /head/usr.bin/find:r226702,227006,228761,228857,229067,229538,229997,230127,230555,231544,232322,232994,233121,233648,234206,234772,234782,235915,236338,236346,236365 Merged /projects/largeSMP/usr.bin/find:r221273-222812,222815-223757 Merged /vendor/resolver/dist/usr.bin/find:r1540-186085 Index: stable/9/usr.bin/fstat/fuser.1 =================================================================== --- stable/9/usr.bin/fstat/fuser.1 (revision 237215) +++ stable/9/usr.bin/fstat/fuser.1 (revision 237216) @@ -1,153 +1,153 @@ .\" Copyright (c) 2005-2011 Stanislav Sedov .\" 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 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. .\" .\" $FreeBSD$ .\" .Dd May 13, 2011 .Dt FUSER 1 .Os .Sh NAME .Nm fuser -.Nd list IDs of all processes that have one or more files open +.Nd list IDs of all processes that have one or more files open .Sh SYNOPSIS .Nm .Op Fl cfkmu .Op Fl M Ar core .Op Fl N Ar system .Op Fl s Ar signal .Op Ar .Sh DESCRIPTION The .Nm utility writes to stdout the PIDs of processes that have one or more named files open. For block and character special devices, all processes using files on that device are listed. A file is considered open by a process if it was explicitly opened, is the working directory, root directory, jail root directory, active executable text, kernel trace file or the controlling terminal of the process. If .Fl m option is specified, the .Nm utility will also look through mmapped files. .Pp The following options are available: .Bl -tag -width indent .It Fl c Treat files as mount point and report on any files open in the file system. .It Fl f The report must be only for named files. .It Fl k Send signal to reported processes .Pq SIGKILL by default . .It Fl m Search through mmapped files too. .It Fl u Write the user name associated with each process to stderr. .It Fl M Extract values associated with the name list from the specified core instead of the default .Pa /dev/kmem . .It Fl N Extract the name list from the specified system instead of the default, which is the kernel image the system has booted from. .It Fl s Use given signal name instead of default SIGKILL. .El .Pp The following symbols, written to stderr will indicate how files is used: .Bl -tag -width MOUNT .It Cm r The file is the root directory of the process. .It Cm c The file is the current workdir directory of the process. .It Cm j The file is the jail-root of the process. .It Cm t The file is the kernel tracing file for the process. .It Cm x The file is executable text of the process. .It Cm y The process use this file as its controlling tty. .It Cm m The file is mmapped. .It Cm w The file is open for writing. .It Cm a The file is open as append only .Pq O_APPEND was specified . .It Cm d The process bypasses fs cache while writing to this file .Pq O_DIRECT was specified . .It Cm s Shared lock is hold. .It Cm e Exclusive lock is hold. .El .Sh EXIT STATUS The .Nm utility returns 0 on successful completion and >0 otherwise. .Sh EXAMPLES The command: .Dq Li "fuser -fu ." writes to standard output the process IDs of processes that are using the current directory and writes to stderr an indication of how those processes are using the directory and user names associated with the processes that are using this directory. .Sh SEE ALSO .Xr fstat 1 , .Xr ps 1 , .Xr systat 1 , .Xr iostat 8 , .Xr pstat 8 , .Xr vmstat 8 .Sh STANDARDS The .Nm utility is expected to conform to .St -p1003.1-2004 . .Sh HISTORY The .Nm utility appeared in .Fx 9.0 . .Sh AUTHORS The .Nm utility and this manual page was written by .An Stanislav Sedov Aq stas@FreeBSD.org . .Sh BUGS Since .Nm takes a snapshot of the system, it is only correct for a very short period of time. When working via .Xr kvm 3 interface the report will be limited to filesystems the .Nm utility knows about (currently only cd9660, devfs, nfs, ntfs, nwfs, udf, ufs and zfs). Index: stable/9/usr.bin/fstat =================================================================== --- stable/9/usr.bin/fstat (revision 237215) +++ stable/9/usr.bin/fstat (revision 237216) Property changes on: stable/9/usr.bin/fstat ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/fstat:r233648 Index: stable/9/usr.bin/ipcrm/ipcrm.1 =================================================================== --- stable/9/usr.bin/ipcrm/ipcrm.1 (revision 237215) +++ stable/9/usr.bin/ipcrm/ipcrm.1 (revision 237216) @@ -1,119 +1,119 @@ .\" Copyright (c) 1994 Adam Glass .\" 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. The name of the Author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY Adam Glass ``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 Adam Glass 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 December 12, 2007 .Dt IPCRM 1 .Os .Sh NAME .Nm ipcrm .Nd "remove the specified message queues, semaphore sets, and shared segments" .Sh SYNOPSIS .Nm .Op Fl W .Op Fl v .Op Fl q Ar msqid .Op Fl m Ar shmid .Op Fl s Ar semid .Op Fl Q Ar msgkey .Op Fl M Ar shmkey .Op Fl S Ar semkey .Ar ... .Sh DESCRIPTION The .Nm utility removes the specified message queues, semaphores and shared memory segments. These System V IPC objects can be specified by their creation ID or any associated key. .Pp The following options are generic: .Bl -tag -width indent .It Fl v If specified once with -W or with -1 for an object, it will show all removed objects. If specified twice with -W or with -1 for an objects, it will show all removed objects and all failed removals. .It Fl W Try to wipe all specified message queues, semaphores and shared memory segments. .It Fl y Use the .Xr kvm 3 interface instead of the .Xr sysctl 3 interface to extract the required information. If .Nm is to operate on the running system, using .Xr kvm 3 will require read privileges to .Pa /dev/kmem . .El .Pp The following options are used to specify which IPC objects will be removed. Any number and combination of these options can be used: .Bl -tag -width indent .It Fl q Ar msqid Remove the message queue associated with the ID .Ar msqid from the system. .It Fl m Ar shmid Mark the shared memory segment associated with ID .Ar shmid for removal. This marked segment will be destroyed after the last detach. .It Fl s Ar semid Remove the semaphore set associated with ID .Ar semid from the system. .It Fl Q Ar msgkey Remove the message queue associated with key .Ar msgkey from the system. .It Fl M Ar shmkey Mark the shared memory segment associated with key .Ar shmkey for removal. This marked segment will be destroyed after the last detach. .It Fl S Ar semkey Remove the semaphore set associated with key .Ar semkey from the system. .El .Pp The identifiers and keys associated with these System V IPC objects can be determined by using .Xr ipcs 1 . If the identifier or the key is -1, it will remove all these objects. .Sh SEE ALSO .Xr ipcs 1 .Sh HISTORY The wiping of all System V IPC objects was first implemented in .Fx 6.4 No and 7.1. .Sh AUTHORS -The original author was Adam Glass. +The original author was Adam Glass. The wiping of all System V IPC objects was thought up by Callum Gibson and extended and implemented by Edwin Groothuis. Index: stable/9/usr.bin/ipcrm =================================================================== --- stable/9/usr.bin/ipcrm (revision 237215) +++ stable/9/usr.bin/ipcrm (revision 237216) Property changes on: stable/9/usr.bin/ipcrm ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/ipcrm:r233648 Index: stable/9/usr.bin/locale/locale.1 =================================================================== --- stable/9/usr.bin/locale/locale.1 (revision 237215) +++ stable/9/usr.bin/locale/locale.1 (revision 237216) @@ -1,103 +1,103 @@ .\" .\" Copyright (c) 2003 Alexey Zelkin .\" 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. .\" .\" $FreeBSD$ .\" .Dd November 1, 2005 .Dt LOCALE 1 .Os .Sh NAME .Nm locale .Nd get locale-specific information .Sh SYNOPSIS .Nm .Op Fl a | m .Nm -.Fl k +.Fl k .Ic list .Op Ar prefix .Nm -.Op Fl ck +.Op Fl ck .Ar keyword ... .Sh DESCRIPTION The .Nm utility is supposed to provide most locale specific information to the standard output. .Pp When .Nm is invoked without arguments, it will print out a summary of the current locale environment, subject to the environment settings and internal status. .Pp When .Nm is invoked with the .Ar keyword arguments, and no options are specified, it will print out the values of all keywords specified, using the current locale settings. .Pp The following options are available: .Bl -tag -width indent .It Fl a Print names of all available locales. While looking for locales, .Nm will respect the .Ev PATH_LOCALE environment variable, and use it instead of the system's default locale directory. .It Fl m Print names of all available charmaps. .It Fl k Print the names and values of all selected keywords. .It Fl c Print the category name for all selected keywords. .El .Sh IMPLEMENTATION NOTES The special .Pf ( Fx specific) keyword .Cm list can be used to retrieve the human readable list of all available keywords. If so, a prefix string can be defined to limit the amount of keywords returned. .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr setlocale 3 .Sh BUGS Since .Fx does not support .Em charmap Ns s in their .Tn POSIX meaning, .Nm emulates the .Fl m option using the CODESETs listing of all available locales. Index: stable/9/usr.bin/locale =================================================================== --- stable/9/usr.bin/locale (revision 237215) +++ stable/9/usr.bin/locale (revision 237216) Property changes on: stable/9/usr.bin/locale ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /projects/largeSMP/usr.bin/locale:r221273-222812,222815-223757 Merged /vendor/resolver/dist/usr.bin/locale:r1540-186085 Merged /projects/quota64/usr.bin/locale:r184125-207707 Merged /head/usr.bin/locale:r226702,227006,228761,228857,229067,229538,229997,230127,230555,231544,232322,232994,233121,233648,234206,234772,234782,235915,236338,236346,236365 Index: stable/9/usr.bin/lockf/lockf.1 =================================================================== --- stable/9/usr.bin/lockf/lockf.1 (revision 237215) +++ stable/9/usr.bin/lockf/lockf.1 (revision 237216) @@ -1,156 +1,156 @@ .\" .\" Copyright (C) 1998 John D. Polstra. 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 JOHN D. POLSTRA 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 JOHN D. POLSTRA 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 July 7, 1998 .Dt LOCKF 1 .Os .Sh NAME .Nm lockf .Nd execute a command while holding a file lock .Sh SYNOPSIS .Nm .Op Fl ks .Op Fl t Ar seconds .Ar file .Ar command .Op Ar arguments .Sh DESCRIPTION The .Nm utility acquires an exclusive lock on a .Ar file , creating it if necessary, .Bf Em and removing the file on exit unless explicitly told not to. .Ef While holding the lock, it executes a .Ar command with optional .Ar arguments . After the .Ar command completes, .Nm releases the lock, and removes the .Ar file unless the .Fl k option is specified. .Bx Ns -style locking is used, as described in .Xr flock 2 ; the mere existence of the .Ar file is not considered to constitute a lock. .Pp If the .Nm utility is being used to facilitate concurrency between a number of processes, it is recommended that the .Fl k option be used. This will guarantee lock ordering, as well as implement a performance enhanced algorithm which minimizes CPU load associated with concurrent unlink, drop and re-acquire activity. It should be noted that if the .Fl k option is not used, then no guarantees around lock ordering can be made. .Pp The following options are supported: .Bl -tag -width ".Fl t Ar seconds" .It Fl k Causes the lock file to be kept (not removed) after the command completes. .It Fl s Causes .Nm to operate silently. Failure to acquire the lock is indicated only in the exit status. .It Fl t Ar seconds Specifies a timeout for waiting for the lock. By default, .Nm waits indefinitely to acquire the lock. If a timeout is specified with this option, .Nm will wait at most the given number of .Ar seconds before giving up. A timeout of 0 may be given, in which case .Nm will fail unless it can acquire the lock immediately. When a lock times out, .Ar command is .Em not executed. .El .Pp In no event will .Nm break a lock that is held by another process. .Sh EXIT STATUS If .Nm successfully acquires the lock, it returns the exit status produced by .Ar command . Otherwise, it returns one of the exit codes defined in .Xr sysexits 3 , as follows: .Bl -tag -width ".Dv EX_CANTCREAT" .It Dv EX_TEMPFAIL The specified lock file was already locked by another process. .It Dv EX_CANTCREAT The .Nm utility was unable to create the lock file, e.g., because of insufficient access privileges. .It Dv EX_USAGE There was an error on the .Nm command line. .It Dv EX_OSERR A system call (e.g., .Xr fork 2 ) failed unexpectedly. .It Dv EX_SOFTWARE -The +The .Ar command did not exit normally, but may have been signaled or stopped. .El .Sh SEE ALSO .Xr flock 2 , .Xr sysexits 3 .Sh HISTORY A .Nm utility first appeared in .Fx 2.2 . .Sh AUTHORS .An John Polstra Aq jdp@polstra.com Index: stable/9/usr.bin/lockf =================================================================== --- stable/9/usr.bin/lockf (revision 237215) +++ stable/9/usr.bin/lockf (revision 237216) Property changes on: stable/9/usr.bin/lockf ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /projects/largeSMP/usr.bin/lockf:r221273-222812,222815-223757 Merged /vendor/resolver/dist/usr.bin/lockf:r1540-186085 Merged /projects/quota64/usr.bin/lockf:r184125-207707 Merged /head/usr.bin/lockf:r226702,227006,228761,228857,229067,229538,229997,230127,230555,231544,232322,232994,233121,233648,234206,234772,234782,235915,236338,236346,236365 Index: stable/9/usr.bin/ministat/ministat.1 =================================================================== --- stable/9/usr.bin/ministat/ministat.1 (revision 237215) +++ stable/9/usr.bin/ministat/ministat.1 (revision 237216) @@ -1,130 +1,130 @@ .\" .\" Copyright (c) 2007 Poul-Henning Kamp .\" 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. .\" .\" $FreeBSD$ .\" .Dd June 28, 2010 .Dt MINISTAT 1 .Os .Sh NAME .Nm ministat .Nd statistics utility .Sh SYNOPSIS .Nm .Op Fl ns .Op Fl C Ar column .Op Fl c Ar confidence_level .Op Fl d Ar delimiter .Op Fl w Op width .Op Ar .Sh DESCRIPTION The .Nm command calculates fundamental statistical properties of numeric data in the specified files or, if no file is specified, standard input. .Pp The options are as follows: .Bl -tag -width Fl .It Fl n Just report the raw statistics of the input, suppress the ASCII-art plot and the relative comparisons. .It Fl s Print the average/median/stddev bars on separate lines in the ASCII-art plot, to avoid overlap. .It Fl C Ar column Specify which column of data to use. By default the first column in the input file(s) are used. .It Fl c Ar confidence_level Specify desired confidence level for Student's T analysis. Possible values are 80, 90, 95, 98, 99 and 99.5 % .It Fl d Ar delimiter Specifies the column delimiter characters, default is SPACE and TAB. See .Xr strtok 3 for details. .It Fl w Ar width Width of ASCII-art plot in characters, default is 74. .El .Pp A sample output could look like this: .Bd -literal -offset indent $ ministat -s -w 60 iguana chameleon x iguana + chameleon +------------------------------------------------------------+ |x * x * + + x +| | |________M______A_______________| | | |________________M__A___________________| | +------------------------------------------------------------+ N Min Max Median Avg Stddev x 7 50 750 200 300 238.04761 + 5 150 930 500 540 299.08193 No difference proven at 95.0% confidence .Ed .Pp If .Nm tells you, as in the example above, that there is no difference proven at 95% confidence, the two data sets you gave it are for all statistical purposes identical. .Pp You have the option of lowering your standards by specifying a lower confidence level: .Bd -literal -offset indent $ ministat -s -w 60 -c 80 iguana chameleon x iguana + chameleon +------------------------------------------------------------+ |x * x * + + x +| | |________M______A_______________| | | |________________M__A___________________| | +------------------------------------------------------------+ N Min Max Median Avg Stddev x 7 50 750 200 300 238.04761 + 5 150 930 500 540 299.08193 Difference at 80.0% confidence 240 +/- 212.215 80% +/- 70.7384% (Student's t, pooled s = 264.159) .Ed .Pp But a lower standard does not make your data any better, and the example is only included here to show the format of the output when a statistical difference is proven according to Student's T method. .Sh SEE ALSO Any mathematics text on basic statistics, for instances Larry Gonicks excellent "Cartoon Guide to Statistics" which supplied the above example. .Sh HISTORY The .Nm -command was written by Poul-Henning Kamp out of frustration +command was written by Poul-Henning Kamp out of frustration over all the bogus benchmark claims made by people with no understanding of the importance of uncertainty and statistics. .Pp From -.Fx 5.2 +.Fx 5.2 it has lived in the source tree as a developer tool, graduating to the installed system from .Fx 8.0 . Index: stable/9/usr.bin/ministat =================================================================== --- stable/9/usr.bin/ministat (revision 237215) +++ stable/9/usr.bin/ministat (revision 237216) Property changes on: stable/9/usr.bin/ministat ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /head/usr.bin/ministat:r226702,227006,228761,228857,229067,229538,229997,230127,230555,231544,232322,232994,233121,233648,234206,234772,234782,235915,236338,236346,236365 Merged /projects/largeSMP/usr.bin/ministat:r221273-222812,222815-223757 Merged /vendor/resolver/dist/usr.bin/ministat:r1540-186085 Merged /projects/quota64/usr.bin/ministat:r184125-207707 Index: stable/9/usr.bin/printf/printf.1 =================================================================== --- stable/9/usr.bin/printf/printf.1 (revision 237215) +++ stable/9/usr.bin/printf/printf.1 (revision 237216) @@ -1,379 +1,379 @@ .\" Copyright (c) 1989, 1990, 1993 .\" 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. .\" 4. 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. .\" .\" @(#)printf.1 8.1 (Berkeley) 6/6/93 .\" $FreeBSD$ .\" .Dd May 28, 2011 .Dt PRINTF 1 .Os .Sh NAME .Nm printf .Nd formatted output .Sh SYNOPSIS .Nm .Ar format Op Ar arguments ... .Sh DESCRIPTION The .Nm utility formats and prints its arguments, after the first, under control of the .Ar format . The .Ar format is a character string which contains three types of objects: plain characters, which are simply copied to standard output, character escape sequences which are converted and copied to the standard output, and format specifications, each of which causes printing of the next successive .Ar argument . .Pp The .Ar arguments after the first are treated as strings if the corresponding format is either .Cm c , b or .Cm s ; otherwise it is evaluated as a C constant, with the following extensions: .Pp .Bl -bullet -offset indent -compact .It A leading plus or minus sign is allowed. .It If the leading character is a single or double quote, the value is the character code of the next character. .El .Pp The format string is reused as often as necessary to satisfy the .Ar arguments . Any extra format specifications are evaluated with zero or the null string. .Pp Character escape sequences are in backslash notation as defined in the .St -ansiC , with extensions. The characters and their meanings are as follows: .Pp .Bl -tag -width Ds -offset indent -compact .It Cm \ea Write a character. .It Cm \eb Write a character. .It Cm \ec Ignore remaining characters in this string. .It Cm \ef Write a character. .It Cm \en Write a character. .It Cm \er Write a character. .It Cm \et Write a character. .It Cm \ev Write a character. .It Cm \e\' Write a character. .It Cm \e\e Write a backslash character. .It Cm \e Ns Ar num Write a byte whose value is the 1-, 2-, or 3-digit octal number .Ar num . Multibyte characters can be constructed using multiple .Cm \e Ns Ar num sequences. .El .Pp Each format specification is introduced by the percent character (``%''). The remainder of the format specification includes, in the following order: .Bl -tag -width Ds .It "Zero or more of the following flags:" .Bl -tag -width Ds .It Cm # A `#' character specifying that the value should be printed in an ``alternate form''. For .Cm b , c , d , s and .Cm u formats, this option has no effect. For the .Cm o formats the precision of the number is increased to force the first character of the output string to a zero. For the .Cm x .Pq Cm X format, a non-zero result has the string .Li 0x .Pq Li 0X prepended to it. For .Cm a , A , e , E , f , F , g and .Cm G formats, the result will always contain a decimal point, even if no digits follow the point (normally, a decimal point only appears in the results of those formats if a digit follows the decimal point). For .Cm g and .Cm G formats, trailing zeros are not removed from the result as they would otherwise be; .It Cm \&\- A minus sign `\-' which specifies .Em left adjustment of the output in the indicated field; .It Cm \&+ A `+' character specifying that there should always be a sign placed before the number when using signed formats. .It Sq \&\ \& A space specifying that a blank should be left before a positive number for a signed format. A `+' overrides a space if both are used; .It Cm \&0 A zero `0' character indicating that zero-padding should be used rather than blank-padding. A `\-' overrides a `0' if both are used; .El .It "Field Width:" An optional digit string specifying a .Em field width ; if the output string has fewer bytes than the field width it will be blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up the field width (note that a leading zero is a flag, but an embedded zero is part of a field width); .It Precision: An optional period, .Sq Cm \&.\& , followed by an optional digit string giving a .Em precision which specifies the number of digits to appear after the decimal point, for .Cm e and .Cm f formats, or the maximum number of bytes to be printed from a string; if the digit string is missing, the precision is treated as zero; .It Format: A character which indicates the type of format to use (one of .Cm diouxXfFeEgGaAcsb ) . The uppercase formats differ from their lowercase counterparts only in that the output of the former is entirely in uppercase. The floating-point format specifiers .Pq Cm fFeEgGaA may be prefixed by an .Cm L to request that additional precision be used, if available. .El .Pp A field width or precision may be .Sq Cm \&* instead of a digit string. In this case an .Ar argument supplies the field width or precision. .Pp The format characters and their meanings are: .Bl -tag -width Fl .It Cm diouXx The .Ar argument is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, or unsigned hexadecimal (X or x), respectively. .It Cm fF The .Ar argument is printed in the style `[\-]ddd.ddd' where the number of d's after the decimal point is equal to the precision specification for the argument. If the precision is missing, 6 digits are given; if the precision is explicitly 0, no digits and no decimal point are printed. The values \*[If] and \*[Na] are printed as .Ql inf and .Ql nan , respectively. .It Cm eE The .Ar argument is printed in the style .Cm e .Sm off .Sq Op - Ar d.ddd No \(+- Ar dd .Sm on where there is one digit before the decimal point and the number after is equal to the precision specification for the argument; when the precision is missing, 6 digits are produced. The values \*[If] and \*[Na] are printed as .Ql inf and .Ql nan , respectively. .It Cm gG The .Ar argument is printed in style .Cm f .Pq Cm F or in style .Cm e .Pq Cm E whichever gives full precision in minimum space. .It Cm aA The .Ar argument is printed in style .Sm off .Sq Op - Ar h.hhh No \(+- Li p Ar d .Sm on where there is one digit before the hexadecimal point and the number after is equal to the precision specification for the argument; when the precision is missing, enough digits are produced to convey the argument's exact double-precision floating-point representation. The values \*[If] and \*[Na] are printed as .Ql inf and .Ql nan , respectively. .It Cm c The first byte of .Ar argument is printed. .It Cm s Bytes from the string .Ar argument are printed until the end is reached or until the number of bytes indicated by the precision specification is reached; however if the precision is 0 or missing, the string is printed entirely. .It Cm b As for .Cm s , but interpret character escapes in backslash notation in the string .Ar argument . The permitted escape sequences are slightly different in that octal escapes are .Cm \e0 Ns Ar num instead of .Cm \e Ns Ar num . .It Cm \&% Print a `%'; no argument is used. .El .Pp The decimal point character is defined in the program's locale (category .Dv LC_NUMERIC ) . .Pp In no case does a non-existent or small field width cause truncation of a field; padding takes place only if the specified field width exceeds the actual width. .Pp Some shells may provide a builtin .Nm command which is similar or identical to this utility. Consult the .Xr builtin 1 manual page. .Sh EXIT STATUS .Ex -std .Sh COMPATIBILITY The traditional .Bx behavior of converting arguments of numeric formats not beginning with a digit to the .Tn ASCII code of the first character is not supported. .Sh SEE ALSO .Xr builtin 1 , .Xr echo 1 , .Xr sh 1 , .Xr printf 3 .Sh STANDARDS The .Nm command is expected to be compatible with the .St -p1003.2 specification. .Sh HISTORY The .Nm command appeared in .Bx 4.3 Reno . It is modeled after the standard library function, .Xr printf 3 . .Sh CAVEATS .Tn ANSI hexadecimal character constants were deliberately not provided. .Pp Trying to print a dash ("-") as the first character causes .Nm to interpret the dash as a program argument. .Nm -- -must be used before +must be used before .Ar format . .Pp If the locale contains multibyte characters (such as UTF-8), the .Cm c format and .Cm b and .Cm s formats with a precision may not operate as expected. .Sh BUGS Since the floating point numbers are translated from .Tn ASCII to floating-point and then back again, floating-point precision may be lost. (By default, the number is translated to an IEEE-754 double-precision value before being printed. The .Cm L modifier may produce additional precision, depending on the hardware platform.) .Pp The escape sequence \e000 is the string terminator. When present in the argument for the .Cm b format, the argument will be truncated at the \e000 character. .Pp Multibyte characters are not recognized in format strings (this is only a problem if .Ql % can appear inside a multibyte character). Index: stable/9/usr.bin/printf =================================================================== --- stable/9/usr.bin/printf (revision 237215) +++ stable/9/usr.bin/printf (revision 237216) Property changes on: stable/9/usr.bin/printf ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/printf:r233648 Index: stable/9/usr.bin/procstat/procstat.1 =================================================================== --- stable/9/usr.bin/procstat/procstat.1 (revision 237215) +++ stable/9/usr.bin/procstat/procstat.1 (revision 237216) @@ -1,462 +1,462 @@ .\"- .\" Copyright (c) 2007-2009 Robert N. M. Watson .\" 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. .\" .\" $FreeBSD$ .\" .Dd March 23, 2012 .Dt PROCSTAT 1 .Os .Sh NAME .Nm procstat .Nd get detailed process information .Sh SYNOPSIS .Nm .Op Fl h .Op Fl n .Op Fl C .Op Fl w Ar interval .Op Fl b | c | e | f | i | j | k | l | s | t | v | x .Op Fl a | Ar pid ... .Sh DESCRIPTION The .Nm utility displays detailed information about the processes identified by the .Ar pid arguments, or if the .Fl a flag is used, all processes. .Pp By default, basic process statistics are printed; one of the following options may be specified in order to select more detailed process information for printing: .Bl -tag -width indent .It Fl b Display binary information for the process. -.It Fl c +.It Fl c Display command line arguments for the process. .It Fl e Display environment variables for the process. .It Fl f Display file descriptor information for the process. .It Fl i Display signal pending and disposition information for the process. .It Fl j Display signal pending and blocked information for the process threads. .It Fl k Display the stacks of kernel threads in the process, excluding stacks of threads currently running on a CPU and threads with stacks swapped to disk. If the flag is repeated, function offsets as well as function names are printed. .It Fl l Display resource limits for the process. .It Fl s Display security credential information for the process. .It Fl t Display thread information for the process. .It Fl v Display virtual memory mappings for the process. .It Fl x Display ELF auxiliary vector for the process. .El .Pp All options generate output in the format of a table, the first field of which is the process ID to which the row of information corresponds. The .Fl h flag may be used to suppress table headers. .Pp The .Fl w flag may be used to specify a wait interval at which to repeat the printing of the requested process information. If the .Fl w flag is not specified, the output will not repeat. .Pp The .Fl C flag requests the printing of additional capability information in the file descriptor view. .Pp Some information, such as VM and file descriptor information, is available only to the owner of a process or the superuser. .Ss Binary Information Display the process ID, command, and path to the process binary: .Pp .Bl -tag -width indent -compact .It PID process ID .It COMM command .It OSREL osreldate for process binary .It PATH path to process binary (if available) .El .Ss Command Line Arguments Display the process ID, command, and command line arguments: .Pp .Bl -tag -width indent -compact .It PID process ID .It COMM command .It ARGS command line arguments (if available) .El .Ss File Descriptors Display detailed information about each file descriptor referenced by a process, including the process ID, command, file descriptor number, and per-file descriptor object information, such as object type and file system path. By default, the following information will be printed: .Pp .Bl -tag -width indent -compact .It PID process ID .It COMM command .It FD file descriptor number or cwd/root/jail .It T file descriptor type .It V vnode type .It FLAGS file descriptor flags .It REF file descriptor reference count .It OFFSET file descriptor offset .It PRO network protocol .It NAME file path or socket addresses (if available) .El .Pp The following file descriptor types may be displayed: .Pp .Bl -tag -width X -compact .It c crypto .It e POSIX semaphore .It f fifo .It h shared memory .It k kqueue .It m message queue .It p pipe .It s socket .It t pseudo-terminal master .It v vnode .El .Pp The following vnode types may be displayed: .Pp .Bl -tag -width X -compact .It - not a vnode .It b block device .It c character device .It d directory .It f fifo .It l symbolic link .It r regular file .It s socket .It x revoked device .El .Pp The following file descriptor flags may be displayed: .Pp .Bl -tag -width X -compact .It r read .It w write .It a append .It s async .It f fsync .It n non-blocking .It d direct I/O .It l lock held .It c descriptor is a capability .El .Pp If the .Fl C flag is specified, the vnode type, reference count, and offset fields will be omitted, and a new capabilities field will be included listing capabilities, as described in .Xr cap_new 2 , present for each capability descriptor. .Ss Signal Disposition Information Display signal pending and disposition for a process: .Pp .Bl -tag -width ident -compact .It PID process ID .It COMM command .It SIG signal name .It FLAGS process signal disposition details, three symbols .Bl -tag -width X -compact .It P if signal is pending in the global process queue, - otherwise .It I if signal delivery disposition is SIGIGN, - otherwise .It C if signal delivery is to catch it, - otherwise .El .El .Pp If .Fl n switch is given, the signal numbers are shown instead of signal names. .Ss Thread Signal Information Display signal pending and blocked for a process threads: .Pp .Bl -tag -width ident -compact .It PID process ID .It COMM command .It TID thread ID .It SIG signal name .It FLAGS thread signal delivery status, two symbols .Bl -tag -width X -compact .It P if signal is pending for the thread, - otherwise .It B if signal is blocked in the thread signal mask, - if not blocked .El .El .Pp The .Fl n switch has the same effect as for the .Fl i switch, the signals numbers are shown instead of signal names. .Ss Kernel Thread Stacks Display kernel thread stacks for a process, allowing further interpretation of thread wait channels. If the .Fl k flag is repeated, function offsets, not just function names, are printed. .Pp This feature requires .Cd "options STACK" or .Cd "options DDB" to be compiled into the kernel. .Pp .Bl -tag -width indent -compact .It PID process ID .It TID thread ID .It COMM command .It TDNAME thread name .It KSTACK kernel thread call stack .El .Ss Security Credentials Display process credential information: .Pp .Bl -tag -width indent -compact .It PID process ID .It COMM command .It EUID effective user ID .It RUID real user ID .It SVUID saved user ID .It EGID effective group ID .It RGID real group ID .It SVGID saved group ID .It UMASK file creation mode mask .It FLAGS credential flags .It GROUPS group set .El .Pp The following credential flags may be displayed: .Pp .Bl -tag -width X -compact .It C capability mode .El .Ss Thread Information Display per-thread information, including process ID, per-thread ID, name, CPU, and execution state: .Pp .Bl -tag -width indent -compact .It PID process ID .It TID thread ID .It COMM command .It TDNAME thread name .It CPU current or most recent CPU run on .It PRI thread priority .It STATE thread state .It WCHAN thread wait channel .El .Ss Virtual Memory Mappings Display process virtual memory mappings, including addresses, mapping meta-data, and mapped object information: .Pp .Bl -tag -width indent -compact .It PID process ID .It START starting address of mapping .It END ending address of mapping .It PRT protection flags .It RES resident pages .It PRES private resident pages .It REF reference count .It SHD shadow page count .It FL mapping flags .It TP VM object type .El .Pp The following protection flags may be displayed: .Pp .Bl -tag -width X -compact .It r read .It w write .It x execute .El .Pp The following VM object types may be displayed: .Pp .Bl -tag -width XX -compact .It -- none .It dd dead .It df default .It dv device .It ph physical .It sw swap .It vn vnode .El .Pp The following mapping flags may be displayed: .Pp .Bl -tag -width X -compact .It C copy-on-write .It N needs copy .It S one or more superpage mappings are used .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr fstat 1 , .Xr ps 1 , .Xr sockstat 1 , .Xr cap_enter 2 , .Xr cap_new 2 , .Xr ddb 4 , .Xr stack 9 .Sh AUTHORS .An Robert N M Watson .Sh BUGS Some field values may include spaces, which limits the extent to which the output of .Nm may be mechanically parsed. .Pp The display of open file or memory mapping pathnames is implemented using the kernel's name cache. If a file system does not use the name cache, or the path to a file is not in the cache, a path will not be displayed. .Pp .Nm currently supports extracting data only from a live kernel, and not from kernel crash dumps. Index: stable/9/usr.bin/procstat =================================================================== --- stable/9/usr.bin/procstat (revision 237215) +++ stable/9/usr.bin/procstat (revision 237216) Property changes on: stable/9/usr.bin/procstat ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/procstat:r233648 Index: stable/9/usr.bin/sed/sed.1 =================================================================== --- stable/9/usr.bin/sed/sed.1 (revision 237215) +++ stable/9/usr.bin/sed/sed.1 (revision 237216) @@ -1,636 +1,636 @@ .\" Copyright (c) 1992, 1993 .\" 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. .\" 4. 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. .\" .\" @(#)sed.1 8.2 (Berkeley) 12/30/93 .\" $FreeBSD$ .\" .Dd May 24, 2009 .Dt SED 1 .Os .Sh NAME .Nm sed .Nd stream editor .Sh SYNOPSIS .Nm .Op Fl Ealnr .Ar command .Op Ar .Nm .Op Fl Ealnr .Op Fl e Ar command .Op Fl f Ar command_file .Op Fl I Ar extension .Op Fl i Ar extension .Op Ar .Sh DESCRIPTION The .Nm utility reads the specified files, or the standard input if no files are specified, modifying the input as specified by a list of commands. The input is then written to the standard output. .Pp A single command may be specified as the first argument to .Nm . Multiple commands may be specified by using the .Fl e or .Fl f options. All commands are applied to the input in the order they are specified regardless of their origin. .Pp The following options are available: .Bl -tag -width indent .It Fl E Interpret regular expressions as extended (modern) regular expressions rather than basic regular expressions (BRE's). The .Xr re_format 7 manual page fully describes both formats. .It Fl a The files listed as parameters for the .Dq w functions are created (or truncated) before any processing begins, by default. The .Fl a option causes .Nm to delay opening each file until a command containing the related .Dq w function is applied to a line of input. .It Fl e Ar command Append the editing commands specified by the .Ar command argument to the list of commands. .It Fl f Ar command_file Append the editing commands found in the file .Ar command_file to the list of commands. The editing commands should each be listed on a separate line. .It Fl I Ar extension Edit files in-place, saving backups with the specified .Ar extension . If a zero-length .Ar extension is given, no backup will be saved. It is not recommended to give a zero-length .Ar extension when in-place editing files, as you risk corruption or partial content in situations where disk space is exhausted, etc. .Pp Note that in-place editing with .Fl I still takes place in a single continuous line address space covering all files, although each file preserves its individuality instead of forming one output stream. The line counter is never reset between files, address ranges can span file boundaries, and the .Dq $ address matches only the last line of the last file. (See .Sx "Sed Addresses" . ) That can lead to unexpected results in many cases of in-place editing, where using .Fl i is desired. .It Fl i Ar extension Edit files in-place similarly to .Fl I , but treat each file independently from other files. In particular, line numbers in each file start at 1, the .Dq $ address matches the last line of the current file, and address ranges are limited to the current file. (See .Sx "Sed Addresses" . ) The net result is as though each file were edited by a separate .Nm instance. .It Fl l Make output line buffered. .It Fl n By default, each line of input is echoed to the standard output after all of the commands have been applied to it. The .Fl n option suppresses this behavior. .It Fl r Same as -.Fl E +.Fl E for compatibility with GNU sed. .El .Pp The form of a .Nm command is as follows: .Pp .Dl [address[,address]]function[arguments] .Pp Whitespace may be inserted before the first address and the function portions of the command. .Pp Normally, .Nm cyclically copies a line of input, not including its terminating newline character, into a .Em "pattern space" , (unless there is something left after a .Dq D function), applies all of the commands with addresses that select that pattern space, copies the pattern space to the standard output, appending a newline, and deletes the pattern space. .Pp Some of the functions use a .Em "hold space" to save all or part of the pattern space for subsequent retrieval. .Sh "Sed Addresses" An address is not required, but if specified must have one of the following formats: .Bl -bullet -offset indent .It a number that counts input lines cumulatively across input files (or in each file independently if a .Fl i option is in effect); .It a dollar .Pq Dq $ character that addresses the last line of input (or the last line of the current file if a .Fl i option was specified); .It a context address that consists of a regular expression preceded and followed by a -delimiter. The closing delimiter can also optionally be followed by the +delimiter. The closing delimiter can also optionally be followed by the .Dq I character, to indicate that the regular expression is to be matched in a case-insensitive way. .El .Pp A command line with no addresses selects every pattern space. .Pp A command line with one address selects all of the pattern spaces that match the address. .Pp A command line with two addresses selects an inclusive range. This range starts with the first pattern space that matches the first address. The end of the range is the next following pattern space that matches the second address. If the second address is a number less than or equal to the line number first selected, only that line is selected. The number in the second address may be prefixed with a .Pq Dq \&+ to specify the number of lines to match after the first pattern. In the case when the second address is a context address, .Nm does not re-match the second address against the pattern space that matched the first address. Starting at the first line following the selected range, .Nm starts looking again for the first address. .Pp Editing commands can be applied to non-selected pattern spaces by use of the exclamation character .Pq Dq \&! function. .Sh "Sed Regular Expressions" The regular expressions used in .Nm , by default, are basic regular expressions (BREs, see .Xr re_format 7 for more information), but extended (modern) regular expressions can be used instead if the .Fl E flag is given. In addition, .Nm has the following two additions to regular expressions: .Pp .Bl -enum -compact .It In a context address, any character other than a backslash .Pq Dq \e or newline character may be used to delimit the regular expression. The opening delimiter needs to be preceded by a backslash unless it is a slash. For example, the context address .Li \exabcx is equivalent to .Li /abc/ . Also, putting a backslash character before the delimiting character within the regular expression causes the character to be treated literally. For example, in the context address .Li \exabc\exdefx , the RE delimiter is an .Dq x and the second .Dq x stands for itself, so that the regular expression is .Dq abcxdef . .Pp .It The escape sequence \en matches a newline character embedded in the pattern space. You cannot, however, use a literal newline character in an address or in the substitute command. .El .Pp One special feature of .Nm regular expressions is that they can default to the last regular expression used. If a regular expression is empty, i.e., just the delimiter characters are specified, the last regular expression encountered is used instead. The last regular expression is defined as the last regular expression used as part of an address or substitute command, and at run-time, not compile-time. For example, the command .Dq /abc/s//XXX/ will substitute .Dq XXX for the pattern .Dq abc . .Sh "Sed Functions" In the following list of commands, the maximum number of permissible addresses for each command is indicated by [0addr], [1addr], or [2addr], representing zero, one, or two addresses. .Pp The argument .Em text consists of one or more lines. To embed a newline in the text, precede it with a backslash. Other backslashes in text are deleted and the following character taken literally. .Pp The .Dq r and .Dq w functions take an optional file parameter, which should be separated from the function letter by white space. Each file given as an argument to .Nm is created (or its contents truncated) before any input processing begins. .Pp The .Dq b , .Dq r , .Dq s , .Dq t , .Dq w , .Dq y , .Dq \&! , and .Dq \&: functions all accept additional arguments. The following synopses indicate which arguments have to be separated from the function letters by white space characters. .Pp Two of the functions take a function-list. This is a list of .Nm functions separated by newlines, as follows: .Bd -literal -offset indent { function function ... function } .Ed .Pp The .Dq { can be preceded by white space and can be followed by white space. The function can be preceded by white space. The terminating .Dq } must be preceded by a newline, and may also be preceded by white space. .Pp .Bl -tag -width "XXXXXX" -compact .It [2addr] function-list Execute function-list only when the pattern space is selected. .Pp .It [1addr]a\e .It text Write .Em text to standard output immediately before each attempt to read a line of input, whether by executing the .Dq N function or by beginning a new cycle. .Pp .It [2addr]b[label] Branch to the .Dq \&: function with the specified label. If the label is not specified, branch to the end of the script. .Pp .It [2addr]c\e .It text Delete the pattern space. With 0 or 1 address or at the end of a 2-address range, .Em text is written to the standard output. .Pp .It [2addr]d Delete the pattern space and start the next cycle. .Pp .It [2addr]D Delete the initial segment of the pattern space through the first newline character and start the next cycle. .Pp .It [2addr]g Replace the contents of the pattern space with the contents of the hold space. .Pp .It [2addr]G Append a newline character followed by the contents of the hold space to the pattern space. .Pp .It [2addr]h Replace the contents of the hold space with the contents of the pattern space. .Pp .It [2addr]H Append a newline character followed by the contents of the pattern space to the hold space. .Pp .It [1addr]i\e .It text Write .Em text to the standard output. .Pp .It [2addr]l (The letter ell.) Write the pattern space to the standard output in a visually unambiguous form. This form is as follows: .Pp .Bl -tag -width "carriage-returnXX" -offset indent -compact .It backslash \e\e .It alert \ea .It form-feed \ef .It carriage-return \er .It tab \et .It vertical tab \ev .El .Pp Nonprintable characters are written as three-digit octal numbers (with a preceding backslash) for each byte in the character (most significant byte first). Long lines are folded, with the point of folding indicated by displaying a backslash followed by a newline. The end of each line is marked with a .Dq $ . .Pp .It [2addr]n Write the pattern space to the standard output if the default output has not been suppressed, and replace the pattern space with the next line of input. .Pp .It [2addr]N Append the next line of input to the pattern space, using an embedded newline character to separate the appended material from the original contents. Note that the current line number changes. .Pp .It [2addr]p Write the pattern space to standard output. .Pp .It [2addr]P Write the pattern space, up to the first newline character to the standard output. .Pp .It [1addr]q Branch to the end of the script and quit without starting a new cycle. .Pp .It [1addr]r file Copy the contents of .Em file to the standard output immediately before the next attempt to read a line of input. If .Em file cannot be read for any reason, it is silently ignored and no error condition is set. .Pp .It [2addr]s/regular expression/replacement/flags Substitute the replacement string for the first instance of the regular expression in the pattern space. Any character other than backslash or newline can be used instead of a slash to delimit the RE and the replacement. Within the RE and the replacement, the RE delimiter itself can be used as a literal character if it is preceded by a backslash. .Pp An ampersand .Pq Dq & appearing in the replacement is replaced by the string matching the RE. The special meaning of .Dq & in this context can be suppressed by preceding it by a backslash. The string .Dq \e# , where .Dq # is a digit, is replaced by the text matched by the corresponding backreference expression (see .Xr re_format 7 ) . .Pp A line can be split by substituting a newline character into it. To specify a newline character in the replacement string, precede it with a backslash. .Pp The value of .Em flags in the substitute function is zero or more of the following: .Bl -tag -width "XXXXXX" -offset indent .It Ar N Make the substitution only for the .Ar N Ns 'th occurrence of the regular expression in the pattern space. .It g Make the substitution for all non-overlapping matches of the regular expression, not just the first one. .It p Write the pattern space to standard output if a replacement was made. If the replacement string is identical to that which it replaces, it is still considered to have been a replacement. .It w Em file Append the pattern space to .Em file if a replacement was made. If the replacement string is identical to that which it replaces, it is still considered to have been a replacement. .It I Match the regular expression in a case-insensitive way. .El .Pp .It [2addr]t [label] Branch to the .Dq \&: function bearing the label if any substitutions have been made since the most recent reading of an input line or execution of a .Dq t function. If no label is specified, branch to the end of the script. .Pp .It [2addr]w Em file Append the pattern space to the .Em file . .Pp .It [2addr]x Swap the contents of the pattern and hold spaces. .Pp .It [2addr]y/string1/string2/ Replace all occurrences of characters in .Em string1 in the pattern space with the corresponding characters from .Em string2 . Any character other than a backslash or newline can be used instead of a slash to delimit the strings. Within .Em string1 and .Em string2 , a backslash followed by any character other than a newline is that literal character, and a backslash followed by an ``n'' is replaced by a newline character. .Pp .It [2addr]!function .It [2addr]!function-list Apply the function or function-list only to the lines that are .Em not selected by the address(es). .Pp .It [0addr]:label This function does nothing; it bears a label to which the .Dq b and .Dq t commands may branch. .Pp .It [1addr]= Write the line number to the standard output followed by a newline character. .Pp .It [0addr] Empty lines are ignored. .Pp .It [0addr]# The .Dq # and the remainder of the line are ignored (treated as a comment), with the single exception that if the first two characters in the file are .Dq #n , the default output is suppressed. This is the same as specifying the .Fl n option on the command line. .El .Sh ENVIRONMENT The .Ev COLUMNS , LANG , LC_ALL , LC_CTYPE and .Ev LC_COLLATE environment variables affect the execution of .Nm as described in .Xr environ 7 . .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr awk 1 , .Xr ed 1 , .Xr grep 1 , .Xr regex 3 , .Xr re_format 7 .Sh STANDARDS The .Nm utility is expected to be a superset of the .St -p1003.2 specification. .Pp The .Fl E , I , a and .Fl i options, the prefixing .Dq \&+ in the second member of an address range, as well as the .Dq I flag to the address regular expression and substitution command are non-standard .Fx extensions and may not be available on other operating systems. .Sh HISTORY A .Nm command, written by .An L. E. McMahon , appeared in .At v7 . .Sh AUTHORS .An "Diomidis D. Spinellis" Aq dds@FreeBSD.org .Sh BUGS Multibyte characters containing a byte with value 0x5C .Tn ( ASCII .Ql \e ) may be incorrectly treated as line continuation characters in arguments to the .Dq a , .Dq c and .Dq i commands. Multibyte characters cannot be used as delimiters with the .Dq s and .Dq y commands. Index: stable/9/usr.bin/sed =================================================================== --- stable/9/usr.bin/sed (revision 237215) +++ stable/9/usr.bin/sed (revision 237216) Property changes on: stable/9/usr.bin/sed ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/sed:r233648 Index: stable/9/usr.bin/tftp/tftp.1 =================================================================== --- stable/9/usr.bin/tftp/tftp.1 (revision 237215) +++ stable/9/usr.bin/tftp/tftp.1 (revision 237216) @@ -1,277 +1,272 @@ .\" Copyright (c) 1990, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. 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. .\" .\" @(#)tftp.1 8.2 (Berkeley) 4/18/94 .\" $FreeBSD$ .\" .Dd June 22, 2011 .Dt TFTP 1 .Os .Sh NAME .Nm tftp .Nd trivial file transfer program .Sh SYNOPSIS .Nm .Op Ar host Op Ar port .Sh DESCRIPTION The .Nm utility is the user interface to the Internet .Tn TFTP (Trivial File Transfer Protocol), which allows users to transfer files to and from a remote machine. The remote .Ar host may be specified on the command line, in which case .Nm uses .Ar host as the default host for future transfers (see the .Cm connect command below). .Sh COMMANDS Once .Nm is running, it issues the prompt .Dq Li tftp> and recognizes the following commands: .Pp .Bl -tag -width verbose -compact .It Cm \&? Ar command-name ... Print help information. .Pp .It Cm ascii Shorthand for "mode ascii" .Pp .It Cm binary Shorthand for "mode binary" .Pp .It Cm blocksize Ar [size] Sets the TFTP blksize option in TFTP Read Request or Write Request packets to .Ar [size] as specified in RFC 2348. Valid values are between 8 and 65464. If no blocksize is specified, then by default a blocksize of 512 bytes will be used. .Pp .It Cm blocksize2 Ar [size] Sets the TFTP blksize2 option in TFTP Read Request or Write Request packets to .Ar [size] . Values are restricted to powers of 2 between 8 and 32768. This is a -non-standard TFTP option. +non-standard TFTP option. .Pp .It Cm connect Ar host Op Ar port Set the .Ar host (and optionally .Ar port ) for transfers. Note that the .Tn TFTP protocol, unlike the .Tn FTP protocol, does not maintain connections between transfers; thus, the .Cm connect command does not actually create a connection, but merely remembers what host is to be used for transfers. You do not have to use the .Cm connect command; the remote host can be specified as part of the .Cm get or .Cm put commands. .Pp .It Cm debug Ar level -Enable or disable debugging levels during verbose output. The value of +Enable or disable debugging levels during verbose output. The value of .Ar level can be one of -.Cm packet , simple , options , +.Cm packet, simple, options, or -.Cm access . +.Cm access. .Pp .It Cm get Oo Ar host : Oc Ns Ar file Op Ar localname .It Cm get Xo .Oo Ar host1 : Oc Ns Ar file1 .Oo Ar host2 : Oc Ns Ar file2 ... .Oo Ar hostN : Oc Ns Ar fileN .Xc Get one or more files from the remote host. When using the .Ar host argument, the .Ar host will be used as default host for future transfers. If .Ar localname is specified, the file is stored locally as .Ar localname , otherwise the original filename is used. Note that it is not possible to download two files at a time, only one, three, or more than three files, at a time. .Pp To specify an IPv6 numeric address for a host, wrap it using square brackets like .Dq Li [3ffe:2900:e00c:ffee::1234] : Ns Ar file to disambiguate the colons used in the IPv6 address from the colon separating the host and the filename. .Pp .It Cm mode Ar transfer-mode Set the mode for transfers; .Ar transfer-mode may be one of .Em ascii or .Em binary . The default is .Em ascii . .Pp .It Cm packetdrop [arg] Randomly drop .Ar arg out of 100 packets during a transfer. This is a debugging feature. .Pp .It Cm put Ar file Op Oo Ar host : Oc Ns Ar remotename .It Cm put Ar file1 file2 ... fileN Op Oo Ar host : Oc Ns Ar remote-directory Put a file or set of files to the remote host. When .Ar remotename is specified, the file is stored remotely as .Ar remotename , otherwise the original filename is used. If the .Ar remote-directory argument is used, the remote host is assumed to be a .Ux machine. To specify an IPv6 numeric address for a .Ar host , see the example under the .Cm get command. .Pp .It Cm options Ar [arg] Enable or disable support for TFTP options. The valid values of .Ar arg are .Cm on (enable RFC 2347 options), .Cm off (disable RFC 2347 options), and .Cm extra -(toggle support for non-RFC defined options). +(toggle support for non-RFC defined options). .Pp .It Cm quit Exit .Nm . An end of file also exits. .Pp .It Cm rexmt Ar retransmission-timeout Set the per-packet retransmission timeout, in seconds. .Pp .It Cm rollover [arg] Specify the rollover option in TFTP Read Request or Write Request packets. After 65535 packets have been transmitted, set the block counter to .Ar arg . Valid values of .Ar arg are 0 and 1. This is a non-standard TFTP option. .Pp .It Cm status Show current status. .Pp .It Cm timeout Ar total-transmission-timeout Set the total transmission timeout, in seconds. .Pp .It Cm trace Toggle packet tracing. .Pp .It Cm verbose Toggle verbose mode. .El .Sh SEE ALSO .Xr tftpd 8 .Pp The following RFC's are supported: .Rs -RFC 1350 -.%T The TFTP Protocol (Revision 2) +.%T RFC 1350: The TFTP Protocol (Revision 2) .Re .Rs -RFC 2347 -.%T TFTP Option Extension +.%T RFC 2347: TFTP Option Extension .Re .Rs -RFC 2348 -.%T TFTP Blocksize Option +.%T RFC 2348: TFTP Blocksize Option .Re .Rs -RFC 2349 -.%T TFTP Timeout Interval and Transfer Size Options +.%T RFC 2349: TFTP Timeout Interval and Transfer Size Options .Re .Rs -RFC 3617 -.%T Uniform Resource Identifier (URI) Scheme and Applicability Statement for the Trivial File Transfer Protocol (TFTP) +.%T RFC 3617: Uniform Resource Identifier (URI) Scheme and Applicability Statement for the Trivial File Transfer Protocol (TFTP) .Re .Pp The non-standard .Cm rollover and .Cm blksize2 TFTP options are mentioned here: .Rs .%T Extending TFTP .%U http://www.compuphase.com/tftp.htm .Re .Sh HISTORY The .Nm command appeared in .Bx 4.3 . .Pp Edwin Groothuis performed a major rewrite of the .Xr tftpd 8 and .Nm code to support RFC2348. .Sh NOTES Because there is no user-login or validation within the .Tn TFTP protocol, the remote site will probably have some sort of file-access restrictions in place. The exact methods are specific to each site and therefore difficult to document here. .Pp Files larger than 33488896 octets (65535 blocks) cannot be transferred without client and server supporting the TFTP blocksize option (RFC2348), or the non-standard TFTP rollover option. Index: stable/9/usr.bin/tftp =================================================================== --- stable/9/usr.bin/tftp (revision 237215) +++ stable/9/usr.bin/tftp (revision 237216) Property changes on: stable/9/usr.bin/tftp ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/tftp:r233648 Index: stable/9/usr.bin/top/top.local.1 =================================================================== --- stable/9/usr.bin/top/top.local.1 (revision 237215) +++ stable/9/usr.bin/top/top.local.1 (revision 237216) @@ -1,52 +1,52 @@ -.\" $FreeBSD$ +.\" $FreeBSD$ .SH "FreeBSD NOTES" .SH DESCRIPTION OF MEMORY Mem: 9220K Active, 1M Inact, 3284K Wired, 1M Cache, 2M Buf, 1320K Free Swap: 91M Total, 79M Free, 13% Inuse, 80K In, 104K Out .TP .B K: Kilobyte .TP .B M: Megabyte .TP .B G: Gigabyte .TP .B %: 1/100 .TP .B Active: number of bytes active .TP .B Inact: number of bytes inactive .TP .B Wired: number of bytes wired down, including cached file data pages .TP .B Cache: number of clean bytes caching data that are available for immediate reallocation .TP .B Buf: number of bytes used for BIO-level disk caching .TP -.B Free: +.B Free: number of bytes free .TP -.B Total: +.B Total: total available swap usage -.TP -.B Free: +.TP +.B Free: total free swap usage -.TP -.B Inuse: +.TP +.B Inuse: swap usage -.TP -.B In: +.TP +.B In: bytes paged in from swap devices (last interval) .TP -.B Out: +.B Out: bytes paged out to swap devices (last interval) Index: stable/9/usr.bin/top =================================================================== --- stable/9/usr.bin/top (revision 237215) +++ stable/9/usr.bin/top (revision 237216) Property changes on: stable/9/usr.bin/top ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.bin/top:r233648 Index: stable/9/usr.bin/touch/touch.1 =================================================================== --- stable/9/usr.bin/touch/touch.1 (revision 237215) +++ stable/9/usr.bin/touch/touch.1 (revision 237216) @@ -1,217 +1,217 @@ .\" Copyright (c) 1991, 1993 .\" 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. .\" 4. 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. .\" .\" @(#)touch.1 8.3 (Berkeley) 4/28/95 .\" $FreeBSD$ .\" .Dd April 28, 1995 .Dt TOUCH 1 .Os .Sh NAME .Nm touch .Nd change file access and modification times .Sh SYNOPSIS .Nm .Op Fl A Ar [-][[hh]mm]SS .Op Fl acfhm .Op Fl r Ar file .Op Fl t Ar [[CC]YY]MMDDhhmm[.SS] .Ar .Sh DESCRIPTION The .Nm utility sets the modification and access times of files. If any file does not exist, it is created with default permissions. .Pp By default, -.Nm +.Nm changes both modification and access times. The .Fl a -and +and .Fl m flags may be used to select the access time or the modification time individually. Selecting both is equivalent to the default. By default, the timestamps are set to the current time. -The +The .Fl t flag explicitly specifies a different time, and the .Fl r flag specifies to set the times those of the specified file. -The +The .Fl A flag adjusts the values by a specified amount. .Pp The following options are available: .Bl -tag -width Ds -.It Fl A +.It Fl A Adjust the access and modification time stamps for the file by the specified value. This flag is intended for use in modifying files with incorrectly set time stamps. .Pp The argument is of the form .Dq [-][[hh]mm]SS where each pair of letters represents the following: .Pp .Bl -tag -width Ds -compact -offset indent .It Ar - Make the adjustment negative: the new time stamp is set to be before the old one. .It Ar hh The number of hours, from 00 to 99. .It Ar mm The number of minutes, from 00 to 59. .It Ar SS The number of seconds, from 00 to 59. .El .Pp The .Fl A -flag implies the +flag implies the .Fl c flag: if any file specified does not exist, it will be silently ignored. .It Fl a Change the access time of the file. The modification time of the file is not changed unless the .Fl m flag is also specified. .It Fl c Do not create the file if it does not exist. The .Nm utility does not treat this as an error. No error messages are displayed and the exit value is not affected. .It Fl f Attempt to force the update, even if the file permissions do not currently permit it. .It Fl h If the file is a symbolic link, change the times of the link itself rather than the file that the link points to. Note that .Fl h implies .Fl c and thus will not create any new files. .It Fl m Change the modification time of the file. The access time of the file is not changed unless the .Fl a flag is also specified. .It Fl r Use the access and modifications times from the specified file instead of the current time of day. .It Fl t Change the access and modification times to the specified time instead of the current time of day. The argument is of the form .Dq [[CC]YY]MMDDhhmm[.SS] where each pair of letters represents the following: .Pp .Bl -tag -width Ds -compact -offset indent .It Ar CC The first two digits of the year (the century). .It Ar YY The second two digits of the year. If .Dq YY is specified, but .Dq CC is not, a value for .Dq YY between 69 and 99 results in a .Dq CC value of 19. Otherwise, a .Dq CC value of 20 is used. .It Ar MM The month of the year, from 01 to 12. .It Ar DD the day of the month, from 01 to 31. .It Ar hh The hour of the day, from 00 to 23. .It Ar mm The minute of the hour, from 00 to 59. .It Ar SS The second of the minute, from 00 to 61. .El .Pp If the .Dq CC and .Dq YY letter pairs are not specified, the values default to the current year. If the .Dq SS letter pair is not specified, the value defaults to 0. .El .Sh EXIT STATUS .Ex -std .Sh COMPATIBILITY The obsolescent form of .Nm , where a time format is specified as the first argument, is supported. When no .Fl r or .Fl t option is specified, there are at least two arguments, and the first argument is a string of digits either eight or ten characters in length, the first argument is interpreted as a time specification of the form .Dq MMDDhhmm[YY] . .Pp The .Dq MM , .Dq DD , .Dq hh and .Dq mm letter pairs are treated as their counterparts specified to the .Fl t option. If the .Dq YY letter pair is in the range 39 to 99, the year is set to 1939 to 1999, otherwise, the year is set in the 21st century. .Sh SEE ALSO .Xr utimes 2 .Sh STANDARDS The .Nm utility is expected to be a superset of the .St -p1003.2 specification. .Sh HISTORY A .Nm utility appeared in .At v7 . Index: stable/9/usr.bin/touch =================================================================== --- stable/9/usr.bin/touch (revision 237215) +++ stable/9/usr.bin/touch (revision 237216) Property changes on: stable/9/usr.bin/touch ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /vendor/resolver/dist/usr.bin/touch:r1540-186085 Merged /projects/quota64/usr.bin/touch:r184125-207707 Merged /head/usr.bin/touch:r226702,227006,228761,228857,229067,229538,229997,230127,230555,231544,232322,232994,233121,233648,234206,234772,234782,235915,236338,236346,236365 Merged /projects/largeSMP/usr.bin/touch:r221273-222812,222815-223757 Index: stable/9/usr.sbin/adduser/adduser.conf.5 =================================================================== --- stable/9/usr.sbin/adduser/adduser.conf.5 (revision 237215) +++ stable/9/usr.sbin/adduser/adduser.conf.5 (revision 237216) @@ -1,221 +1,221 @@ .\" .\" Copyright (c) 2004 Tom Rhodes .\" 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. .\" .\" $FreeBSD$ .\" .Dd April 12, 2007 .Dt ADDUSER.CONF 5 .Os .Sh NAME .Nm adduser.conf .Nd .Xr adduser 8 configuration file .Sh DESCRIPTION -The +The .Pa /etc/adduser.conf file is automatically generated by the .Xr adduser 8 utility when invoked with the .Fl C command-line option. It is not meant to be edited by hand. .Pp The .Pa /etc/adduser.conf file is used to pre-set certain configuration options for the .Xr adduser 8 utility. When .Xr adduser 8 is invoked, it will check to see if this file exists, and if so, the configuration will be used or offered as the default settings. The .Nm file offers three types of configuration: .Bl -bullet .It Default settings offered by .Xr adduser 8 . These options are specified in the configuration file and offered as the default during every invocation of the .Xr adduser 8 utility. .It Configuration options which can be set in .Nm , but overridden by passing a flag to .Xr adduser 8 . .It Configuration supported by .Xr adduser 8 but not offered by a flag or during initial invocation. .El .Pp In the first case, these options can be set in .Nm but will still be offered when .Xr adduser 8 is invoked. In the second case, .Xr adduser 8 will read the configuration data unless a flag has been passed to override it. For example, the .Va defaultshell option. In the third case, the configuration will be utilized, but the user will never be prompted to modify the default setting by either a flag or an .Xr adduser 8 prompt. For example, the .Va upwexpire setting. .Pp The following configuration options can be set in .Nm : .Bl -tag -width ".Va defaultgroups" -offset indent .It Va defaultLgroup The default group new users will be added to. .It Va defaultclass The default class to place users in as described in .Xr login.conf 5 . .It Va defaultgroups This option is used to specify what other groups the new account should be added to. .It Va passwdtype May be one of .Cm no , none , random , or .Cm yes , as described in .Xr adduser 8 . As such, the text is not duplicated here and may be read in .Xr adduser 8 . .It Va homeprefix The default home directory prefix, usually .Pa /home . .It Va defaultshell The user's default shell which may be any of the shells listed in .Xr shells 5 . .It Va udotdir Defines the location of the default shell and environment configuration files. .It Va msgfile Location of the default new user message file. This message will be sent to all new users if specified here or at the .Xr adduser 8 prompt. .It Va disableflag The default message enclosed in brackets for the lock account prompt. .It Va upwexpire The default password expiration time. Format of the date is either a .Ux time in decimal, or a date in .Sm off .Ar dd No - Ar mmm No - Ar yy Op Ar yy .Sm on format, where .Ar dd is the day, .Ar mmm is the month in either numeric or alphabetic format, and .Ar yy Ns Op Ar yy is either a two or four digit year. This option also accepts a relative date in the form of .Sm off .Ar n Op Ar m h d w o y .Sm on where .Ar n is a decimal, octal (leading 0) or hexadecimal (leading 0x) digit followed by the number of Minutes, Hours, Days, Weeks, Months or Years from the current date at which the expiration time is to be set. .It Va uexpire The default account expire time. The format is similar to the .Va upwexpire option. .It Va ugecos The default information to be held in the GECOS field of .Pa /etc/master.passwd . .It Va uidstart The default user ID setting. This must be a number above 1000 and fewer than 65534. .El .Sh EXAMPLES The following is an example .Nm file created with the .Fl C .Xr adduser 8 flag and modified. .Bd -literal -offset indent # Configuration file for adduser(8). # NOTE: only *some* variables are saved. # Last Modified on Fri Mar 30 14:04:05 EST 2004. defaultLgroup= defaultclass= defaultgroups= passwdtype=yes homeprefix=/home defaultshell=/bin/csh udotdir=/usr/share/skel msgfile=/etc/adduser.msg disableflag= upwexpire=91d # Expire passwords 91 days after creation. .Ed .Sh SEE ALSO .Xr group 5 , .Xr passwd 5 , .Xr adduser 8 , .Xr pw 8 , .Xr rmuser 8 .Sh HISTORY The .Nm manual page first appeared in .Fx 5.3 . .Sh AUTHORS This manual page was written by .An Tom Rhodes Aq trhodes@FreeBSD.org . .Sh BUGS The internal variables documented here may change without notice. Do not rely on them. To modify this file invoke .Xr adduser 8 with the .Fl C option instead. Index: stable/9/usr.sbin/adduser =================================================================== --- stable/9/usr.sbin/adduser (revision 237215) +++ stable/9/usr.sbin/adduser (revision 237216) Property changes on: stable/9/usr.sbin/adduser ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/largeSMP/usr.sbin/adduser:r221273-222812,222815-223757 Merged /projects/head_mfi/usr.sbin/adduser:r233621 Merged /vendor/resolver/dist/usr.sbin/adduser:r1540-186085 Merged /projects/quota64/usr.sbin/adduser:r184125-207707 Merged /head/usr.sbin/adduser:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Index: stable/9/usr.sbin/bluetooth/ath3kfw/ath3kfw.8 =================================================================== --- stable/9/usr.sbin/bluetooth/ath3kfw/ath3kfw.8 (revision 237215) +++ stable/9/usr.sbin/bluetooth/ath3kfw/ath3kfw.8 (revision 237216) @@ -1,78 +1,78 @@ .\" Copyright (c) 2010 Maksim Yevmenkin .\" 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. .\" .\" $FreeBSD$ .\" .Dd Novermber 9, 2010 .Dt ATH3KFW 8 .Os .Sh NAME .Nm ath3kfw .Nd firmware download utility for Atheros AR3011 chip based Bluetooth USB devices .Sh SYNOPSIS .Nm .Fl d Ar device_name .Fl f Ar firmware_file_name .Nm .Fl h .Sh DESCRIPTION The .Nm utility downloads the specified firmware file to the specified .Xr ugen 4 device. .Pp This utility will .Em only work with Atheros AR3011 chip based Bluetooth USB devices. The identification is currently based on USB vendor ID/product ID pair. The vendor ID should be 0x0cf3 .Pq Dv USB_VENDOR_ATHEROS2 and the product ID should be 0x3000. .Pp Firmware files ath3k-1.fw and ath3k-2.fw can be obtained from the linux-firmware RPM. .Pp The options are as follows: .Bl -tag -width indent .It Fl d Ar device_name Specify -.Xr ugen 4 +.Xr ugen 4 device name. .It Fl f Ar firmware_file_name Specify firmware file name for download. .It Fl h Display usage message and exit. .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr libusb 3 , .Xr ugen 4 , .Xr devd 8 .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com .Sh BUGS Most likely. Please report if found. Index: stable/9/usr.sbin/bluetooth/ath3kfw =================================================================== --- stable/9/usr.sbin/bluetooth/ath3kfw (revision 237215) +++ stable/9/usr.sbin/bluetooth/ath3kfw (revision 237216) Property changes on: stable/9/usr.sbin/bluetooth/ath3kfw ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /head/usr.sbin/bluetooth/ath3kfw:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /vendor/resolver/dist/usr.sbin/bluetooth/ath3kfw:r1540-186085 Merged /projects/largeSMP/usr.sbin/bluetooth/ath3kfw:r221273-222812,222815-223757 Merged /projects/quota64/usr.sbin/bluetooth/ath3kfw:r184125-207707 Merged /projects/head_mfi/usr.sbin/bluetooth/ath3kfw:r233621 Index: stable/9/usr.sbin/bsdinstall/bsdinstall.8 =================================================================== --- stable/9/usr.sbin/bsdinstall/bsdinstall.8 (revision 237215) +++ stable/9/usr.sbin/bsdinstall/bsdinstall.8 (revision 237216) @@ -1,187 +1,187 @@ .\"- .\" Copyright (c) 2011 Nathan Whitehorn .\" 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 ``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 June 11, 2011 .Dt bsdinstall 8 .Os .Sh NAME .Nm bsdinstall .Nd system installer .Sh SYNOPSIS .Nm .Op Ar target .Op Ar ... .Sh DESCRIPTION .Nm is used for installation of new systems, both for system setup from installation media (e.g. CD-ROMs) and for use on live systems to prepare VM images and jails. .Pp Much like .Xr make 1 , Nm takes a target and possible parameters of the target as arguments. If invoked with no arguments, it will invoke the .Cm auto target, which provides a standard interactive installation, invoking the others in sequence. To perform a scripted installation, these subtargets can be invoked separately by an installation script. .Sh TARGETS Most of the following targets are only useful for scripting the installer. For interactive use, most users will be interested only in the .Cm auto and .Cm jail targets. .Bl -tag -width ".Cm jail Ar destination" .It Cm auto Run the standard interactive installation, including disk partitioning. .It Cm jail Ar destination Sets up a new chroot system at .Pa destination , suitable for use with .Xr jail 8 . Behavior is generally similar to .Cm auto , except that disk partitioning and network setup are skipped and a kernel is not installed into the new system. .It Cm keymap If the current controlling TTY is a .Xr syscons 4 console, asks the user to set the current keymap, and saves the result to the new system's .Pa rc.conf . .It Cm hostname Prompts the user for a host name for the new system and saves the result to the new system's .Pa rc.conf . If .Ev BSDINSTALL_CONFIGCURRENT is set, also sets the host name of the current system. .It Cm netconfig Interactively configures network interfaces (first invoking .Cm wlanconfig on wireless interfaces), saving the result to the new system's -.Pa rc.conf +.Pa rc.conf and .Pa resolv.conf . If .Ev BSDINSTALL_CONFIGCURRENT is set, also configures the network interfaces of the current system to match. .It Cm autopart Provides the installer's interactive guided disk partitioner for single-disk installations. Partitions disks, runs .Xr newfs 8 , and writes the new system's .Pa fstab . .It Cm partedit Provides the installer's interactive manual disk partitioner, with support for multi disk setups, non-UFS file systems, and manual selection of partition schemes. Partitions disks, runs .Xr newfs 8 , and writes the new system's .Pa fstab . .It Cm mount Mounts the file systems previously configured by .Cm autopart or .Cm partedit under .Ev BSDINSTALL_CHROOT . .It Cm distfetch Fetches the distributions in .Ev DISTRIBUTIONS to .Ev BSDINSTALL_DISTDIR from .Ev BSDINSTALL_DISTSITE . .It Cm checksum Verifies the checksums of the distributions listed in .Ev DISTRIBUTIONS against the distribution manifest. .It Cm distextract Extracts the distributions listed in .Ev DISTRIBUTIONS into .Ev BSDINSTALL_CHROOT . .It Cm rootpass Interactively invokes .Xr passwd 1 in the new system to set the root user's password. .It Cm adduser Interactively invokes .Xr adduser 8 in the new system. .It Cm time Interactively sets the time, date, and time zone of the new system. .It Cm services Queries the user for the system daemons to begin at system startup, writing the result into the new system's .Pa rc.conf . .It Cm config Installs the configuration files destined for the new system (e.g. rc.conf fragments generated by .Cm netconfig , etc.) onto the new system. .El .Sh ENVIRONMENT VARIABLES The following environment variables control various aspects of the installation process. Many are used internally during installation and have reasonable default values for most installation scenarios. Others are set by various interactive user prompts, and can be usefully overridden when making scripted or customized installers. .Bl -tag -width ".Ev BSDINSTALL_DISTDIR" .It Ev DISTRIBUTIONS The set of distributions to install (e.g. "base kernel ports"). Default: none .It Ev BSDINSTALL_DISTDIR The directory in which the distribution files can be found (or to which they should be downloaded). Default: .Pa /usr/freebsd-dist .It Ev BSDINSTALL_CHROOT The directory into which the distribution files should be unpacked and the directory at which the root file system of the new system should be mounted. Default: .Pa /mnt .It Ev BSDINSTALL_LOG Path to a log file for the installation. Default: .Pa /tmp/bsdinstall_log .It Ev BSDINSTALL_TMPETC Directory where files destined for the new system's .Pa /etc will be stored until the .Cm config target is executed. If this directory does not already exist, it will be created. Default: .Pa /tmp/bsdinstall_etc .El .Sh HISTORY This version of .Nm first appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit .An Nathan Whitehorn Aq nwhitehorn@FreeBSD.org Index: stable/9/usr.sbin/bsdinstall =================================================================== --- stable/9/usr.sbin/bsdinstall (revision 237215) +++ stable/9/usr.sbin/bsdinstall (revision 237216) Property changes on: stable/9/usr.sbin/bsdinstall ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/bsdinstall:r233648 Index: stable/9/usr.sbin/bsnmpd/modules/snmp_wlan/snmp_wlan.3 =================================================================== --- stable/9/usr.sbin/bsnmpd/modules/snmp_wlan/snmp_wlan.3 (revision 237215) +++ stable/9/usr.sbin/bsnmpd/modules/snmp_wlan/snmp_wlan.3 (revision 237216) @@ -1,160 +1,160 @@ .\"- .\" Copyright (C) 2010 The FreeBSD Foundation .\" All rights reserved. -.\" +.\" .\" This documentation was written by Shteryana Sotirova Shopova 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 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 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 June 28, 2010 .Dt SNMP_WLAN 3 .Os .Sh NAME .Nm snmp_wlan -.Nd "wireless networking module for +.Nd "wireless networking module for" .Xr bsnmpd 1 .Sh LIBRARY .Pq begemotSnmpdModulePath."wlan" = "/usr/lib/snmp_wlan.so" .Sh DESCRIPTION The .Nm snmp_wlan module implements a private BEGEMOT-WIRELESS-MIB, which allows management of virtual wireless interfaces. The MIB defines objects similar to the state data and configuration capabilities of .Xr ifconfig 8 for configuring virtual wireless interfaces. Therefore one should consider adding write communities or loading the .Nm module on systems where security is crucial. .Sh IMPLEMENTATION NOTES A short description of the Tables and interesting objects in the MIB follows. .Bl -tag -width "XXXXXXXXX" .It Va wlanInterfaceTable The table is used for creation and deletion of virtual wireless interfaces. To add a new interface, a SET should be executed on the .Va wlanIfaceName column with value the desired name of the interface. Next the parent interface must be set via .Va wlanParentIfName column. Any optional parameters may be set via the -.Va wlanIfaceOperatingMode , -.Va wlanIfaceFlags , +.Va wlanIfaceOperatingMode, +.Va wlanIfaceFlags, .Va wlanIfaceBssid -and +and .Va wlanIfaceLocalAddress columns. To finally create the interface in the system, a SET with value of active(1) to .Va wlanIfaceStatus column should be executed. To destroy a wireless interface a SET with value of destroy(6) to the relevant .Va wlanIfaceStatus column should be executed. .It Va wlanIfParentTable The table contains information about the hardware capabilities of the parent of a wireless interface. .It Va wlanIfaceConfigTable The table is used to get or set various configuration parameters for a virtual wireless interface. Depending on the operating mode of the interface and the hardware capabilities of the underlying hardware interface, not all parameters and values may be supported. .It Va wlanIfacePeerTable The table contains information about the associated stations for interfaces operating as access points, or the stations identified as neighbors in the IBSS for interfaces operating in adhoc mode. .It Va wlanIfaceChannelTable Information about the active channels for the wireless interfaces in the system. .It Va wlanIfRoamParamsTable The parameters that govern the roaming operation on the wireless interfaces. .It Va wlanIfTxParamsTable The parameters that govern the transmit operation on the wireless interfaces. .It Va wlanScanConfigTable The table that contains a configuration for channel scanning initiated via SNMP. .It Va wlanScanResultsTable The table contains the scan results from the last scan for each wireless interface on the system. .It Va wlanIfaceStatisticsTable Summary statistics for each wireless interface on the system. .It Va wlanWepInterfaceTable WEP configuration for the wireless interfaces on the system. .It Va wlanMACAccessControlTable Access Control configuration for wireless interfaces operating as access points. .It Va wlanMACAccessControlMACTable The table with Access Control MAC entries for which the configured Access Control Policy on wireless interfaces operating in Host AP mode is applied. .Va wlanMACAccessControlMACStatus column is used to add or delete MAC ACL entries. A set with value createAndGo(4) will add new entry, while with value destroy(6) will delete an existing one. .It Va wlanMeshRoutingConfig The subtree contains system configuration related to Wireless Mesh Routing. .It Va wlanMeshInterfaceTable The table contains information for wireless interfaces operating as wireless mesh points. .It Va wlanMeshNeighborTable The table contains information for the neighbors of wireless interfaces operating in mesh mode. .It Va wlanMeshRouteTable The mesh routing table for interfaces operating as mesh points, used for forwarding packets on a mesh network. .Va wlanMeshRouteStatus column is used to add or delete entries in the mesh routing table for an interface. A set with value createAndGo(4) will add new entry, while with value destroy(6) will delete an existing one. .It Va wlanMeshStatsTable Summary statistics for each virtual wireless interface operating as mesh point. .It Va wlanMeshHWMPConfig The subtree contains system configuration related to Hybrid Wireless Mesh Protocol. .It Va wlanHWMPInterfaceTable The table contains HWMP information for wireless interfaces operating in mesh mode. .It Va wlanMeshHWMPStatsTable Summary statistics for HWMP operation on interfaces operating as mesh points. .El .Sh RESTRICTIONS Not all information or configuration in the MIBs is currently available in FreeBSD. The values of the following variables carry no information: .Bl -tag -width "XXXXXXXXX" .It Va wlanStatsReset .El .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/snmp/defs/wlan_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/share/snmp/mibs/BEGEMOT-WIRELESS-MIB.txt The private BEGEMOT-WIRELESS-MIB that is implemented by this module. .El .Sh SEE ALSO .Xr bsnmpd 1 , .Xr gensnmptree 1 , .Xr wlan 4 , .Xr wlan_acl 4 , .Xr wlan_wep 4 , .Xr ifconfig 8 , .Xr snmpmod 3 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org Index: stable/9/usr.sbin/bsnmpd/modules/snmp_wlan =================================================================== --- stable/9/usr.sbin/bsnmpd/modules/snmp_wlan (revision 237215) +++ stable/9/usr.sbin/bsnmpd/modules/snmp_wlan (revision 237216) Property changes on: stable/9/usr.sbin/bsnmpd/modules/snmp_wlan ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/bsnmpd/modules/snmp_wlan:r233648 Index: stable/9/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 =================================================================== --- stable/9/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 (revision 237215) +++ stable/9/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 (revision 237216) @@ -1,418 +1,426 @@ .\" .\" Copyright (c) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written by Shteryana Sotirova Shopova .\" under sponsorship from the FreeBSD Foundation. .\" .\" Copyright (c) 2005-2007 The FreeBSD Project. .\" All rights reserved. .\" .\" Author: Shteryana Shopova .\" .\" 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 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 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 September 17, 2007 +.Dd January 10, 2012 .Dt BSNMPGET 1 .Os .Sh NAME .Nm bsnmpget , .Nm bsnmpwalk , .Nm bsnmpset .Nd "simple tools for querying SNMP agents" .Sh SYNOPSIS .Nm .Op Fl aDdehnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl M Ar max-repetitions .Op Fl N Ar non-repeaters .Op Fl o Ar output .Op Fl P Ar options .Op Fl p Ar pdu .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Op Ar OID ... .Pp .Nm bsnmpwalk .Op Fl dhnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl o Ar output .Op Fl P Ar options .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Op Ar OID ... .Pp .Nm bsnmpset .Op Fl adehnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl o Ar output .Op Fl P Ar options .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Ar OID Ns = Ar syntax Ns : Ns Ar value .Op Ar OID Ns = Ar syntax Ns : Ns Ar value ... .Sh DESCRIPTION .Nm , .Nm bsnmpwalk and .Nm bsnmpset are simple tools for retrieving management information from and setting -management information to a Simple Network Managment Protocol (SNMP) agent. +management information to a Simple Network Management Protocol (SNMP) agent. .Pp Depending on the options .Nm bsnmpget constructs either a SMNP GetRequest, GetNextRequest or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the objects whose values will be retrived, waits for a response and prints it if received successfully. .Pp .Nm Bsnmpwalk -queries an agent with SMNP GetNextRequest packets, +queries an agent with ether SMNP GetNextRequest or GetBulkRequest packets, asking for values of OID instances that are a part of the object subtree rooted at the provided OIDs. .Pp .Nm Bsnmpset constructs a SMNP SetRequest packet, fills in the OIDs (object identifiers), syntaxes and values of the objects whose values are to be set and waits for a -responce from server. +response from server. .Sh OPTIONS -.Pp The options are as follows (not all apply to all three programs): .Bl -tag -width ".It Fl D Ar options" .It Fl A Ar options Authentication options to use with SNMPv3 PDUs .Bl -tag -width \& .It Cm proto=[md5|sha] The protocol to use when calculating the PDU message digest. .It Cm key=authkey A binary localized authentication key to use when calculating the PDU message digest. .El .Pp By default SNMPv3 PDUs are sent unauthenticated. .It Fl a Skip any sanity checks when adding OIDs to a Protocol Data Unit (PDU): ingore syntax/access type, allow adding of non-leaf objects for GetPdu and read-only objects to a SetPDU. .It Fl b Ar buffersize Tune the size of buffers used to send and receive packets. The default size is 10000 bytes which should be enough unless an agent sends a really large octetstring. The maximum allowed length is 65535 according to the Structure of Management Information (SMIv2). .It Fl C Ar options The context to query with SNMPv3 PDUs. .Bl -tag -width \& .It Cm context=name The context name. Default is "" (empty). .It Cm context-engine=engine-id The SNMP Engine ID of the context to query with SNMPv3 PDUs, represented as binary octet string. By default, this is set to the Engine ID of the SNMP agent. .El .It Fl D Perform SNMP USM Engine Discovery, rather than sending a request for the value of a specific object. .It Fl d Turn on debugging. This option will cause the packets sent and received to be dumped to the terminal. .It Fl e Retry on error. If an error is returned in the response PDU, resend the request removing the variable that caused the error until a valid response is received. -This is only usefull for a GetRequest- and a GetNextRequest-PDU. +This is only useful for a GetRequest- and a GetNextRequest-PDU. .It Fl h Print a short help text with default values for various options. .It Fl I Ar options Load each MIB description file from the given list to translate symbolic object names to their numerical representation and vice versa. Use the other options to obtain a non-default behaviour: .Bl -tag -width \& .It Cm cut=OID Specifies the initial OID that was cut by .Xr gensnmpdef 1 when producing the MIB description file. The default value is .iso(1).org(3).dod(6) which is what should have been used for all the files installed under /usr/share/snmp/defs. Use this only if you generated your own files, providing a .Fl c option to .Xr gensnmpdef 1 . .It Cm path=filedir The directory where files in the list will be searched. The default is .Pa /usr/share/snmp/defs Ns . .It Cm file=filelist A comma separated list of files to which the two options above will apply. .El .Pp The file suboption has to come after the other suboptions so that their non-default values will be applied to the list of files. The order of the other suboptions before each file suboption can be random. Suboptions may be separated either by commas or by spaces. If using spaces make sure the entire option string is one argument, for example using quotes. .It Fl i Ar filelist List of MIB description files produced by .Xr gensnmpdef 1 which .Nm bsnmpget , .Nm bsnmpwalk or .Nm bsnmpset will search to translate numerical OIDs to their symbolic object names. Multiple files can be provided either giving this option multiple times or a comma separated list of file names. If a filename begins with a letter the default directory, /usr/share/snmp/defs, will be searched. .It Fl K Calculate and display the localized authentication and privacy keys corresponding to a plain text password. The password is obtain via the environment. Additionally, if one or more OIDs are specified, the calculated keys are used when processing the SNMPv3 requests. .It Fl l Ar filename The path of the posix local (unix domain) socket if local transport is used. .It Fl M Ar max-repetitions The value for the max-repetitions field in a GetBulk PDU. -Default is 1. +Default is 10. .It Fl N Ar non-repeaters The value for the non-repeaters field in a GetBulk PDU. Default is 0. .It Fl n Only use numerical representations for input and output OIDs and do not try to resolve symbolic object names. Note that .Nm bsnmpget , .Nm bsnmpwalk and .Nm bsnmpset will print numerical OIDs anyway if the corresponding string representation is not found in the MIB description files. .It Fl o Ar [quiet|short|verbose] The format used to print the received response. Quiet only prints values, short (default) prints an abbreviated OID representation and the value. In addition to the short output verbose prints the type before the value. .It Fl P Ar options Privacy options to use with SNMPv3 PDUs .Bl -tag -width \& .It Cm proto=[aes|des] The protocol to use when encypting/decrypting SNMPv3 PDU data. .It Cm key=privkey A binary localized privacy key to use when encypting/decrypting SNMPv3 PDU data. .El .Pp By default plain text SNMPv3 PDUs are sent. .It Fl p Ar [get|getnext|getbulk] The PDU type to send by -.Nm bsmpget . -Default is get. +.Nm bsmpget +and +.Nm bsnmpwalk . +Default is get +for +.Nm bsmpget +and getnext for +.Nm bsnmpwalk . +Getbulk allows executing the so called SNMP "bulkwalks" allowing the values of +multiple columns to be retrived in a single PDU by +.Nm bsnmpwalk . .It Fl r Ar retries Number of resends of request packets before giving up if the agent does not respond after the first try. Default is 3. .It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port] Each of the server specification components is optional but at least one has to be provided if .Ar s option is used. The server specification is constructed in the following manner: .Bl -tag -width \& .It Cm trans:: Transport type may be one of udp, stream or dgram. If this option is not provided an udp inet/inet6 socket will be used, which is the most common. Stream stands for a posix local stream socket and a posix local datagram socket will be used if dgram is specified. .It Cm community@ Specify an SNMP community string to be used when sending packets. If the option is skipped the default "public" will be used for .Nm and .Nm bsnmpwalk and the default "private" community string will be used for .Nm bsnmpset . .It Cm server This might be either the IP address or the hostname where the agent is listening. The default is .Qq localhost . .It Cm port The destination port to send the requests to. This is useful if the SNMP agent listens on a non-default port. Default is given by the .Qq snmp entry in .Pa /etc/services , port 161. .El .It Fl t Ar timeout Number of seconds before resending a request packet if the agent does not respond. The default value is 3 seconds. .It Fl U Ar options User credentials when sending SNMPv3 PDUs. .Bl -tag -width \& .It Cm engine=id The Engine ID of the SNMP agent represented as a binary octet string. .It Cm engine-boots=value The value of the snmpEngineBoots of the SNMP agent. .It Cm engine-time=value The value of the snmpEngineTime of the SNMP agent. .Pp If any of the above is not specified, SNMP USM Engine Discovery is attempted. This is also the default behavior. .It Cm name=username The USM user name to include in the SNMPv3 PDUs. By default, the user name is obtain via the environment .El .It Fl v Ar version The SNMP protocol version to use when sending requests. SNMP versions 1, 2 and 3 are supported. If no version option is provided .Nm bsnmpget , .Nm bsnmpwalk and .Nm bsnmpset will use version 2. Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the version to 1 is incompatiable with sending a GetBulk PDU. .It OID The object identifier whose value to retrive. At least one OID should be provided for .Nm bsnmpget to be able to send a request. .Pp For .Nm bsnmpwalk this is the root object identifier of the subtree whose values are to be retrived. If no OID is provided .Nm bsnmpwalk will walk the mib2 subtree rooted at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) . .Pp Any of the formats used to print a single variable is valid as input OID: .Bl -tag -width \& .It 1.3.6.1.2.1.25.1.1.0 .It sysDescr .It ifPhysAddress.1 .It ifRcvAddressStatus.2.6.255.255.255.255.255.255 .It ifRcvAddressType[2,ff:ff:ff:ff:ff:ff] .It ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff] (requires .Fl o Ar verbose option) .El .Pp Square brackets are used to denote an entry's indexes. When used in an input OID, the square brackets may have to be escaped or the OID has to be quoted to protect it from the shell. Note there is no difference between ifName.1 and "ifName[1]". .It OID Ns = Ns Ar [syntax Ns :] Ns Ar value The object identifier with its syntax type and value that is to be set. At least one such string OID=[syntax:]value should be provided to .Nm bsnmpset to be able to send a request. .Bl -tag -width \& .It Cm OID OID may be input as a string, a string followed by a random number of integers (suboids) separated by dots, a sequence of integers separated by dots - that is if .Ar n options is used - and in such case a syntax is required for every value, or a string followed by square brackets (used to denote an entry's indexes) and corresponding indexes. Any of formats used to print a single variable by .Nm bsnmpset is valid for inpit OID as well: .Bl -tag -width \& .It 1.3.6.1.2.1.25.1.1.0=TimeTicks:537615486 .It sysLocation=OctetString:"@ Home" (with Fl o Ar verbose No option) .It sysLocation.0="@ Home" .It 1.3.6.1.2.1.2.2.1.6.1=OctetString:ffffffffffff .It ifPhysAddress.1="00:02:b3:1d:1c:a3" .It ifRcvAddressStatus.1.6.255.255.255.255.255.255=1 .It "ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]=Integer:1" (with .Fl o Ar verbose option) .El .It Cm syntax where syntax string is one of: Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64. .It Cm value The value to be set - IP address in form of u.u.u.u - for example 1.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they contain any special characters or spaces, all other numeric types don't. .El .El .Sh ENVIRONMENT .Nm , .Nm bsnmpwalk and .Nm bsnmpset use the following environment variables: .Bl -tag -width SNMPAUTH .It Ev SNMPAUTH Specifies a default SNMP USM authentication protocol. .It Ev SNMPPRIV Specifies a default SNMP USM privacy protocol. .It Ev SNMPUSER Specifies a default SNMP USM user name. .It Ev SNMPPASSWD Specifies the SNMP USM plain text password to use when calculating localized authentication and privacy keys. If this variable exists in the environment, SMNPv3 is the default version to use for outgoing requests. .El .Sh SEE ALSO .Xr gensnmpdef 1 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org Index: stable/9/usr.sbin/bsnmpd/tools/bsnmptools =================================================================== --- stable/9/usr.sbin/bsnmpd/tools/bsnmptools (revision 237215) +++ stable/9/usr.sbin/bsnmpd/tools/bsnmptools (revision 237216) Property changes on: stable/9/usr.sbin/bsnmpd/tools/bsnmptools ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /vendor/resolver/dist/usr.sbin/bsnmpd/tools/bsnmptools:r1540-186085 Merged /projects/quota64/usr.sbin/bsnmpd/tools/bsnmptools:r184125-207707 Merged /head/usr.sbin/bsnmpd/tools/bsnmptools:r226702,226785,227006,228761,229067,229385,230127,233648,235286 Merged /projects/largeSMP/usr.sbin/bsnmpd/tools/bsnmptools:r221273-222812,222815-223757 Index: stable/9/usr.sbin/cdcontrol/cdcontrol.1 =================================================================== --- stable/9/usr.sbin/cdcontrol/cdcontrol.1 (revision 237215) +++ stable/9/usr.sbin/cdcontrol/cdcontrol.1 (revision 237216) @@ -1,222 +1,222 @@ .\" $FreeBSD$ .\" .Dd June 27, 2008 .Dt CDCONTROL 1 .Os .Sh NAME .Nm cdcontrol .Nd compact disc control utility .Sh SYNOPSIS .Nm .Op Fl sv .Op Fl f Ar device .Op Ar command ... .Sh DESCRIPTION The .Nm utility is a program to control audio features of a CD drive. The device is a name such as .Pa cd0 or .Pa acd0 . .Pp If no .Ar command is given, then .Nm enters an interactive mode, reading commands from the standard input. .Pp The following options are available: .Bl -tag -width indent .It Fl s Silent mode. Do not print table headers and human readable comments. .It Fl v Verbose mode. Print as much information as possible. .It Fl f Ar device Specify a device, such as .Pa /dev/cd0 or .Pa acd0 . Both absolute path and relative to .Pa /dev filename are possible. The .Fl f option overrides .Ev CDROM . If neither .Ev CDROM nor the .Fl f option is specified, .Nm tries opening first .Pa /dev/cdrom , then .Pa /dev/cd0 , and finally .Pa /dev/acd0 . .El .Pp The available commands are listed below. Only as many characters as are required to uniquely identify a command need be specified. The word .Ic play can be omitted or the characters .Ic + and .Ic - can be used in the place of .Ic next and .Ic prev . .Bl -tag -width indent .It Ic play Ar first_track Op Ar last_track Play from track .Ar first_track to track .Ar last_track . The first track has number 1. Can be omitted in all cases. .It Xo .Ic play .Ar start_m : Ns Ar start_s . Ns Ar start_f .Op Ar end_m : Ns Ar end_s . Ns Ar end_f .Xc Play from the absolute address (MSF) defined by .Ar start_m in minutes, .Ar start_s , in seconds and .Ar start_f (frame number) to the absolute address defined by .Ar end_m in minutes, .Ar end_s , in seconds and .Ar end_f (frame number). Minutes are in the range 0-99. Seconds are in the range 0-59. Frame numbers are in the range 0-74. .It Ic play Op # Ns Ar start_block Op Ar length Play starting from the logical block .Ar start_block using .Ar length logical blocks. .It Ic next Op Ar tracks Skip forward a number of tracks (default 1). .It Ic prev Op Ar tracks Skip backward a number of tracks (default 1). .It Ic pause Stop playing. Do not stop the disc. .It Ic resume Resume playing. Used after the .Ic pause command. .It Ic stop Stop the disc. .It Ic eject Eject the disc. .It Ic close Inject the disc. .It Ic volume -Same as +Same as .Em status volume command. .It Ic volume Ar level Set the volume of both channels to .Ar level . Allowed values are in the range 0-255. .It Ic volume Ar left_channel right_channel Set the volume of left channel to .Ar left_channel and the volume of right channel to .Ar right_channel . Allowed values are in the range 0-255. .It Ic volume Cm mute Turn the sound off. .It Ic volume Cm mono Set the mono mode. .It Ic volume Cm stereo Set the stereo mode. .It Ic volume Cm left Play the left subtrack on both left and right channels. .It Ic volume Cm right Play the right subtrack on both left and right channels. .It Ic info Print the table of contents. .It Ic status Op Cm audio | media | volume Print the information about the disc: .Pp .Bl -tag -width ".Cm volume" -compact .It Cm audio the current playing status and position .It Cm media the current media catalog status .It Cm volume the current values of the volume for left and right channels. .El .It Ic cdid Display the serial number of the CD using the method used by the .Tn CDDB project .Pq Pa http://www.cddb.org/ . .It Ic help Print the list of available commands. .It Ic debug Cm on Enable the debugging mode of the CD device driver. .It Ic debug Cm off Disable the driver debugging mode. .It Ic reset Perform the hardware reset of the device. .It Ic set Cm msf Set minute-second-frame ioctl mode (default). .It Ic set Cm lba Set LBA ioctl mode. .It Ic speed Ar s Set the highest speed that the drive should use for reading data. The units are multiples of a single speed CDROM (150 KB/s). Specify .Dq Li max to use the drive's fastest speed. .It Ic quit Quit the program. .El .Sh ENVIRONMENT The following environment variables affect the execution of .Nm : .Bl -tag -width ".Ev CD_DRIVE" .It Ev CDROM The CD device to use, if one is not specified with the .Fl f option. .It Ev CDPLAY , CD_DRIVE , DISC , MUSIC_CD These variables have been deprecated in favour of .Ev CDROM . .El .Sh FILES .Bl -tag -width ".Pa /dev/mcd0" -compact .It Pa /dev/cd0 .It Pa /dev/mcd0 .It Pa /dev/acd0 .El .Sh HISTORY The .Nm command appeared in .Fx 2.1 . .Sh AUTHORS .An Jean-Marc Zucconi .An Andrey A. Chernov .An Serge V. Vakulenko Index: stable/9/usr.sbin/cdcontrol =================================================================== --- stable/9/usr.sbin/cdcontrol (revision 237215) +++ stable/9/usr.sbin/cdcontrol (revision 237216) Property changes on: stable/9/usr.sbin/cdcontrol ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /head/usr.sbin/cdcontrol:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /projects/head_mfi/usr.sbin/cdcontrol:r233621 Merged /vendor/resolver/dist/usr.sbin/cdcontrol:r1540-186085 Merged /projects/quota64/usr.sbin/cdcontrol:r184125-207707 Merged /projects/largeSMP/usr.sbin/cdcontrol:r221273-222812,222815-223757 Index: stable/9/usr.sbin/config/config.8 =================================================================== --- stable/9/usr.sbin/config/config.8 (revision 237215) +++ stable/9/usr.sbin/config/config.8 (revision 237216) @@ -1,263 +1,263 @@ .\" 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. .\" 4. 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. .\" .\" @(#)config.8 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd May 8, 2007 .Dt CONFIG 8 .Os .Sh NAME .Nm config .Nd build system configuration files .Sh SYNOPSIS .Nm .Op Fl CVgp .Op Fl d Ar destdir .Ar SYSTEM_NAME .Nm .Op Fl x Ar kernel .Sh DESCRIPTION The .Nm utility builds a set of system configuration files from the file .Ar SYSTEM_NAME which describes the system to configure. A second file tells .Nm what files are needed to generate a system and can be augmented by configuration specific set of files that give alternate files for a specific machine (see the .Sx FILES section below). .Pp Available options and operands: .Bl -tag -width ".Ar SYSTEM_NAME" .It Fl V Print the .Nm version number. .It Fl C If the INCLUDE_CONFIG_FILE is present in a configuration file, kernel image will contain full configuration files included literally (preserving comments). This flag is kept for backward compatibility. .It Fl d Ar destdir Use .Ar destdir as the output directory, instead of the default one. Note that .Nm does not append .Ar SYSTEM_NAME to the directory given. .It Fl m Print the MACHINE and MACHINE_ARCH values for this kernel and exit. .It Fl g Configure a system for debugging. .It Fl x Ar kernel Print kernel configuration file embedded into a kernel file. -This option makes sense only if +This option makes sense only if .Cd "options INCLUDE_CONFIG_FILE" entry was present in your configuration file. .It Fl p Configure a system for profiling; for example, .Xr kgmon 8 and .Xr gprof 1 . If two or more .Fl p options are supplied, .Nm configures a system for high resolution profiling. .It Ar SYSTEM_NAME Specify the name of the system configuration file containing device specifications, configuration options and other system parameters for one system configuration. .El .Pp The .Nm utility should be run from the .Pa conf subdirectory of the system source (usually .Pa /sys/ Ns Va ARCH Ns Pa /conf ) , where .Va ARCH represents one of the architectures supported by .Fx . The .Nm utility creates the directory .Pa ../compile/ Ns Ar SYSTEM_NAME or the one given with the .Fl d option as necessary and places all output files there. The output of .Nm consists of a number of files; for the .Tn i386 , they are: .Pa Makefile , used by .Xr make 1 in building the system; header files, definitions of the number of various devices that will be compiled into the system. .Pp After running .Nm , it is necessary to run .Dq Li make depend in the directory where the new makefile was created. The .Nm utility prints a reminder of this when it completes. .Pp If any other error messages are produced by .Nm , the problems in the configuration file should be corrected and .Nm should be run again. Attempts to compile a system that had configuration errors are likely to fail. .Sh DEBUG KERNELS Traditional .Bx kernels are compiled without symbols due to the heavy load on the system when compiling a .Dq debug kernel. A debug kernel contains complete symbols for all the source files, and enables an experienced kernel programmer to analyse the cause of a problem. The debuggers available prior to .Bx 4.4 Lite were able to find some information from a normal kernel; .Xr gdb 1 provides very little support for normal kernels, and a debug kernel is needed for any meaningful analysis. .Pp For reasons of history, time and space, building a debug kernel is not the default with .Fx : a debug kernel takes up to 30% longer to build and requires about 30 MB of disk storage in the build directory, compared to about 6 MB for a non-debug kernel. A debug kernel is about 11 MB in size, compared to about 2 MB for a non-debug kernel. This space is used both in the root file system and at run time in memory. Use the .Fl g option to build a debug kernel. With this option, .Nm causes two kernel files to be built in the kernel build directory: .Bl -bullet .It .Pa kernel.debug is the complete debug kernel. .It .Pa kernel is a copy of the kernel with the debug symbols stripped off. This is equivalent to the normal non-debug kernel. .El .Pp There is currently little sense in installing and booting from a debug kernel, since the only tools available which use the symbols do not run on-line. There are therefore two options for installing a debug kernel: .Bl -bullet .It .Dq Li "make install" installs .Pa kernel in the root file system. .It .Dq Li "make install.debug" installs .Pa kernel.debug in the root file system. .El .Sh FILES .Bl -tag -width ".Pa /sys/ Ns Va ARCH Ns Pa /compile/ Ns Ar SYSTEM_NAME" -compact .It Pa /sys/conf/files list of common files system is built from .It Pa /sys/conf/Makefile. Ns Va ARCH generic makefile for the .Va ARCH .It Pa /sys/conf/files. Ns Va ARCH list of .Va ARCH specific files .It Pa /sys/ Ns Va ARCH Ns Pa /compile/ Ns Ar SYSTEM_NAME default kernel build directory for system .Ar SYSTEM_NAME on .Va ARCH . .El .Sh SEE ALSO .Xr config 5 .Pp The .Sx SYNOPSIS portion of each device in section 4. .Rs .%T "Building 4.3 BSD UNIX System with Config" .Re .Sh HISTORY The .Nm utility appeared in .Bx 4.1 . .Pp -Before support for +Before support for .Fl x was introduced, .Cd "options INCLUDE_CONFIG_FILE" included entire configuration file that used to be embedded in the new kernel. This meant that .Xr strings 1 could be used to extract it from a kernel: -to extract the configuration information, you had to use +to extract the configuration information, you had to use the command: .Pp .Dl "strings -n 3 kernel | sed -n 's/^___//p'" .Sh BUGS The line numbers reported in error messages are usually off by one. Index: stable/9/usr.sbin/config =================================================================== --- stable/9/usr.sbin/config (revision 237215) +++ stable/9/usr.sbin/config (revision 237216) Property changes on: stable/9/usr.sbin/config ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/largeSMP/usr.sbin/config:r221273-222812,222815-223757 Merged /head/usr.sbin/config:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /projects/head_mfi/usr.sbin/config:r233621 Merged /vendor/resolver/dist/usr.sbin/config:r1540-186085 Merged /projects/quota64/usr.sbin/config:r184125-207707 Index: stable/9/usr.sbin/ctladm/ctladm.8 =================================================================== --- stable/9/usr.sbin/ctladm/ctladm.8 (revision 237215) +++ stable/9/usr.sbin/ctladm/ctladm.8 (revision 237216) @@ -1,963 +1,963 @@ -.\" +.\" .\" Copyright (c) 2003 Silicon Graphics International Corp. .\" 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, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. -.\" +.\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. -.\" +.\" .\" ctladm utility man page. .\" .\" Author: Ken Merry .\" .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $ .\" $FreeBSD$ .\" .Dd July 8, 2011 .Dt CTLADM 8 .Os .Sh NAME .Nm ctladm .Nd CAM Target Layer control utility .Sh SYNOPSIS .Nm .Aq Ar command .Op target:lun .Op generic args .Op command args .Nm .Ic tur .Aq target:lun .Op general options .Nm .Ic inquiry .Aq target:lun .Op general options .Nm .Ic reqsense .Aq target:lun .Op general options .Nm .Ic reportluns .Aq target:lun .Op general options .Nm .Ic read .Aq target:lun .Op general options .Aq Fl l Ar lba .Aq Fl d Ar datalen .Aq Fl f Ar file|- .Aq Fl b Ar blocksize_bytes .Op Fl c Ar cdbsize .Op Fl N .Nm .Ic write .Aq target:lun .Op general options .Aq Fl l Ar lba .Aq Fl d Ar datalen .Aq Fl f Ar file|- .Aq Fl b Ar blocksize_bytes .Op Fl c Ar cdbsize .Op Fl N .Nm .Ic bbrread .Aq target:lun .Op general options .Aq Fl -l Ar lba .Aq Fl -d Ar datalen .Nm .Ic readcap .Aq target:lun .Op general options .Op Fl c Ar cdbsize .Nm .Ic modesense .Aq target:lun .Aq Fl m Ar page | Fl l .Op Fl P Ar pc .Op Fl d .Op Fl S Ar subpage .Op Fl c Ar size .Nm .Ic start .Aq target:lun .Op general options .Op Fl i .Op Fl o .Nm .Ic stop .Aq target:lun .Op general options .Op Fl i .Op Fl o .Nm .Ic synccache .Aq target:lun .Op general options .Op Fl l Ar lba .Op Fl b Ar blockcount .Op Fl r .Op Fl i .Op Fl c Ar cdbsize .Nm .Ic shutdown .Op general options .Nm .Ic startup .Op general options .Nm .Ic hardstop .Nm .Ic hardstart .Nm .Ic lunlist .Nm .Ic delay .Aq target:lun .Aq Fl l Ar datamove|done .Aq Fl t Ar secs .Op Fl T Ar oneshot|cont .Nm .Ic realsync Aq on|off|query .Nm .Ic setsync interval .Aq target:lun .Aq Fl i Ar interval .Nm .Ic getsync .Aq target:lun .Nm .Ic inject .Aq Fl i Ar action .Aq Fl p Ar pattern .Op Fl r Ar lba,len .Op Fl s Ar len fmt Op Ar args .Op Fl c .Op Fl d Ar delete_id .Nm .Ic create .Aq Fl b Ar backend .Op Fl B Ar blocksize .Op Fl d Ar device_id .Op Fl l Ar lun_id .Op Fl o Ar name=value .Op Fl s Ar size_bytes .Op Fl S Ar serial_num .Op Fl t Ar device_type .Nm .Ic remove .Aq Fl b Ar backend .Aq Fl l Ar lun_id .Op Fl o Ar name=value .Nm .Ic devlist .Op Fl b Ar backend .Op Fl v .Op Fl x .Nm .Ic port .Op Fl l .Op Fl o Ar on|off .Op Fl w Ar wwpn .Op Fl W Ar wwnn .Op Fl p Ar targ_port .Op Fl t Ar fe_type .Op Fl q .Op Fl x .Nm .Ic dumpooa .Nm .Ic dumpstructs .Nm .Ic help .Sh DESCRIPTION The .Nm utility is designed to provide a way to access and control the CAM Target Layer (CTL). It provides a way to send .Tn SCSI commands to the CTL layer, and also provides some meta-commands that utilize .Tn SCSI commands. (For instance, the .Ic lunlist command is implemented using the .Tn SCSI REPORT LUNS and INQUIRY commands.) .Pp The .Nm utility has a number of primary functions, many of which require a device identifier. The device identifier takes the following form: .Bl -tag -width 14n .It target:lun Specify the target (almost always 0) and LUN number to operate on. .El Many of the primary functions of the .Nm utility take the following optional arguments: .Pp .Bl -tag -width 10n .It Fl C Ar retries Specify the number of times to retry a command in the event of failure. .It Fl D Ar device Specify the device to open. This allows opening a device other than the default device, .Pa /dev/cam/ctl , to be opened for sending commands. .It Fl I Ar id Specify the initiator number to use. By default, .Nm will use 7 as the initiator number. .El .Pp Primary commands: .Bl -tag -width 11n .It Ic tur Send the .Tn SCSI TEST UNIT READY command to the device and report whether or not it is ready. .It Ic inquiry Send the .Tn SCSI INQUIRY command to the device and display some of the returned inquiry data. .It Ic reqsense Send the .Tn SCSI REQUEST SENSE command to the device and display the returned sense information. .It Ic reportluns Send the .Tn SCSI REPORT LUNS command to the device and display supported LUNs. .It Ic read Send a .Tn SCSI READ command to the device, and write the requested data to a file or stdout. .Bl -tag -width 12n .It Fl l Ar lba Specify the starting Logical Block Address for the READ. This can be specified in decimal, octal (starting with 0), hexadecimal (starting with 0x) or any other base supported by .Xr strtoull 3 . .It Fl d Ar datalen Specify the length, in 512 byte blocks, of the READ request. .It Fl f Ar file Specify the destination for the data read by the READ command. Either a filename or .Sq - for stdout may be specified. .It Fl c Ar cdbsize Specify the minimum .Tn SCSI CDB (Command Data Block) size to be used for the READ request. Allowable values are 6, 10, 12 and 16. Depending upon the LBA and amount of data requested, a larger CDB size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) .It Fl b Ar blocksize Specify the blocksize of the underlying .Tn SCSI device, so the transfer length can be calculated accurately. The blocksize can be obtained via the .Tn SCSI READ CAPACITY command. -.It Fl N +.It Fl N Do not copy data to .Nm from the kernel when doing a read, just execute the command without copying data. This is to be used for performance testing. .El .It Ic write Read data from a file or stdin, and write the data to the device using the .Tn SCSI WRITE command. .Bl -tag -width 12n .It Fl l Ar lba Specify the starting Logical Block Address for the WRITE. This can be specified in decimal, octal (starting with 0), hexadecimal (starting with 0x) or any other base supported by .Xr strtoull 3 . .It Fl d Ar atalen Specify the length, in 512 byte blocks, of the WRITE request. .It Fl f Ar file Specify the source for the data to be written by the WRITE command. Either a filename or .Sq - for stdin may be specified. .It Fl c Ar cdbsize Specify the minimum .Tn SCSI CDB (Command Data Block) size to be used for the READ request. Allowable values are 6, 10, 12 and 16. Depending upon the LBA and amount of data requested, a larger CDB size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) .It Fl b Ar blocksize Specify the blocksize of the underlying .Tn SCSI device, so the transfer length can be calculated accurately. The blocksize can be obtained via the .Tn SCSI READ CAPACITY command. .It Fl N Do not copy data to .Nm to the kernel when doing a write, just execute the command without copying data. This is to be used for performance testing. .El .It Ic bbrread Issue a SCSI READ command to the logical device to potentially force a bad block on a disk in the RAID set to be reconstructed from the other disks in the array. This command should only be used on an array that is in the normal state. If used on a critical array, it could cause the array to go offline if the bad block to be remapped is on one of the disks that is still active in the array. .Pp The data for this particular command will be discarded, and not returned to the user. .Pp In order to determine which LUN to read from, the user should first determine which LUN the disk with a bad block belongs to. Then he should map the bad disk block back to the logical block address for the array in order to determine which LBA to pass in to the .Ic bbrread command. .Pp This command is primarily intended for testing. In practice, bad block remapping will generally be triggered by the in-kernel Disk Aerobics and Disk Scrubbing code. .Bl -tag -width 10n .It Fl l Ar lba Specify the starting Logical Block Address. .It Fl d Ar datalen Specify the amount of data in bytes to read from the LUN. This must be a multiple of the LUN blocksize. .El .It Ic readcap Send the .Tn SCSI READ CAPACITY command to the device and display the device size and device block size. By default, READ CAPACITY(10) is used. If the device returns a maximum LBA of 0xffffffff, however, .Nm will automatically issue a READ CAPACITY(16), which is implemented as a service action of the SERVICE ACTION IN(16) opcode. The user can specify the minimum CDB size with the .Fl c argument. Valid values for the .Fl c option are 10 and 16. If a 10 byte CDB is specified, the request will be automatically reissued with a 16 byte CDB if the maximum LBA returned is 0xffffffff. .It Ic modesense Send a .Tn SCSI MODE SENSE command to the device, and display the requested mode page(s) or page list. .Bl -tag -width 10n .It Fl m Ar page Specify the mode page to display. This option and the .Fl l option are mutually exclusive. One of the two must be specified, though. Mode page numbers may be specified in decimal or hexadecimal. .It Fl l Request that the list of mode pages supported by the device be returned. This option and the .Fl m option are mutually exclusive. One of the two must be specified, though. .It Fl P Ar pc Specify the mode page page control value. Possible values are: .Bl -tag -width 2n -compact .It 0 Current values. .It 1 Changeable value bitmask. .It 2 Default values. .It 3 Saved values. .El .It Fl d Disable block descriptors when sending the mode sense request. .It Fl S Ar subpage Specify the subpage used with the mode sense request. .It Fl c Ar cdbsize Specify the CDB size used for the mode sense request. Supported values are 6 and 10. .El .It Ic start Send the .Tn SCSI START STOP UNIT command to the specified LUN with the start bit set. .Bl -tag -width 4n .It Fl i Set the immediate bit in the CDB. Note that CTL does not support the immediate bit, so this is primarily useful for making sure that CTL returns the proper error. .It Fl o Set the Copan proprietary on/offline bit in the CDB. When this flag is used, the LUN will be marked online again (see the description of the .Ic shutdown and .Ic startup commands). When this flag is used with a start command, the LUN will NOT be spun up. You need to use a start command without the .Fl o flag to spin up the disks in the LUN. .El .It Ic stop Send the .Tn SCSI START STOP UNIT command to the specified LUN with the start bit cleared. We use an ordered tag to stop the LUN, so we can guarantee that all pending I/O executes before it is stopped. (CTL guarantees this anyway, but .Nm sends an ordered tag for completeness.) .Bl -tag -width 4n .It Fl i Set the immediate bit in the CDB. Note that CTL does not support the immediate bit, so this is primarily useful for making sure that CTL returns the proper error. .It Fl o Set the Copan proprietary on/offline bit in the CDB. When this flag is used, the LUN will be spun down and taken offline ("Logical unit not ready, -manual intervention required"). See the description of the +manual intervention required"). See the description of the .Ic shutdown and .Ic startup options. .El .It Ic synccache Send the -.Tn SCSI +.Tn SCSI SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE CACHE(10) is used. If the specified starting LBA is greater than 0xffffffff or the length is greater than 0xffff, though, SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used if the user specifies a 16 byte CDB with the .Fl c argument. .Bl -tag -width 14n .It Fl l Ar lba Specify the starting LBA of the cache region to synchronize. This option is a no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN. .It Fl b Ar blockcount Specify the length of the cache region to synchronize. This option is a no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN. .It Fl r Specify relative addressing for the starting LBA. CTL does not support relative addressing, since it only works for linked commands, and CTL doesn't support linked commands. .It Fl i Tell the target to return status immediately after issuing the SYHCHRONIZE CACHE command rather than waiting for the cache to finish syncing. CTL does not support this bit. .It Fl c Ar cdbsize Specify the minimum CDB size. Valid values are 10 and 16 bytes. .El .It Ic shutdown Issue a .Tn SCSI START STOP UNIT command with the start bit cleared and the on/offline bit set to all direct access LUNs. This will spin down all direct access LUNs, and mark them offline ("Logical unit not ready, manual intervention required"). Once marked offline, the state can only be cleared by sending a START STOP UNIT command with the start bit set and the on/offline bit set. The .Nm commands .Ic startup and .Ic start will accomplish this. Note that the on/offline bit is a non-standard Copan extension to the .Tn SCSI START STOP UNIT command, so merely sending a normal start command from an initiator will not clear the condition. (This is by design.) .It Ic startup Issue a .Tn SCSI START STOP UNIT command with the start bit set and the on/offline bit set to all direct access LUNs. This will mark all direct access LUNs "online" again. It will not cause any LUNs to start up. A separate start command without the on/offline bit set is necessary for that. .It Ic hardstop Use the kernel facility for stopping all direct access LUNs and setting the offline bit. Unlike the .Ic shutdown command above, this command allows shutting down LUNs with I/O active. It will also issue a LUN reset to any reserved LUNs to break the reservation so that the LUN can be stopped. .Ic shutdown command instead. .It Ic hardstart This command is functionally identical to the .Ic startup command described above. The primary difference is that the LUNs are enumerated and commands sent by the in-kernel Front End Target Driver instead of by .Nm . .It Ic lunlist List all LUNs registered with CTL. Because this command uses the ioctl port, it will only work when the FETDs (Front End Target Drivers) are enabled. This command is the equivalent of doing a REPORT LUNS on one LUN and then and then an INQUIRY on each LUN in the system. .It Ic delay Delay commands at the given location. There are two places where commands may be delayed currently: before data is transferred .Pq Dq datamove and just prior to sending status to the host .Pq Dq done . One of the two must be supplied as an argument to the -.Fl l +.Fl l option. The .Fl t option must also be specified. .Bl -tag -width 12n .It Fl l Ar delayloc Delay command(s) at the specified location. This can either be at the data movement stage (datamove) or prior to command completion (done). .It Fl t Ar delaytime Delay command(s) for the specified number of seconds. This must be specified. If set to 0, it will clear out any previously set delay for this particular location (datamove or done). .It Fl T Ar delaytype Specify the delay type. By default, the .Ic delay option will delay the next command sent to the given LUN. With the .Fl T Ar cont option, every command will be delayed by the specified period of time. With the .Fl T Ar oneshot the next command sent to the given LUN will be delayed and all subsequent commands will be completed normally. This is the default. .El .It Ic realsync Query and control CTL's SYNCHRONIZE CACHE behavior. The .Sq query argument will show whether SYNCHRONIZE CACHE commands are being sent to the backend or not. The default is to send SYNCHRONIZE CACHE commands to the backend. -The +The .Sq on argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be sent to the backend. The .Sq off argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be immediately returned to the initiator with successful status. .It Ic setsync For a given lun, only actually service every Nth SYNCHRONIZE CACHE command that is sent. This can be used for debugging the optimal time period for sending SYNCHRONIZE cache commands. An interval of 0 means that the cache will be flushed for this LUN every time a SYNCHRONIZE CACHE command is received. .Pp You must specify the target and LUN you want to modify. .It Ic getsync Get the interval at which we actually service the SYNCHRONIZE CACHE command, as set by the .Ic setsync command above. The reported number means that we will actually flush the cache on every Nth SYNCHRONIZE CACHE command. A value of 0 means that we will flush the cache every time. .Pp You must specify the target and LUN you want to query. .It Ic inject Inject the specified type of error for the LUN specified, when a command that matches the given pattern is seen. The sense data returned is in either fixed or descriptor format, depending upon the status of the D_SENSE bit in the control mode page (page 0xa) for the LUN. .Pp Errors are only injected for commands that have not already failed for other reasons. By default, only the first command matching the pattern specified is returned with the supplied error. .Pp If the .Fl c flag is specified, all commands matching the pattern will be returned with the specified error until the error injection command is deleted with -.Fl d +.Fl d flag. .Bl -tag -width 17n .It Fl i Ar action Specify the error to return: .Bl -tag -width 10n .It aborted Return the next matching command on the specified LUN with the sense key ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect failure"). .It mediumerr Return the next matching command on the specified LUN with the sense key MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed") for write errors. .It ua Return the next matching command on the specified LUN with the sense key UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS DEVICE RESET OCCURRED"). .It custom Return the next matching command on the specified LUN with the supplied sense data. The .Fl s argument must be specified. .El .It Fl p Ar pattern Specify which commands should be returned with the given error. .Bl -tag -width 10n .It read The error should apply to READ(6), READ(10), READ(12), READ(16), etc. .It write The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE AND VERIFY(10), etc. .It rw The error should apply to both read and write type commands. .It readcap The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands. .It tur The error should apply to TEST UNIT READY commands. .It any The error should apply to any command. .El .It Fl r Ar lba,len Specify the starting lba and length of the range of LBAs which should trigger an error. This option is only applies when read and/or write patterns are specified. If used with other command types, the error will never be triggered. .It Fl s Ar len fmt Op Ar args Specify the sense data that is to be returned for custom actions. If the format is .Sq - , len bytes of sense data will be read from standard input and written to the sense buffer. If len is longer than 252 bytes (the maximum allowable .Tn SCSI sense data length), it will be truncated to that length. The sense data format is described in .Xr cam_cdparse 3 . .It Fl c The error injection should be persistent, instead of happening once. Persistent errors must be deleted with the .Fl d argument. .It Fl d Ar delete_id Delete the specified error injection serial number. The serial number is returned when the error is injected. .El .It Ic port Perform one of several CTL frontend port operations. Either get a list of frontend ports .Pq Fl l , turn one or more frontends on or off .Pq Fl o Ar on|off , or set the World Wide Node Name .Pq Fl w Ar wwnn or World Wide Port Name .Pq Fl W Ar wwpn for a given port. One of .Fl l , .Fl o , -or +or .Fl w or .Fl W must be specified. The WWNN and WWPN may both be specified at the same time, but cannot be combined with enabling/disabling or listing ports. .Bl -tag -width 12n .It Fl l List all CTL frontend ports or a specific port type or number. .It Fl o Ar on|off Turn the specified CTL frontend ports off or on. If no port number or port type is specified, all ports are turned on or off. -.It Fl p Ar targ_port +.It Fl p Ar targ_port Specify the frontend port number. The port numbers can be found in the frontend port list. .It Fl q Omit the header in the port list output. .It Fl t Ar fe_type Specify the frontend type. Currently defined port types are .Dq fc (Fibre Channel), .Dq scsi (Parallel SCSI), .Dq ioctl (CTL ioctl interface), and .Dq internal (CTL CAM SIM). .It Fl w Ar wwnn Set the World Wide Node Name for the given port. The -.Fl n +.Fl n argument must be specified, since this is only possible to implement on a single port. As a general rule, the WWNN should be the same across all ports on the system. .It Fl W Ar wwpn Set the World Wide Node Name for the given port. The .Fl n argument must be specified, since this is only possible to implement on a single port. As a general rule, the WWPN must be different for every port in the system. .It Fl x Output the port list in XML format. .El .It Ic dumpooa Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL. .It Ic dumpstructs Dump the CTL structures to the console. .It Ic create Create a new LUN. The backend must be specified, and depending upon the backend requested, some of the other options may be required. If the LUN is created successfully, the LUN configuration will be displayed. If LUN creation fails, a message will be displayed describing the failure. .Bl -tag -width 14n .It Fl b Ar backend The .Fl b flag is required. This specifies the name backend to use when creating the LUN. Examples are .Dq ramdisk and .Dq block . .It Fl B Ar blocksize Specify the blocksize of the backend in bytes. .It Fl d Ar device_id Specify the LUN-associated string to use in the .Tn SCSI INQUIRY VPD page 0x83 data. .It Fl l Ar lun_id Request that a particular LUN number be assigned. If the requested LUN number is not available, the request will fail. .It Fl o Ar name=value Specify a backend-specific name/value pair. Multiple .Fl o arguments may be specified. Refer to the backend documentation for arguments that may be used. .It Fl s Ar size_bytes Specify the size of the LUN in bytes. Some backends may allow setting the size (e.g. the ramdisk backend) and for others the size may be implicit (e.g. the block backend). .It Fl S Ar serial_num Specify the serial number to be used in the .Tn SCSI INQUIRY VPD page 0x80 data. .It Fl t Ar device_type Specify the numeric SCSI device type to use when creating the LUN. For example, the Direct Access type is 0. If this flag is not used, the type of LUN created is backend-specific. Not all LUN types are supported. Currently CTL only supports Direct Access (type 0) and Processor (type 3) LUNs. The backend requested may or may not support all of the LUN types that CTL supports. .El .It Ic remove Remove a LUN. The backend must be specified, and the LUN number must also be specified. Backend-specific options may also be specified with the .Fl o flag. .Bl -tag -width 14n .It Fl b Ar backend Specify the backend that owns the LUN to be removed. Examples are .Dq ramdisk and .Dq block . .It Fl l Ar lun_id Specify the LUN number to remove. .It Fl o Ar name=value Specify a backend-specific name/value pair. Multiple .Fl o arguments may be specified. Refer to the backend documentation for arguments that may be used. .El .It Ic devlist Get a list of all configured LUNs. This also includes the LUN size and blocksize, serial number and device ID. .Bl -tag -width 11n .It Fl b Ar backend Specify the backend. This restricts the LUN list to the named backend. Examples are .Dq ramdisk and .Dq block . .It Fl v Be verbose. This will also display any backend-specific LUN attributes in addition to the standard per-LUN information. .It Fl x Dump the raw XML. The LUN list information from the kernel comes in XML format, and this option allows the display of the raw XML data. This option and the .Fl v and .Fl b options are mutually exclusive. If you specify .Fl x , the entire LUN database is displayed in XML format. .El .It Ic help Display .Nm usage information. .El .Sh EXAMPLES .Dl ctladm tur 0:1 .Pp Send a .Tn SCSI TEST UNIT READY command to LUN 1. .Pp .Dl ctladm modesense 0:1 -l .Pp Display the list of mode pages supported by LUN 1. .Pp .Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10 .Pp Display the saved version of the Control mode page (page 10) on LUN 0. Disable fetching block descriptors, and use a 10 byte MODE SENSE command instead of the default 6 byte command. .Pp .Bd -literal ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo .Ed .Pp Read the first 512 byte block from LUN 2 and dump it to the file .Pa foo . .Bd -literal ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar .Ed .Pp Read 10240 bytes from the file .Pa /tmp/bar and write it to target 0, LUN 3. starting at LBA 0xff432140. .Pp .Dl ctladm create -b ramdisk -s 10485760000000000 .Pp Create a LUN with the .Dq fake ramdisk as a backing store. The LUN will claim to have a size of approximately 10 terabytes. .Pp .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 .Pp Create a LUN using the block backend, and specify the file .Pa src/usr.sbin/ctladm/ctladm.8 as the backing store. The size of the LUN will be derived from the size of the file. .Pp .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123 .Pp Create a LUN using the block backend, specify the file .Pa src/usr.sbin/ctladm/ctladm.8 as the backing store, and specify the .Tn SCSI VPD page 0x80 and 0x83 serial number ( .Fl S) and device ID ( .Fl d). .Pp .Dl ctladm remove -b block -l 12 .Pp Remove LUN 12, which is handled by the block backend, from the system. .Pp .Dl ctladm devlist .Pp List configured LUNs in the system, along with their backend and serial number. This works when the Front End Target Drivers are enabled or disabled. .Pp .Dl ctladm lunlist .Pp List all LUNs in the system, along with their inquiry data and device type. -This only works when the FETDs are enabled, since the commands go through the +This only works when the FETDs are enabled, since the commands go through the ioctl port. .Pp .Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c .Pp Inject a medium error on LUN 6 for every read that covers the first 512 blocks of the LUN. .Pp .Bd -literal -offset indent ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02" .Ed .Pp Inject a custom error on LUN 6 for the next TEST UNIT READY command only. This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of 0x04,0x02 ("Logical unit not ready, initializing command required"). .Sh SEE ALSO .Xr cam 3 , .Xr cam_cdbparse 3 , .Xr cam 4 , .Xr xpt 4 , .Xr camcontrol 8 .Sh HISTORY The .Nm utility was originally written during the Winter/Spring of 2003 as an interface to CTL. .Sh AUTHORS .An Ken Merry Aq ken@FreeBSD.org Index: stable/9/usr.sbin/ctladm =================================================================== --- stable/9/usr.sbin/ctladm (revision 237215) +++ stable/9/usr.sbin/ctladm (revision 237216) Property changes on: stable/9/usr.sbin/ctladm ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/largeSMP/usr.sbin/ctladm:r221273-222812,222815-223757 Merged /projects/head_mfi/usr.sbin/ctladm:r233621 Merged /vendor/resolver/dist/usr.sbin/ctladm:r1540-186085 Merged /projects/quota64/usr.sbin/ctladm:r184125-207707 Merged /head/usr.sbin/ctladm:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Index: stable/9/usr.sbin/edquota/edquota.8 =================================================================== --- stable/9/usr.sbin/edquota/edquota.8 (revision 237215) +++ stable/9/usr.sbin/edquota/edquota.8 (revision 237216) @@ -1,264 +1,264 @@ .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Robert Elz at The University of Melbourne. .\" .\" 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. .\" 4. 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. .\" .\" @(#)edquota.8 8.1 (Berkeley) 6/6/93 .\" $FreeBSD$ .\" .Dd June 6, 1993 .Dt EDQUOTA 8 .Os .Sh NAME .Nm edquota .Nd edit user quotas .Sh SYNOPSIS .Nm .Op Fl uh .Op Fl f Ar fspath .Op Fl p Ar proto-username .Ar username ... .Nm .Op Fl u .Fl e .Sm off .Ar fspath Op : Ar bslim Op : Ar bhlim Op : Ar islim Op : Ar ihlim .Sm on .Op Fl e Ar ... .Ar username ... .Nm .Fl g .Op Fl h .Op Fl f Ar fspath .Op Fl p Ar proto-groupname .Ar groupname ... .Nm .Fl g .Fl e .Sm off .Ar fspath Op : Ar bslim Op : Ar bhlim Op : Ar islim Op : Ar ihlim .Sm on .Op Fl e Ar ... .Ar groupname ... .Nm .Fl t .Op Fl u .Op Fl f Ar fspath .Nm .Fl t .Fl g .Op Fl f Ar fspath .Sh DESCRIPTION The .Nm utility is a quota editor. By default, or if the .Fl u flag is specified, one or more users may be specified on the command line. For each user a temporary file is created with an .Tn ASCII representation of the current disk quotas for that user. The list of file systems with user quotas is determined from .Pa /etc/fstab . An editor is invoked on the .Tn ASCII file. The editor invoked is .Xr vi 1 unless the environment variable .Ev EDITOR specifies otherwise. .Pp The quotas may then be modified, new quotas added, etc. Block quotas can be specified in bytes (B), kilobytes (K), megabytes (M), terabytes (T), petabytes (P), or exabytes (E). If no units are specified, kilobytes are assumed. Inode quotas can be specified in kiloinodes (K), megainodes (M), terainodes (T), petainodes (P), or exainodes (E). If no units are specified, the number of inodes specified are used. If the .Fl h -flag is specified, the editor will always display the +flag is specified, the editor will always display the block usage and limits in a more human readable format rather than displaying them in the historic kilobyte format. Setting a quota to zero indicates that no quota should be imposed. Setting a hard limit to one indicates that no allocations should be permitted. Setting a soft limit to one with a hard limit of zero indicates that allocations should be permitted only on a temporary basis (see .Fl t below). The current usage information in the file is for informational purposes; only the hard and soft limits can be changed. .Pp On leaving the editor, .Nm reads the temporary file and modifies the binary quota files to reflect the changes made. .Pp If the .Fl p option is specified, .Nm will duplicate the quotas of the prototypical user specified for each user specified. This is the normal mechanism used to initialize quotas for groups of users. If the user given to assign quotas to is a numerical uid range (e.g.\& 1000-2000), then .Nm will duplicate the quotas of the prototypical user for each uid in the range specified. This allows for easy setup of default quotas for a group of users. The uids in question do not have to be currently assigned in .Pa /etc/passwd . .Pp If one or more .Fl e .Sm off .Ar fspath Op : Ar bslim Op : Ar bhlim Op : Ar islim Op : Ar ihlim .Sm on options are specified, .Nm will non-interactively set quotas defined by .Ar bslim , bhlim , islim , and .Ar ihlim on each particular file system referenced by .Ar fspath . Here .Ar bslim is the soft limit on the number of blocks, .Ar bhlim is the hard limit on the number of blocks, .Ar islim is the soft limit on the number of files, and .Ar ihlim is the hard limit on the number of files. If any of the .Ar bslim , bhlim , islim , and .Ar ihlim values is omitted, it is assumed to be zero, therefore indicating that no particular quota should be imposed. Block quotas can be specified in bytes (B), kilobytes (K), megabytes (M), terabytes (T), petabytes (P), or exabytes (E). If no units are specified, kilobytes are assumed. Inode quotas can be specified in kiloinodes (K), megainodes (M), terainodes (T), petainodes (P), or exainodes (E). If no units are specified, the number of inodes specified are used. .Pp If invoked with the .Fl f option, .Nm will read and modify quotas on the file system specified by .Ar fspath only. The .Ar fspath argument may be either a special device or a file system mount point. The primary purpose of this option is to set the scope for the .Fl p option, which would overwrite quota records on every file system with quotas otherwise. .Pp If the .Fl g flag is specified, .Nm is invoked to edit the quotas of one or more groups specified on the command line. The .Fl p flag can be specified in conjunction with the .Fl g flag to specify a prototypical group to be duplicated among the listed set of groups. Similarly, .Fl e flag can be specified in conjunction with the .Fl g flag to non-interactively set-up quotas on the listed set of groups. .Pp Users are permitted to exceed their soft limits for a grace period that may be specified per file system. Once the grace period has expired, the soft limit is enforced as a hard limit. The default grace period for a file system is specified in .In ufs/ufs/quota.h . The .Fl t flag can be used to change the grace period. By default, or when invoked with the .Fl u flag, the grace period is set for all the file systems with user quotas specified in .Pa /etc/fstab . When invoked with the .Fl g flag the grace period is set for all the file systems with group quotas specified in .Pa /etc/fstab . The grace period may be specified in days, hours, minutes, or seconds. Setting a grace period to zero indicates that the default grace period should be imposed. Setting a grace period to one second indicates that no grace period should be granted. Quotas must be turned off for the file system and then turned back on for the new grace period to take effect. .Pp Only the super-user may edit quotas. .Sh FILES .Bl -tag -width quota.group -compact .It Pa quota.user at the file system root with user quotas .It Pa quota.group at the file system root with group quotas .It Pa /etc/fstab to find file system names and locations .El .Sh DIAGNOSTICS Various messages about inaccessible files; self-explanatory. .Sh SEE ALSO .Xr quota 1 , .Xr quotactl 2 , .Xr fstab 5 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr repquota 8 Index: stable/9/usr.sbin/edquota =================================================================== --- stable/9/usr.sbin/edquota (revision 237215) +++ stable/9/usr.sbin/edquota (revision 237216) Property changes on: stable/9/usr.sbin/edquota ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /vendor/resolver/dist/usr.sbin/edquota:r1540-186085 Merged /projects/largeSMP/usr.sbin/edquota:r221273-222812,222815-223757 Merged /projects/quota64/usr.sbin/edquota:r184125-207707 Merged /projects/head_mfi/usr.sbin/edquota:r233621 Merged /head/usr.sbin/edquota:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Index: stable/9/usr.sbin/freebsd-update/freebsd-update.8 =================================================================== --- stable/9/usr.sbin/freebsd-update/freebsd-update.8 (revision 237215) +++ stable/9/usr.sbin/freebsd-update/freebsd-update.8 (revision 237216) @@ -1,177 +1,177 @@ .\"- .\" Copyright 2006, 2007 Colin Percival .\" All rights reserved .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted providing 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 ``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 July 14, 2010 .Dt FREEBSD-UPDATE 8 .Os FreeBSD .Sh NAME .Nm freebsd-update .Nd fetch and install binary updates to FreeBSD .Sh SYNOPSIS .Nm .Op Fl b Ar basedir .Op Fl d Ar workdir .Op Fl f Ar conffile .Op Fl k Ar KEY .Op Fl r Ar newrelease .Op Fl s Ar server .Op Fl t Ar address .Cm command ... .Sh DESCRIPTION The .Nm tool is used to fetch, install, and rollback binary updates to the FreeBSD base system. Note that updates are only available if they are being built for the FreeBSD release and architecture being used; in particular, the .Fx -Security Team only builds updates for releases shipped in binary form +Security Team only builds updates for releases shipped in binary form by the .Fx Release Engineering Team, e.g., .Fx 7.3-RELEASE and .Fx 8.0-RELEASE, but not .Fx 6.3-STABLE or .Fx 9.0-CURRENT. .Sh OPTIONS The following options are supported .Bl -tag -width "-f conffile" .It Fl b Ar basedir Operate on a system mounted at .Ar basedir . (default: .Pa / , or as given in the configuration file.) .It Fl d Ar workdir Store working files in .Ar workdir . (default: .Pa /var/db/freebsd-update/ , or as given in the configuration file.) .It Fl f Ar conffile Read configuration options from .Ar conffile . (default: .Pa /etc/freebsd-update.conf ) .It Fl k Ar KEY Trust an RSA key with SHA256 of .Ar KEY . (default: read value from configuration file.) .It Fl r Ar newrelease Specify the new release to which .Nm should upgrade (upgrade command only). .It Fl s Ar server Fetch files from the specified server or server pool. (default: read value from configuration file.) .It Fl t Ar address Mail output of .Cm cron command, if any, to .Ar address . (default: root, or as given in the configuration file.) .El .Sh COMMANDS The .Cm command can be any one of the following: .Bl -tag -width "-f conffile" .It Cm fetch Based on the currently installed world and the configuration options set, fetch all available binary updates. .It Cm cron Sleep a random amount of time between 1 and 3600 seconds, then download updates as if the .Cm fetch command was used. If updates are downloaded, an email will be sent (to root or a different address if specified via the .Fl t option or in the configuration file). As the name suggests, this command is designed for running from .Xr cron 8 ; the random delay serves to minimize the probability that a large number of machines will simultaneously attempt to fetch updates. .It Cm upgrade Fetch files necessary for upgrading to a new release. Before using this command, make sure that you read the announcement and release notes for the new release in case there are any special steps needed for upgrading. Note that this command may require up to 500 MB of space in .Ar workdir depending on which components of the .Fx base system are installed. .It Cm install Install the most recently fetched updates or upgrade. .It Cm rollback Uninstall the most recently installed updates. .It Cm IDS Compare the system against a "known good" index of the installed release. .El .Sh TIPS .Bl -bullet .It If your clock is set to local time, adding the line .Pp .Dl 0 3 * * * root /usr/sbin/freebsd-update cron .Pp to /etc/crontab will check for updates every night. If your clock is set to UTC, please pick a random time other than 3AM, to avoid overly imposing an uneven load on the server(s) hosting the updates. .It In spite of its name, .Nm IDS should not be relied upon as an "Intrusion Detection System", since if the system has been tampered with it cannot be trusted to operate correctly. If you intend to use this command for intrusion-detection purposes, make sure you boot from a secure disk (e.g., a CD). .El .Sh FILES .Bl -tag -width "/etc/freebsd-update.conf" .It /etc/freebsd-update.conf Default location of the .Nm configuration file. .It /var/db/freebsd-update/ Default location where .Nm stores temporary files and downloaded updates. .El .Sh SEE ALSO .Xr freebsd-update.conf 5 .Sh AUTHORS .An Colin Percival Aq cperciva@FreeBSD.org Index: stable/9/usr.sbin/freebsd-update =================================================================== --- stable/9/usr.sbin/freebsd-update (revision 237215) +++ stable/9/usr.sbin/freebsd-update (revision 237216) Property changes on: stable/9/usr.sbin/freebsd-update ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/freebsd-update:r233648 Index: stable/9/usr.sbin/gpioctl/gpioctl.8 =================================================================== --- stable/9/usr.sbin/gpioctl/gpioctl.8 (revision 237215) +++ stable/9/usr.sbin/gpioctl/gpioctl.8 (revision 237216) @@ -1,119 +1,119 @@ .\" 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. .\" 4. 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. .\" .\" $FreeBSD$ .\" .Dd May 25, 2011 .Dt GPIOCTL 1 .Os .Sh NAME .Nm gpioctl .Nd GPIO control utility .Sh SYNOPSIS .Nm -.Cm -l +.Cm -l .Fl f Ar ctldev .Op Fl v .Nm -.Cm -t +.Cm -t .Fl f Ar ctldev .Ar pin .Nm -.Cm -c +.Cm -c .Fl f Ar ctldev .Ar pin -.Ar flag +.Ar flag .Op flag ... .Nm -.Cm -f Ar ctldev +.Cm -f Ar ctldev .Ar pin .Ar [0|1] .Sh DESCRIPTION The .Nm utility could be used to manage GPIO pins from userland and list available pins. .Pp The options are as follows: .Bl -tag -width ".Fl f Ar ctldev" .It Fl c Ar pin Ar flag Op flag ... Configure pin by setting provided flags. The following flags are currently defined: .Bl -tag -offset indent -width ".Cm PULSE" .It Cm IN Input pin .It Cm OUT Output pin .It Cm OD Open drain pin .It Cm PP Push pull pin .It Cm TS Tristate pin .It Cm PU Pull-up pin .It Cm PD Pull-down pin .It Cm II Inverted input pin .It Cm IO Inverted output pin .El .It Fl f Ar ctldev GPIO controller device to use .It Fl l list available pins .It Fl t Ar pin toggle value of provided pin number .It Fl v be verbose: for each listed pin print current configuration .El .Sh EXAMPLES .Bl -bullet .It List pins available on GPIO controller defined by device /dev/gpioc0 .Pp gpioctl -f /dev/gpioc0 -l .It Set the value of pin 12 to 1 .Pp gpioctl -f /dev/gpioc0 12 1 .It Configure pin 12 to be input pin .Pp gpioctl -f /dev/gpioc0 -c 12 IN .El .Sh HISTORY The .Nm utility appeared in .Fx 9.0 . .Sh AUTHORS .An -nosplit The .Nm utility and this manual page were written by .An Oleksandr Tymoshenko .Aq gonzo@freebsd.org Index: stable/9/usr.sbin/gpioctl =================================================================== --- stable/9/usr.sbin/gpioctl (revision 237215) +++ stable/9/usr.sbin/gpioctl (revision 237216) Property changes on: stable/9/usr.sbin/gpioctl ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /head/usr.sbin/gpioctl:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /projects/largeSMP/usr.sbin/gpioctl:r221273-222812,222815-223757 Merged /projects/head_mfi/usr.sbin/gpioctl:r233621 Merged /vendor/resolver/dist/usr.sbin/gpioctl:r1540-186085 Merged /projects/quota64/usr.sbin/gpioctl:r184125-207707 Index: stable/9/usr.sbin/i2c/i2c.8 =================================================================== --- stable/9/usr.sbin/i2c/i2c.8 (revision 237215) +++ stable/9/usr.sbin/i2c/i2c.8 (revision 237216) @@ -1,166 +1,166 @@ .\" .\" Copyright (C) 2008-2009 Semihalf, Michal Hajduk and Bartlomiej Sieka .\" 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 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$ +.\" $FreeBSD$ .\" .Dd January 23, 2009 .Dt I2C 8 .Os .Sh NAME .Nm i2c -.Nd test I2C bus and slave devices +.Nd test I2C bus and slave devices .Sh SYNOPSIS .Nm .Cm -a Ar address .Op Fl f Ar device .Op Fl d Ar r|w .Op Fl w Ar 0|8|16 .Op Fl o Ar offset .Op Fl c Ar count .Op Fl m Ar ss|rs|no .Op Fl b .Op Fl v .Nm .Cm -s .Op Fl f Ar device .Op Fl n Ar skip_addr .Op Fl v .Nm .Cm -r .Op Fl f Ar device .Op Fl v .Sh DESCRIPTION The .Nm utility can be used to perform raw data transfers (read or write) with devices on the I2C bus. It can also scan the bus for available devices and reset the I2C controller. .Pp The options are as follows: .Bl -tag -width ".Fl d Ar direction" .It Fl a Ar address 7-bit address on the I2C device to operate on (hex). .It Fl b binary mode - when performing a read operation, the data read from the device is output in binary format on stdout; when doing a write, the binary data to be written to the device is read from stdin. .It Fl c Ar count number of bytes to transfer (dec). .It Fl d Ar r|w transfer direction: r - read, w - write. .It Fl f Ar device I2C bus to use (default is /dev/iic0). .It Fl m Ar ss|rs|no addressing mode, i.e., I2C bus operations performed after the offset for the transfer has been written to the device and before the actual read/write operation. rs - repeated start; ss - stop start; no - none. .It Fl n Ar skip_addr skip address - address(es) to be skipped during bus scan. There are two ways to specify addresses to ignore: by range 'a..b' or using selected addresses 'a:b:c'. This option is available only when "-s" is used. .It Fl o Ar offset offset within the device for data transfer (hex). .It Fl r reset the controller. .It Fl s scan the bus for devices. .It Fl v be verbose .It Fl w Ar 0|8|16 device addressing width (in bits). .El .Sh WARNINGS Great care must be taken when manipulating slave I2C devices with the .Nm utility. Often times important configuration data for the system is kept in non-volatile but write enabled memories located on the I2C bus, for example Ethernet hardware addresses, RAM module parameters (SPD), processor reset configuration word etc. .Pp It is very easy to render the whole system unusable when such configuration data is deleted or altered, so use the .Dq -d w (write) command only if you know exactly what you are doing. .Pp Also avoid ungraceful interrupting of an ongoing transaction on the I2C bus, as it can lead to potentially dangerous effects. Consider the following scenario: when the host CPU is reset (for whatever reason) in the middle of a started I2C transaction, the I2C slave device could be left in write mode waiting for data or offset to arrive. When the CPU reinitializes itself and talks to this I2C slave device again, the commands and other control info it sends are treated by the slave device as data or offset it was waiting for, and there's great potential for corruption if such a write is performed. .Sh EXAMPLES .Bl -bullet .It Scan the default bus (/dev/iic0) for devices: .Pp i2c -s .It -Scan the default bus (/dev/iic0) for devices and skip addresses 0x56 and +Scan the default bus (/dev/iic0) for devices and skip addresses 0x56 and 0x45. .Pp i2c -s -n 0x56:0x45 .It -Scan the default bus (/dev/iic0) for devices and skip address range +Scan the default bus (/dev/iic0) for devices and skip address range 0x34 to 0x56. .Pp i2c -s -n 0x34..0x56 .It Read 8 bytes of data from device at address 0x56 (e.g., an EEPROM): .Pp i2c -a 0x56 -d r -c 8 .It Write 16 bytes of data from file data.bin to device 0x56 at offset 0x10: .Pp i2c -a 0x56 -d w -c 16 -o 0x10 -b < data.bin .It Copy 4 bytes between two EEPROMs (0x56 on /dev/iic1 to 0x57 on /dev/iic0): .Pp i2c -a 0x56 -f /dev/iic1 -d r -c 0x4 -b | i2c -a 0x57 -f /dev/iic0 -d w -c 4 -b .It Reset the controller: .Pp i2c -f /dev/iic1 -r .El .Sh SEE ALSO .Xr iic 4 , .Xr iicbus 4 .Sh HISTORY The .Nm utility appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm utility and this manual page were written by .An Bartlomiej Sieka .Aq tur@semihalf.com -and +and .An Michal Hajduk .Aq mih@semihalf.com . Index: stable/9/usr.sbin/i2c =================================================================== --- stable/9/usr.sbin/i2c (revision 237215) +++ stable/9/usr.sbin/i2c (revision 237216) Property changes on: stable/9/usr.sbin/i2c ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/i2c:r233648 Index: stable/9/usr.sbin/mountd/exports.5 =================================================================== --- stable/9/usr.sbin/mountd/exports.5 (revision 237215) +++ stable/9/usr.sbin/mountd/exports.5 (revision 237216) @@ -1,509 +1,509 @@ .\" Copyright (c) 1989, 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. .\" 4. 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. .\" .\" @(#)exports.5 8.3 (Berkeley) 3/29/95 .\" $FreeBSD$ .\" .Dd July 12, 2011 .Dt EXPORTS 5 .Os .Sh NAME .Nm exports .Nd define remote mount points for .Tn NFS mount requests .Sh SYNOPSIS .Nm .Sh DESCRIPTION The .Nm file specifies remote mount points for the .Tn NFS mount protocol per the .Tn NFS server specification; see .%T "Network File System Protocol Specification" , RFC1094, Appendix A and .%T "NFS: Network File System Version 3 Specification" , Appendix I. .Pp Each line in the file (other than comment lines that begin with a #) specifies the mount point(s) and export flags within one local server file system or the NFSv4 tree root for one or more hosts. A long line may be split over several lines by ending all but the last line with a backslash .Pq Ql \e . A host may be specified only once for each local file or the NFSv4 tree root on the server and there may be only one default entry for each server file system that applies to all other hosts. The latter exports the file system to the .Dq world and should be used only when the file system contains public information. .Pp In a mount entry, the first field(s) specify the directory path(s) within a server file system that can be mounted on by the corresponding client(s). There are three forms of this specification. The first is to list all mount points as absolute directory paths separated by whitespace. This list of directory paths should be considered an -.Dq administrative control , +.Dq administrative control , since it is only enforced by the .Xr mountd 8 daemon and not the kernel. As such, it only applies to NFSv2 and NFSv3 mounts and only with respect to the client's use of the mount protocol. The second is to specify the pathname of the root of the file system followed by the .Fl alldirs flag; this form allows the host(s) to mount at any point within the file system, including regular files if the .Fl r option is used on .Xr mountd 8 . Because NFSv4 does not use the mount protocol, the -.Dq administrative controls +.Dq administrative controls are not applied. Thus, all the above export line(s) should be considered to have the .Fl alldirs flag, even if the line is specified without it. The third form has the string ``V4:'' followed by a single absolute path name, to specify the NFSv4 tree root. This line does not export any file system, but simply marks where the root of the server's directory tree is for NFSv4 clients. The exported file systems for NFSv4 are specified via the other lines in the .Xr exports 5 file in the same way as for NFSv2 and NFSv3. The pathnames must not have any symbolic links in them and should not have any .Dq Pa \&. or .Dq Pa .. components. Mount points for a file system may appear on multiple lines each with different sets of hosts and export options. .Pp The second component of a line specifies how the file system is to be exported to the host set. The option flags specify whether the file system is exported read-only or read-write and how the client UID is mapped to user credentials on the server. For the NFSv4 tree root, the only option that can be specified in this section is .Fl sec . .Pp Export options are specified as follows: .Pp .Sm off .Fl maproot Li = Sy user .Sm on The credential of the specified user is used for remote access by root. The credential includes all the groups to which the user is a member on the local machine (see .Xr id 1 ) . The user may be specified by name or number. .Pp .Sm off .Fl maproot Li = Sy user:group1:group2:... .Sm on The colon separated list is used to specify the precise credential to be used for remote access by root. The elements of the list may be either names or numbers. Note that user: should be used to distinguish a credential containing no groups from a complete credential for that user. .Pp .Sm off .Fl mapall Li = Sy user .Sm on or .Sm off .Fl mapall Li = Sy user:group1:group2:... .Sm on specifies a mapping for all client UIDs (including root) using the same semantics as .Fl maproot . .Pp The option .Fl r is a synonym for .Fl maproot in an effort to be backward compatible with older export file formats. .Pp In the absence of .Fl maproot and .Fl mapall options, remote accesses by root will result in using a credential of -2:-2. All other users will be mapped to their remote credential. If a .Fl maproot option is given, remote access by root will be mapped to that credential instead of -2:-2. If a .Fl mapall option is given, all users (including root) will be mapped to that credential in place of their own. .Pp .Sm off .Fl sec Li = Sy flavor1:flavor2... .Sm on specifies a colon separated list of acceptable security flavors to be used for remote access. Supported security flavors are sys, krb5, krb5i and krb5p. If multiple flavors are listed, they should be ordered with the most preferred flavor first. If this option is not present, the default security flavor list of just sys is used. .Pp The .Fl ro option specifies that the file system should be exported read-only (default read/write). The option .Fl o is a synonym for .Fl ro in an effort to be backward compatible with older export file formats. .Pp .Tn WebNFS exports strictly according to the spec (RFC 2054 and RFC 2055) can be done with the .Fl public flag. However, this flag in itself allows r/w access to all files in the file system, not requiring reserved ports and not remapping UIDs. It is only provided to conform to the spec, and should normally not be used. For a .Tn WebNFS export, use the .Fl webnfs flag, which implies .Fl public , .Sm off .Fl mapall No = Sy nobody .Sm on and .Fl ro . Note that only one file system can be .Tn WebNFS exported on a server. .Pp A .Sm off .Fl index No = Pa file .Sm on option can be used to specify a file whose handle will be returned if a directory is looked up using the public filehandle .Pq Tn WebNFS . This is to mimic the behavior of URLs. If no .Fl index option is specified, a directory filehandle will be returned as usual. The .Fl index option only makes sense in combination with the .Fl public or .Fl webnfs flags. .Pp Specifying the .Fl quiet option will inhibit some of the syslog diagnostics for bad lines in .Pa /etc/exports . This can be useful to avoid annoying error messages for known possible problems (see .Sx EXAMPLES below). .Pp The third component of a line specifies the host set to which the line applies. The set may be specified in three ways. The first way is to list the host name(s) separated by white space. (Standard Internet .Dq dot addresses may be used in place of names.) The second way is to specify a .Dq netgroup as defined in the .Pa netgroup file (see .Xr netgroup 5 ) . The third way is to specify an Internet subnetwork using a network and network mask that is defined as the set of all hosts with addresses within the subnetwork. This latter approach requires less overhead within the kernel and is recommended for cases where the export line refers to a large number of clients within an administrative subnet. .Pp The first two cases are specified by simply listing the name(s) separated by whitespace. All names are checked to see if they are .Dq netgroup names first and are assumed to be hostnames otherwise. Using the full domain specification for a hostname can normally circumvent the problem of a host that has the same name as a netgroup. The third case is specified by the flag .Sm off .Fl network Li = Sy netname Op Li / Ar prefixlength .Sm on and optionally .Sm off .Fl mask No = Sy netmask . .Sm on The netmask may be specified either by attaching a .Ar prefixlength to the .Fl network option, or by using a separate .Fl mask option. If the mask is not specified, it will default to the mask for that network class (A, B or C; see .Xr inet 4 ) . See the .Sx EXAMPLES section below. .Pp Scoped IPv6 address must carry scope identifier as documented in .Xr inet6 4 . For example, .Dq Li fe80::%re2/10 is used to specify .Li fe80::/10 on .Li re2 interface. .Pp For the third form which specifies the NFSv4 tree root, the directory path specifies the location within the server's file system tree which is the root of the NFSv4 tree. All entries of this form must specify the same directory path. This location can be any directory and does not need to be within an exported file system. If it is not in an exported file system, a very limited set of operations are permitted, so that an NFSv4 client can traverse the tree to an exported file system. Although parts of the NFSv4 tree can be non-exported, the entire NFSv4 tree must consist of local file systems capable of being exported via NFS. NFSv4 does not use the mount protocol and does permit clients to cross server mount point boundaries, although not all clients are capable of crossing the mount points. .Pp The .Fl sec option on these line(s) specifies what security flavors may be used for NFSv4 operations that do not use file handles. Since these operations (SetClientID, SetClientIDConfirm, Renew, DelegPurge and ReleaseLockOnwer) allocate/modify state in the server, it is possible to restrict some clients to the use of the krb5[ip] security flavors, via this option. See the .Sx EXAMPLES section below. This third form is meaningless for NFSv2 and NFSv3 and is ignored for them. .Pp The .Xr mountd 8 utility can be made to re-read the .Nm file by sending it a hangup signal as follows: .Bd -literal -offset indent /etc/rc.d/mountd reload .Ed .Pp After sending the .Dv SIGHUP , check the .Xr syslogd 8 output to see whether .Xr mountd 8 logged any parsing errors in the .Nm file. .Sh FILES .Bl -tag -width /etc/exports -compact .It Pa /etc/exports the default remote mount-point file .El .Sh EXAMPLES .Bd -literal -offset indent /usr /usr/local -maproot=0:10 friends /usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 /usr -ro -mapall=nobody /u -maproot=bin: -network 131.104.48 -mask 255.255.255.0 /a -network 192.168.0/24 /a -network 3ffe:1ce1:1:fe80::/64 /u2 -maproot=root friends /u2 -alldirs -network cis-net -mask cis-mask /cdrom -alldirs,quiet,ro -network 192.168.33.0 -mask 255.255.255.0 /private -sec=krb5i /secret -sec=krb5p V4: / -sec=krb5:krb5i:krb5p -network 131.104.48 -mask 255.255.255.0 V4: / -sec=sys:krb5:krb5i:krb5p grumpy.cis.uoguelph.ca .Ed .Pp Given that .Pa /usr , /u , /a and .Pa /u2 are local file system mount points, the above example specifies the following: .Pp The file system rooted at .Pa /usr is exported to hosts .Em friends where friends is specified in the netgroup file with users mapped to their remote credentials and root mapped to UID 0 and group 10. It is exported read-write and the hosts in .Dq friends can mount either .Pa /usr or .Pa /usr/local . It is exported to .Em 131.104.48.16 and .Em grumpy.cis.uoguelph.ca with users mapped to their remote credentials and root mapped to the user and groups associated with .Dq daemon ; it is exported to the rest of the world as read-only with all users mapped to the user and groups associated with .Dq nobody . .Pp The file system rooted at .Pa /u is exported to all hosts on the subnetwork .Em 131.104.48 with root mapped to the UID for .Dq bin and with no group access. .Pp The file system rooted at .Pa /u2 is exported to the hosts in .Dq friends with root mapped to UID and groups associated with .Dq root ; it is exported to all hosts on network .Dq cis-net allowing mounts at any directory within /u2. .Pp The file system rooted at .Pa /a is exported to the network 192.168.0.0, with a netmask of 255.255.255.0. However, the netmask length in the entry for .Pa /a is not specified through a .Fl mask option, but through the .Li / Ns Ar prefix notation. .Pp The file system rooted at .Pa /a is also exported to the IPv6 network .Li 3ffe:1ce1:1:fe80:: address, using the upper 64 bits as the prefix. Note that, unlike with IPv4 network addresses, the specified network address must be complete, and not just contain the upper bits. With IPv6 addresses, the .Fl mask option must not be used. .Pp The file system rooted at .Pa /cdrom will be exported read-only to the entire network 192.168.33.0/24, including all its subdirectories. Since .Pa /cdrom is the conventional mountpoint for a CD-ROM device, this export will fail if no CD-ROM medium is currently mounted there since that line would then attempt to export a subdirectory of the root file system with the .Fl alldirs option which is not allowed. The .Fl quiet option will then suppress the error message for this condition that would normally be syslogged. As soon as an actual CD-ROM is going to be mounted, .Xr mount 8 will notify .Xr mountd 8 about this situation, and the .Pa /cdrom file system will be exported as intended. Note that without using the .Fl alldirs option, the export would always succeed. While there is no CD-ROM medium mounted under .Pa /cdrom , it would export the (normally empty) directory .Pa /cdrom of the root file system instead. .Pp The file system rooted at .Pa /private will be exported using Kerberos 5 authentication and will require integrity protected messages for all accesses. The file system rooted at .Pa /secret will also be exported using Kerberos 5 authentication and all messages used to access it will be encrypted. .Pp For the experimental server, the NFSv4 tree is rooted at ``/'', and any client within the 131.104.48 subnet is permitted to perform NFSv4 state operations on the server, so long as valid Kerberos credentials are provided. The machine grumpy.cis.uoguelph.ca is permitted to perform NFSv4 state operations on the server using AUTH_SYS credentials, as well as Kerberos ones. .Sh SEE ALSO .Xr nfsv4 4 , .Xr netgroup 5 , .Xr mountd 8 , .Xr nfsd 8 , .Xr showmount 8 .Sh BUGS The export options are tied to the local mount points in the kernel and must be non-contradictory for any exported subdirectory of the local server mount point. It is recommended that all exported directories within the same server file system be specified on adjacent lines going down the tree. You cannot specify a hostname that is also the name of a netgroup. Specifying the full domain specification for a hostname can normally circumvent the problem. Index: stable/9/usr.sbin/mountd =================================================================== --- stable/9/usr.sbin/mountd (revision 237215) +++ stable/9/usr.sbin/mountd (revision 237216) Property changes on: stable/9/usr.sbin/mountd ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/quota64/usr.sbin/mountd:r184125-207707 Merged /head/usr.sbin/mountd:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /projects/largeSMP/usr.sbin/mountd:r221273-222812,222815-223757 Merged /projects/head_mfi/usr.sbin/mountd:r233621 Merged /vendor/resolver/dist/usr.sbin/mountd:r1540-186085 Index: stable/9/usr.sbin/mptutil/mptutil.8 =================================================================== --- stable/9/usr.sbin/mptutil/mptutil.8 (revision 237215) +++ stable/9/usr.sbin/mptutil/mptutil.8 (revision 237216) @@ -1,398 +1,398 @@ .\" .\" Copyright (c) 2008 Yahoo!, Inc. .\" All rights reserved. .\" Written by: John Baldwin .\" .\" 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 author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd August 16, 2009 .Dt MPTUTIL 8 .Os .Sh NAME .Nm mptutil .Nd Utility for managing LSI Fusion-MPT controllers .Sh SYNOPSIS .Nm .Cm version .Nm .Op Fl u Ar unit .Cm show adapter .Nm .Op Fl u Ar unit .Cm show config .Nm .Op Fl u Ar unit .Cm show drives .Nm .Op Fl u Ar unit .Cm show events .Nm .Op Fl u Ar unit .Cm show volumes .Nm .Op Fl u Ar unit .Cm fail Ar drive .Nm .Op Fl u Ar unit .Cm online Ar drive .Nm .Op Fl u Ar unit .Cm offline Ar drive .Nm .Op Fl u Ar unit .Cm name Ar volume Ar name .Nm .Op Fl u Ar unit .Cm volume status Ar volume .Nm .Op Fl u Ar unit -.Cm volume cache Ar volume +.Cm volume cache Ar volume .Ar enable|disable .Nm .Op Fl u Ar unit .Cm clear .Nm .Op Fl u Ar unit .Cm create Ar type .Op Fl q .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Nm .Op Fl u Ar unit .Cm delete Ar volume .Nm .Op Fl u Ar unit .Cm add Ar drive Op Ar volume .Nm .Op Fl u Ar unit .Cm remove Ar drive .Sh DESCRIPTION The .Nm utility can be used to display or modify various parameters on LSI Fusion-MPT controllers. Each invocation of .Nm consists of zero or more global options followed by a command. Commands may support additional optional or required arguments after the command. .Pp Currently one global option is supported: .Bl -tag -width indent .It Fl u Ar unit .Ar unit specifies the unit of the controller to work with. If no unit is specified, then unit 0 is used. .El .Pp Volumes may be specified in two forms. First, a volume may be identified by its location as .Sm off .Op Ar xx Ns \&: .Ar yy .Sm on where .Ar xx is the bus ID and .Ar yy is the target ID. If the bus ID is omitted, the volume is assumed to be on bus 0. Second, on the volume may be specified by the corresponding .Em daX device, such as .Em da0 . .Pp The .Xr mpt 4 controller divides drives up into two categories. Configured drives belong to a RAID volume either as a member drive or as a hot spare. Each configured drive is assigned a unique device ID such as 0 or 1 that is show in .Cm show config , and in the first column of .Cm show drives . Any drive not associated with a RAID volume as either a member or a hot spare is a standalone drive. Standalone drives are visible to the operating system as SCSI disk devices. As a result, drives may be specified in three forms. First, a configured drive may be identified by its device ID. Second, any drive may be identified by its location as .Sm off .Ar xx Ns \&: .Ar yy .Sm on where .Ar xx is the bus ID and .Ar yy is the target ID for each drive as displayed in .Cm show drives . Note that unlike volumes, a drive location always requires the bus ID to avoid confusion with device IDs. Third, a standalone drive that is not part of a volume may be identified by its corresponding .Em daX device as displayed in .Cm show drives . .Pp The .Nm utility supports several different groups of commands. The first group of commands provide information about the controller, the volumes it manages, and the drives it controls. The second group of commands are used to manage the physical drives attached to the controller. The third group of commands are used to manage the logical volumes managed by the controller. The fourth group of commands are used to manage the drive configuration for the controller. .Pp The informational commands include: .Bl -tag -width indent .It Cm version Displays the version of .Nm . .It Cm show adapter Displays information about the RAID controller such as the model number. .It Cm show config Displays the volume and drive configuration for the controller. Each volume is listed along with the physical drives that the volume spans. If any hot spare drives are configured, then they are listed as well. .It Cm show drives Lists all of the physical drives attached to the controller. .It Cm show events Display all the entries from the controller's event log. Due to lack of documentation this command isn't very useful currently and just dumps each log entry in hex. .It Cm show volumes Lists all of the logical volumes managed by the controller. .El .Pp The physical drive management commands include: .Bl -tag -width indent .It Cm fail Ar drive Mark .Ar drive as .Dq failed requested . Note that this state is different from the .Dq failed state that is used when the firmware fails a drive. .Ar Drive must be a configured drive. .It Cm online Ar drive Mark .Ar drive as an online drive. .Ar Drive must be part a configured drive in either the .Dq offline or .Dq failed requested states. .It Cm offline Ar drive Mark .Ar drive as offline. .Ar Drive must be a configured, online drive. .El .Pp The logical volume management commands include: .Bl -tag -width indent .It Cm name Ar volume Ar name Sets the name of .Ar volume to .Ar name . .It Cm volume cache Ar volume Ar enable|disable Enables or disables the drive write cache for the member drives of .Ar volume . .It Cm volume status Ar volume Display more detailed status about a single volume including the current progress of a rebuild operation if one is being performed. .El .Pp The configuration commands include: .Bl -tag -width indent .It Cm clear Delete the entire configuration including all volumes and spares. All drives will become standalone drives. .It Xo Cm create Ar type .Op Fl q .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Xc Create a new volume. The .Ar type specifies the type of volume to create. Currently supported types include: .Bl -tag -width indent .It Cm raid0 Creates one RAID0 volume spanning the drives listed in the single drive list. .It Cm raid1 Creates one RAID1 volume spanning the drives listed in the single drive list. .It Cm raid1e Creates one RAID1E volume spanning the drives listed in the single drive list. .El .Pp .Sy Note: Not all volume types are supported by all controllers. .Pp If the .Fl q flag is specified after .Ar type , then a .Dq quick initialization of the volume will be done. This is useful when the drives do not contain any existing data that need to be preserved. .Pp If the .Fl v flag is specified after .Ar type , then more verbose output will be enabled. Currently this just provides notification as drives are added to volumes when building the configuration. .Pp The .Fl s .Ar stripe_size parameter allows the stripe size of the array to be set. By default a stripe size of 64K is used. The list of valid values for a given .Ar type are listed in the output of .Cm show adapter . .It Cm delete Ar volume Delete the volume .Ar volume . Member drives will become standalone drives. .It Cm add Ar drive Op Ar volume Mark .Ar drive as a hot spare. .Ar Drive must not be a member of a volume. If .Ar volume is specified, then the hot spare will be dedicated to that volume. Otherwise, .Ar drive will be used as a global hot spare backing all volumes for this controller. Note that .Ar drive must be as large as the smallest drive in all of the volumes it is going to back. .It Cm remove Ar drive Remove the hot spare .Ar drive from service. It will become a standalone drive. .El .Sh EXAMPLES Mark the drive at bus 0 target 4 as offline: .Pp .Dl Nm Cm offline 0:4 .Pp Create a RAID1 array from the two standalone drives .Va da1 and .Va da2 : .Pp .Dl Nm Cm create raid1 da1,da2 .Pp Mark standalone drive .Va da3 as a global hot spare: .Pp .Dl Nm Cm add da3 .Sh SEE ALSO .Xr mpt 4 .Sh HISTORY The .Nm utility first appeared in .Fx 8.0 . .Sh BUGS .Pp The handling of spare drives appears to be unreliable. The .Xr mpt 4 firmware manages spares via spare drive .Dq pools . There are eight pools numbered 0 through 7. Each spare drive can only be assigned to a single pool. Each volume can be backed by any combination of zero or more spare pools. The .Nm utility attempts to use the following algorithm for managing spares. Global spares are always assigned to pool 0, and all volumes are always backed by pool 0. For dedicated spares, .Nm assigns one of the remaining 7 pools to each volume and assigns dedicated drives to that pool. In practice however, it seems that assigning a drive as a spare does not take effect until the box has been rebooted. Also, the firmware renumbers the spare pool assignments after a reboot which undoes the effects of the algorithm above. Simple cases such as assigning global spares seem to work ok .Pq albeit requiring a reboot to take effect but more .Dq exotic configurations may not work reliably. .Pp Drive configuration commands result in an excessive flood of messages on the console. .Pp The mpt version 1 API that is used by .Nm -and +and .Xr mpt 4 doesn't support volumes above two terabytes. This is a limitation of the API. If you are using this adapter with volumes larger than two terabytes, use the adapter in JBOD mode. Utilize .Xr geom 8 , .Xr zfs 8 , or another software volume manager to work around this limitation. Index: stable/9/usr.sbin/mptutil =================================================================== --- stable/9/usr.sbin/mptutil (revision 237215) +++ stable/9/usr.sbin/mptutil (revision 237216) Property changes on: stable/9/usr.sbin/mptutil ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/mptutil:r233648 Index: stable/9/usr.sbin/newsyslog/newsyslog.conf.5 =================================================================== --- stable/9/usr.sbin/newsyslog/newsyslog.conf.5 (revision 237215) +++ stable/9/usr.sbin/newsyslog/newsyslog.conf.5 (revision 237216) @@ -1,380 +1,380 @@ .\" This file was split from the newsyslog(8) manual page by Tom Rhodes .\" and includes modifications as appropriate. .\" The original header is included below: .\" .\" This file contains changes from the Open Software Foundation. .\" .\" from: @(#)newsyslog.8 .\" $FreeBSD$ .\" .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software .\" and its documentation for any purpose and without fee is .\" hereby granted, provided that the above copyright notice .\" appear in all copies and that both that copyright notice and .\" this permission notice appear in supporting documentation, .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be .\" used in advertising or publicity pertaining to distribution .\" of the software without specific, written prior permission. .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about .\" the suitability of this software for any purpose. It is .\" provided "as is" without express or implied warranty. .\" .Dd March 21, 2012 .Dt NEWSYSLOG.CONF 5 .Os .Sh NAME .Nm newsyslog.conf .Nd .Xr newsyslog 8 configuration file .Sh DESCRIPTION The .Nm file is used to set log file rotation configuration for the .Xr newsyslog 8 utility. Configuration may designate that logs are rotated based on size, last rotation time, or time of day. The .Nm file can also be used to designate secure permissions to log files at rotation time. During initialization, .Xr newsyslog 8 reads a configuration file, normally .Pa /etc/newsyslog.conf , to determine which logs may potentially be rotated and archived. Each line has five mandatory fields and four optional fields, separated with whitespace. Blank lines or lines beginning with .Ql # are ignored. If .Ql # is placed in the middle of the line, the .Ql # character and the rest of the line after it is ignored. To prevent special meaning, the .Ql # character may be escaped with .Ql \e ; in this case preceding .Ql \e is removed and .Ql # is treated as an ordinary character. The fields of the configuration file are as follows: .Bl -tag -width indent .It Ar logfile_name Name of the system log file to be archived, or one of the literal strings .Dq Aq Li default , or .Dq Aq Li include . The special default entry will only be used if a log file name is given as a command line argument to .Xr newsyslog 8 , and if that log file name is not matched by any other line in the configuration file. The include entry is used to include other configuration files and supports globbing. .It Ar owner : Ns Ar group This optional field specifies the owner and group for the archive file. The .Ql \&: is essential regardless if the .Ar owner or .Ar group field is left blank or contains a value. The field may be numeric, or a name which is present in .Pa /etc/passwd or .Pa /etc/group . .It Ar mode Specify the file mode of the log file and archives. .It Ar count Specify the maximum number of archive files which may exist. This does not consider the current log file. .It Ar size When the size of the log file reaches .Ar size in kilobytes, the log file will be trimmed as described above. If this field contains an asterisk .Pq Ql * , the log file will not be trimmed based on size. .It Ar when The .Ar when field may consist of an interval, a specific time, or both. If the .Ar when field contains an asterisk .Pq Ql * , log rotation will solely depend on the contents of the .Ar size field. Otherwise, the .Ar when field consists of an optional interval in hours, usually followed by an .So Li \&@ Sc Ns No -sign and a time in restricted .Tn ISO 8601 format. Additionally, the format may also be constructed with a .Ql $ sign along with a rotation time specification of once a day, once a week, or once a month. .Pp Time based trimming happens only if .Xr newsyslog 8 is run within one hour of the specified time. If an interval is specified, the log file will be trimmed if that many hours have passed since the last rotation. When both a time and an interval are specified then both conditions must be satisfied for the rotation to take place. .Pp There is no provision for the specification of a timezone. There is little point in specifying an explicit minutes or seconds component in the current implementation, since the only comparison is .Dq within the hour . .Pp .Sy ISO 8601 restricted time format : .Pp The lead-in character for a restricted .Tn ISO 8601 time is an .Ql @ sign. The particular format of the time in restricted .Tn ISO 8601 is: .Sm off .Oo .Op Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd .Oo .Li T .Op Va hh Oo Va mm Oo Va ss Oc Oc Oc .Oc . .Sm on Optional date fields default to the appropriate component of the current date; optional time fields default to midnight; hence if today is January 22, 1999, the following date specifications are all equivalent: .Pp .Bl -item -compact -offset indent .It .Sq Li 19990122T000000 .It .Sq Li 990122T000000 .It .Sq Li 0122T000000 .It .Sq Li 22T000000 .It .Sq Li T000000 .It .Sq Li T0000 .It .Sq Li T00 .It .Sq Li 22T .It .Sq Li T .It .Sq Li \& .El .Pp .Sy Day, week, and month time format: .Pp The lead-in character for day, week, and month specification is a .Ql $ sign. The particular format of day, week, and month specification is: .Op Li D Ns Va hh , .Op Li W Ns Va w Ns Op Li D Ns Va hh , and .Op Li M Ns Va dd Ns Op Li D Ns Va hh , respectively. Optional time fields default to midnight. The ranges for day and hour specifications are: .Pp .Bl -tag -width indent -offset indent -compact .It Ar hh hours, range 0..23 .It Ar w day of week, range 0..6, 0 = Sunday .It Ar dd day of month, range 1..31, or one of the letters .Ql L or .Ql l to specify the last day of the month. .El .Pp Some examples: .Pp .Bl -tag -width indent -offset indent -compact .It Li $D0 rotate every night at midnight (same as .Li @T00 ) .It Li $D23 rotate every day at 23:00 (same as .Li @T23 ) .It Li $W0D23 rotate every week on Sunday at 23:00 .It Li $W5D16 rotate every week on Friday at 16:00 .It Li $M1D0 rotate at the first day of every month at midnight (i.e., the start of the day; same as .Li @01T00 ) .It Li $M5D6 rotate on every 5th day of month at 6:00 (same as .Li @05T06 ) .El .It Ar flags This optional field is made up of one or more characters that specify any special processing to be done for the log files matched by this line. The following are valid flags: .Bl -tag -width indent .It Cm B indicates that the log file is a binary file, or has some special format. Usually .Xr newsyslog 8 inserts an .Tn ASCII message into a log file during rotation. This message is used to indicate when, and sometimes why the log file was rotated. If .Cm B is specified, then that informational message will not be inserted into the log file. .It Cm C indicates that the log file should be created if it does not already exist, and if the .Fl C option was also specified on the command line. .It Cm D indicates that .Xr newsyslog 8 should set the .Dv UF_NODUMP flag when creating a new version of this log file. This option would affect how the .Xr dump 8 command treats the log file when making a file system backup. .It Cm G indicates that the specified .Ar logfile_name is a shell pattern, and that .Xr newsyslog 8 should archive all filenames matching that pattern using the other options on this line. See .Xr glob 3 for details on syntax and matching rules. .It Cm J indicates that .Xr newsyslog 8 should attempt to save disk space by compressing the rotated log file using .Xr bzip2 1 . .It Cm X indicates that .Xr newsyslog 8 should attempt to save disk space by compressing the rotated log file using .Xr xz 1 . .It Cm N indicates that there is no process which needs to be signaled when this log file is rotated. .It Cm R if this flag is set the .Xr newsyslog 8 -will run shell command defined in +will run shell command defined in .Ar path_to_pid_cmd_file after rotation instead of trying to send signal to a process id stored in the file. .It Cm U indicates that the file specified by .Ar path_to_pid_cmd_file will contain the ID for a process group instead of a process. This option also requires that the first line in that file be a negative value to distinguish it from a process ID. .It Cm Z indicates that .Xr newsyslog 8 should attempt to save disk space by compressing the rotated log file using .Xr gzip 1 . .It Fl a minus sign will not cause any special processing, but it can be used as a placeholder to create a .Ar flags field when you need to specify any of the following fields. .El .It Ar path_to_pid_cmd_file This optional field specifies the file name containing a daemon's process ID or to find a group process ID if the .Cm U flag was specified. If this field is present, a .Ar signal_number is sent to the process ID contained in this file. If this field is not present and the .Cm N flag has not been specified, then a .Dv SIGHUP signal will be sent to .Xr syslogd 8 or to the process id found in the file specified by .Xr newsyslog 8 Ns 's .Fl S switch. This field must start with .Ql / in order to be recognized properly. When used with the .Cm R flag, the file is treated as a path to a binary to be executed by the .Xr newsyslog 8 after rotation instead of sending the signal out. .It Ar signal_number This optional field specifies the signal number that will be sent to the daemon process (or to all processes in a process group, if the .Cm U flag was specified). If this field is not present, then a .Dv SIGHUP signal will be sent. .El .Sh EXAMPLES The following is an example of the .Dq Aq Li include entry: .Dl " /etc/newsyslog-local.conf" .Sh SEE ALSO .Xr bzip2 1 , .Xr gzip 1 , .Xr xz 1 , .Xr syslog 3 , .Xr chown 8 , .Xr newsyslog 8 , .Xr syslogd 8 .Sh HISTORY This manual page first appeared in .Fx 4.10 . Index: stable/9/usr.sbin/newsyslog =================================================================== --- stable/9/usr.sbin/newsyslog (revision 237215) +++ stable/9/usr.sbin/newsyslog (revision 237216) Property changes on: stable/9/usr.sbin/newsyslog ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/newsyslog:r233648 Index: stable/9/usr.sbin/pciconf/pciconf.8 =================================================================== --- stable/9/usr.sbin/pciconf/pciconf.8 (revision 237215) +++ stable/9/usr.sbin/pciconf/pciconf.8 (revision 237216) @@ -1,283 +1,283 @@ .\" Copyright (c) 1997 .\" Stefan Esser . 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. .\" .\" $FreeBSD$ .\" .Dd November 7, 2007 .Dt PCICONF 8 .Os .Sh NAME .Nm pciconf .Nd diagnostic utility for the PCI bus .Sh SYNOPSIS .Nm .Fl l Op Fl bcv .Nm .Fl a Ar selector .Nm .Fl r Oo Fl b | h Oc Ar selector addr Ns Op : Ns Ar addr2 .Nm .Fl w Oo Fl b | h Oc Ar selector addr value .Sh DESCRIPTION The .Nm utility provides a command line interface to functionality provided by the .Xr pci 4 .Xr ioctl 2 interface. As such, some of the functions are only available to users with write access to .Pa /dev/pci , normally only the super-user. .Pp With the .Fl l option, it lists all devices found by the boot probe in the following format: .Bd -literal foo0@pci0:0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 \ hdr=0x00 bar0@pci0:0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 \ hdr=0x00 none0@pci0:0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 \ hdr=0x00 .Ed .Pp The first column gives the device name, unit number, and .Ar selector . If there is no device configured in the kernel for the .Tn PCI device in question, the device name will be .Dq none . Unit numbers for unconfigured devices start at zero and are incremented for each unconfigured device that is encountered. The .Ar selector is in a form which may directly be used for the other forms of the command. The second column is the class code, with the class byte printed as two hex digits, followed by the sub-class and the interface bytes. The third column gives the contents of the subvendorid register, introduced in revision 2.1 of the .Tn PCI standard. Note that it will be 0 for older cards. The field consists of the card ID in the upper half and the card vendor ID in the lower half of the value. .Pp The fourth column contains the chip device ID, which identifies the chip this card is based on. It consists of two fields, identifying the chip and its vendor, as above. The fifth column prints the chip's revision. The sixth column describes the header type. Currently assigned header types include 0 for most devices, 1 for .Tn PCI to .Tn PCI bridges, and 2 for .Tn PCI to .Tn CardBus bridges. If the most significant bit of the header type register is set for function 0 of a .Tn PCI device, it is a .Em multi-function device, which contains several (similar or independent) functions on one chip. .Pp If the .Fl b option is supplied, .Nm will list any base address registers .Pq BARs that are assigned resources for each device. Each BAR will be enumerated via a line in the following format: .Bd -literal bar [10] = type Memory, range 32, base 0xda060000, size 131072, enabled .Ed .Pp The first value after the .Dq Li bar prefix in the square brackets is the offset of the BAR in config space in hexadecimal. The type of a BAR is one of .Dq Memory , .Dq Prefetchable Memory , or .Dq I/O Port . The range indicates the maximum address the BAR decodes. The base and size indicate the start and length of the BAR's address window, respectively. Finally, the last flag indicates if the BAR is enabled or disabled. .Pp If the .Fl c option is supplied, .Nm will list any capabilities supported by each device. Each capability is enumerated via a line in the following format: .Bd -literal cap 10[40] = PCI-Express 1 root port .Ed .Pp The first value after the .Dq Li cap prefix is the capability ID in hexadecimal. The second value in the square brackets is the offset of the capability in config space in hexadecimal. The format of the text after the equals sign is capability-specific. .Pp Each extended capability is enumerated via a line in a similar format: .Bd -literal ecap 0002[100] = VC 1 max VC0 .Ed .Pp The first value after the .Dq Li ecap prefix is the extended capability ID in hexadecimal. The second value in the square brackets is the offset of the extended capability in config space in hexadecimal. The format of the text after the equals sign is capability-specific. .Pp If the .Fl v option is supplied, .Nm will attempt to load the vendor/device information database, and print vendor, device, class and subclass identification strings for each device. .Pp All invocations of .Nm except for .Fl l require a .Ar selector of the form .Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \ Ns Va function Ns , .Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns , or .Li pci Ns Va bus Ns \&: Ns Va device Ns . In case of an abridged form, omitted selector components are assumed to be 0. -An optional leading device name followed by @ and an optional final colon +An optional leading device name followed by @ and an optional final colon will be ignored; this is so that the first column in the output of .Nm .Fl l can be used without modification. All numbers are base 10. .Pp With the .Fl a flag, .Nm determines whether any driver has been assigned to the device identified by .Ar selector . An exit status of zero indicates that the device has a driver; non-zero indicates that it does not. .Pp The .Fl r option reads a configuration space register at byte offset .Ar addr of device .Ar selector and prints out its value in hexadecimal. The optional second address .Ar addr2 specifies a range to read. The .Fl w option writes the .Ar value into a configuration space register at byte offset .Ar addr of device .Ar selector . For both operations, the flags .Fl b and .Fl h select the width of the operation; .Fl b indicates a byte operation, and .Fl h indicates a halfword (two-byte) operation. The default is to read or write a longword (four bytes). .Sh ENVIRONMENT The PCI vendor/device information database is normally read from .Pa /usr/share/misc/pci_vendors . This path can be overridden by setting the environment variable .Ev PCICONF_VENDOR_DATABASE . .Sh SEE ALSO .Xr ioctl 2 , .\" .Xr pci 4 , .Xr devinfo 8 , .Xr kldload 8 .Sh HISTORY The .Nm utility appeared first in .Fx 2.2 . The .Fl a option was added for .Tn PCI KLD support in .Fx 3.0 . .Sh AUTHORS .An -nosplit The .Nm utility was written by .An Stefan Esser and .An Garrett Wollman . .Sh BUGS The .Fl b and .Fl h options are implemented in .Nm , but not in the underlying .Xr ioctl 2 . .Pp It might be useful to give non-root users access to the .Fl a and .Fl r options. But only root will be able to execute a .Nm kldload to provide the device with a driver KLD, and reading of configuration space registers may cause a failure in badly designed .Tn PCI chips. Index: stable/9/usr.sbin/pciconf =================================================================== --- stable/9/usr.sbin/pciconf (revision 237215) +++ stable/9/usr.sbin/pciconf (revision 237216) Property changes on: stable/9/usr.sbin/pciconf ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/head_mfi/usr.sbin/pciconf:r233621 Merged /head/usr.sbin/pciconf:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /vendor/resolver/dist/usr.sbin/pciconf:r1540-186085 Merged /projects/largeSMP/usr.sbin/pciconf:r221273-222812,222815-223757 Merged /projects/quota64/usr.sbin/pciconf:r184125-207707 Index: stable/9/usr.sbin/pkg_install/updating/pkg_updating.1 =================================================================== --- stable/9/usr.sbin/pkg_install/updating/pkg_updating.1 (revision 237215) +++ stable/9/usr.sbin/pkg_install/updating/pkg_updating.1 (revision 237216) @@ -1,90 +1,90 @@ .\" -.\" FreeBSD updating - Scan the installed ports and show all UPDATING entries -.\" that affect one of the installed ports. Alternative a list of portnames +.\" FreeBSD updating - Scan the installed ports and show all UPDATING entries +.\" that affect one of the installed ports. Alternative a list of portnames .\" could be passed to pkg_updating .\" .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Beat Gätzi .\" .\" $FreeBSD$ .\" .Dd May 30, 2008 .Dt PKG_UPDATING 1 .Os .Sh NAME .Nm pkg_updating .Nd a utility for displaying UPDATING entries of software packages .Sh SYNOPSIS .Nm .Op Fl h .Op Fl d Ar date .Op Fl f Ar file .Op Ar pkg-name ... .Nm .Sh DESCRIPTION The .Nm command scans the installed ports and show all UPDATING entries that affect one of the installed ports. Alternative a list of pkg-names could be passed. .Sh OPTIONS The following command line options are supported: .Bl -tag -width indent .It Ar pkg-name ... UPDATING entries for the named packages are displayed. .It Fl d , -date Ar date Only entries newer than .Ar date are shown. Use a YYYYMMDD date format. -.It Fl f , -file Ar file +.It Fl f , -file Ar file Defines a alternative location of the UPDATING .Ar file . .It Fl h , -help Print help message. .El .Sh ENVIRONMENT .Bl -tag -width PKG_DBDIR .It Ev PKG_DBDIR Specifies an alternative location for the installed package database. .It Ev PORTSDIR Location of the ports tree. .El .Sh FILES .Bl -tag -width /var/db/pkg -compact .It Pa /var/db/pkg Default location of the installed package database. .It Pa /usr/ports The default ports directory and default location of the UPDATING file. .El .Sh EXAMPLES Shows all entries of all installed ports: .Dl % pkg_updating .Pp Shows all entries of all installed ports since 2007-01-01: .Dl % pkg_updating -d 20070101 .Pp Shows all entries for all apache and mysql ports: .Dl % pkg_updating apache mysql .Pp Shows all apache entries since 2006-01-01: .Dl % pkg_updating -d 20060101 apache .Pp Defines that the UPDATING file is in /tmp and shows all entries of all installed ports: .Dl % pkg_updating -f /tmp/UPDATING .Pp Fetch UPDATING file from ftp mirror and show all entries of all installed ports: .Dl % pkg_updating -f ftp://ftp.freebsd.org/pub/FreeBSD/ports/packages/UPDATING .Sh SEE ALSO .Xr pkg_add 1 , .Xr pkg_create 1 , .Xr pkg_delete 1 , .Xr pkg_version 1 .Sh AUTHORS .An Beat G\(:atzi Aq beat@chruetertee.ch .Sh CONTRIBUTORS .An Martin Tournoij Aq carpetsmoker@xs4all.nl .Sh BUGS Sure to be some. Index: stable/9/usr.sbin/pkg_install/updating =================================================================== --- stable/9/usr.sbin/pkg_install/updating (revision 237215) +++ stable/9/usr.sbin/pkg_install/updating (revision 237216) Property changes on: stable/9/usr.sbin/pkg_install/updating ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/pkg_install/updating:r233648 Index: stable/9/usr.sbin/rtadvd/rtadvd.8 =================================================================== --- stable/9/usr.sbin/rtadvd/rtadvd.8 (revision 237215) +++ stable/9/usr.sbin/rtadvd/rtadvd.8 (revision 237216) @@ -1,230 +1,230 @@ .\" $KAME: rtadvd.8,v 1.24 2002/05/31 16:16:08 jinmei Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. .\" 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 project 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 PROJECT 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 PROJECT 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 July 14, 2011 .Dt RTADVD 8 .Os .Sh NAME .Nm rtadvd .Nd router advertisement daemon .Sh SYNOPSIS .Nm .Op Fl dDfRs .Op Fl c Ar configfile .Op Fl M Ar ifname .Op Fl p Ar pidfile .Ar interface ... .Sh DESCRIPTION .Nm sends router advertisement packets to the specified .Ar interfaces . .Pp The program will daemonize itself on invocation. It will then send router advertisement packets periodically, as well as in response to router solicitation messages sent by end hosts. .Pp Router advertisements can be configured on a per-interface basis, as described in .Xr rtadvd.conf 5 . .Pp If there is no configuration file entry for an interface, or if the configuration file does not exist altogether, .Nm sets all the parameters to their default values. In particular, .Nm reads all the interface routes from the routing table and advertises them as on-link prefixes. .Pp .Nm also watches the routing table. If an interface direct route is added on an advertising interface and no static prefixes are specified by the configuration file, .Nm adds the corresponding prefix to its advertising list. .Pp Similarly, when an interface direct route is deleted, .Nm will start advertising the prefixes with zero valid and preferred lifetimes to help the receiving hosts switch to a new prefix when renumbering. Note, however, that the zero valid lifetime cannot invalidate the autoconfigured addresses at a receiving host immediately. According to the specification, the host will retain the address for a certain period, which will typically be two hours. The zero lifetimes rather intend to make the address deprecated, indicating that a new non-deprecated address should be used as the source address of a new connection. This behavior will last for two hours. Then .Nm will completely remove the prefix from the advertising list, and succeeding advertisements will not contain the prefix information. .Pp Moreover, if the status of an advertising interface changes, .Nm will start or stop sending router advertisements according to the latest status. .Pp The .Fl s option may be used to disable this behavior; .Nm will not watch the routing table and the whole functionality described above will be suppressed. .Pp Basically, hosts MUST NOT send Router Advertisement messages at any time (RFC 4861, Section 6.2.3). However, it would sometimes be useful to allow hosts to advertise some parameters such as prefix information and link MTU. Thus, .Nm can be invoked if router lifetime is explicitly set zero on every advertising interface. .Pp The command line options are: .Bl -tag -width indent .\" .It Fl c Specify an alternate location, .Ar configfile , for the configuration file. By default, .Pa /etc/rtadvd.conf is used. .It Fl d Print debugging information. .It Fl D Even more debugging information is printed. .It Fl f Foreground mode (useful when debugging). Log messages will be dumped to stderr when this option is specified. .It Fl M Specify an interface to join the all-routers site-local multicast group. By default, .Nm tries to join the first advertising interface appearing on the command line. This option has meaning only with the .Fl R option, which enables routing renumbering protocol support. .It Fl p Specify an alternative file in which to store the process ID. The default is .Pa /var/run/rtadvd.pid. .It Fl R Accept router renumbering requests. If you enable it, certain IPsec setup is suggested for security reasons. This option is currently disabled, and is ignored by .Nm with a warning message. .It Fl s Do not add or delete prefixes dynamically. Only statically configured prefixes, if any, will be advertised. .El .Pp Use .Dv SIGHUP to reload the configuration file .Pa /etc/rtadvd.conf . If an invalid parameter is found in the configuration file upon the reload, the entry will be ignored and the old configuration will be used. -When parameters in an existing entry are updated, +When parameters in an existing entry are updated, .Nm will send Router Advertisement messages with the old configuration but zero router lifetime to the interface first, and then start to send a new message. .Pp Use .Dv SIGTERM to kill .Nm gracefully. In this case, .Nm will transmit router advertisement with router lifetime 0 to all the interfaces .Pq in accordance with RFC 4861 6.2.5 . .Sh FILES .Bl -tag -width Pa -compact .It Pa /etc/rtadvd.conf The default configuration file. .It Pa /var/run/rtadvd.pid The default process ID file. .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr rtadvd.conf 5 , .Xr rtsol 8 .Rs .%A Thomas Narten .%A Erik Nordmark .%A W. A. Simpson .%A Hesham Soliman .%T Neighbor Discovery for IP version 6 (IPv6) .%R RFC 4861 .Re .Rs .%A Thomas Narten .%A Erik Nordmark .%A W. A. Simpson .%T Neighbor Discovery for IP version 6 (IPv6) .%R RFC 2461 (obsoleted by RFC 4861) .Re .Rs .%A Richard Draves .%T Default Router Preferences and More-Specific Routes .%R draft-ietf-ipngwg-router-selection-xx.txt .Re .Rs .%A J. Jeong .%A S. Park .%A L. Beloeil .%A S. Madanapalli .%T IPv6 Router Advertisement Options for DNS Configuration .%R RFC 6106 .Re .Sh HISTORY The .Nm command first appeared in the WIDE Hydrangea IPv6 protocol stack kit. .Sh BUGS There used to be some text that recommended users not to let .Nm advertise Router Advertisement messages on an upstream link to avoid undesirable .Xr icmp6 4 redirect messages. However, based on the later discussion in the IETF ipng working group, all routers should rather advertise the messages regardless of the network topology, in order to ensure reachability. Index: stable/9/usr.sbin/rtadvd =================================================================== --- stable/9/usr.sbin/rtadvd (revision 237215) +++ stable/9/usr.sbin/rtadvd (revision 237216) Property changes on: stable/9/usr.sbin/rtadvd ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head/usr.sbin/rtadvd:r233648 Index: stable/9/usr.sbin/setfib/setfib.1 =================================================================== --- stable/9/usr.sbin/setfib/setfib.1 (revision 237215) +++ stable/9/usr.sbin/setfib/setfib.1 (revision 237216) @@ -1,97 +1,97 @@ .\" Copyright (c) 2008 Cisco systems .\" Author Julian Elischer. 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. 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 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 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. .\" .\" $FreeBSD$ .\" .Dd April 9, 2008 .Dt SETFIB 1 .Os .Sh NAME .Nm setfib .Nd execute a utility with an altered default network view .Sh SYNOPSIS .Nm -.Op Fl F +.Op Fl F .Ar fib .Ar utility .Op Ar argument ... .Sh DESCRIPTION The .Nm utility runs .Ar utility with an different routing table. The table number .Dq Ar fib will be used by default for all sockets started by this process or descendents. .Sh ENVIRONMENT The .Ev PATH environment variable is used to locate the requested .Ar utility if the name contains no .Ql / characters. .Sh EXIT STATUS If .Ar utility is invoked, the exit status of .Nm is the exit status of .Ar utility . .Pp An exit status of 126 indicates .Ar utility was found, but could not be executed. An exit status of 127 indicates .Ar utility could not be found. .Sh EXAMPLES Execute utility .Sq netstat to view the second routing table. .Pp .Dl "setfib -F 1 netstat -rn" or .Dl "setfib 1 netstat -rn" or .Dl "setfib -1 netstat -rn" .Sh SEE ALSO .Xr setfib 2 , .Xr setsockopt 2 .Sh STANDARDS The .Nm utility is a .Fx specific extension, however many .Ux like systems have an equivalent function. .Sh HISTORY The .Nm utility appeared in .Fx 7.1 . Index: stable/9/usr.sbin/setfib =================================================================== --- stable/9/usr.sbin/setfib (revision 237215) +++ stable/9/usr.sbin/setfib (revision 237216) Property changes on: stable/9/usr.sbin/setfib ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /projects/quota64/usr.sbin/setfib:r184125-207707 Merged /projects/head_mfi/usr.sbin/setfib:r233621 Merged /head/usr.sbin/setfib:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /vendor/resolver/dist/usr.sbin/setfib:r1540-186085 Merged /projects/largeSMP/usr.sbin/setfib:r221273-222812,222815-223757 Index: stable/9/usr.sbin/timed/timed/timed.8 =================================================================== --- stable/9/usr.sbin/timed/timed/timed.8 (revision 237215) +++ stable/9/usr.sbin/timed/timed/timed.8 (revision 237216) @@ -1,288 +1,288 @@ .\" 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. .\" 4. 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. .\" .\" @(#)timed.8 8.1 (Berkeley) 6/6/93 .\" $FreeBSD$ .\" .Dd February 11, 2008 .Dt TIMED 8 .Os .Sh NAME .Nm timed .Nd time server daemon .Sh SYNOPSIS .Nm .Op Fl dtM .Op Fl i Ar network | Fl n Ar network .Op Fl F Ar host ... .Sh DESCRIPTION The .Nm utility is a time server daemon which is normally invoked at boot time from the .Xr rc.network 8 file. It synchronizes the host's time with the time of other machines, which are also running .Nm , in a local area network. These time servers will slow down the clocks of some machines and speed up the clocks of others to bring them to the average network time. The average network time is computed from measurements of clock differences using the .Tn ICMP timestamp request message. .Pp The following options are available: .Bl -tag -width indent .It Fl d Enable debugging mode; do not detach from the terminal. .It Fl i Ar network Add .Ar network to the list of networks to ignore. All other networks to which the machine is directly connected are used by .Nm . This option may be specified multiple times to add more than one network to the list. .It Fl F Ar host ... .Bl -dash -compact .It Create a list of trusted hosts. .It Can take one or more parameters. .It .Nm will only accept trusted hosts as masters. If it finds an untrusted host claiming to be master, .Nm will suppress incoming messages from that host and call for a new election. .It -Use real host names (resolvable by RDNS) not aliases (eg in +Use real host names (resolvable by RDNS) not aliases (eg in .Xr named 8 parlance: use A names, not C names). .It Use full names eg time1.domain.com not time1. .It .Fl F -automatically includes the functionality of +automatically includes the functionality of .Fl M (so .Fl M does not need to asserted). .It -If +If .Fl F is not specified, all hosts on connected networks are treated as trustworthy. .El .It Fl M Allow this host to become a .Nm master if necessary. .It Fl n Ar network Add .Ar network to the list of allowed networks. All other networks to which the machine is directly connected are ignored by .Nm . This option may be specified multiple times to add more than one network to the list. .It Fl t Enable tracing of received messages and log to the file .Pa /var/log/timed.log . Tracing can be turned on or off while .Nm is running with the .Xr timedc 8 utility. .El .Pp The .Fl n and .Fl i flags are mutually exclusive and require as arguments real networks to which the host is connected (see .Xr networks 5 ) . If neither flag is specified, .Nm will listen on all connected networks. .Pp A .Nm running without the .Fl M nor .Fl F flags will always remain a slave. If the .Fl F flag is not used, .Nm will treat all machines as trustworthy. .Pp The .Nm utility is based on a master-slave scheme. When .Nm is started on a machine, it asks the master for the network time and sets the host's clock to that time. After that, it accepts synchronization messages periodically sent by the master and calls .Xr adjtime 2 to perform the needed corrections on the host's clock. .Pp It also communicates with .Xr date 1 in order to set the date globally, and with .Xr timedc 8 , a .Nm control utility. If the machine running the master becomes unreachable, the slaves will elect a new master from among those slaves which are running with at least one of the .Fl M and .Fl F flags. .Pp At startup .Nm normally checks for a master time server on each network to which it is connected, except as modified by the .Fl n and .Fl i options described above. It will request synchronization service from the first master server located. If permitted by the .Fl M or .Fl F flags, it will provide synchronization service on any attached networks on which no trusted master server was detected. Such a server propagates the time computed by the top-level master. The .Nm utility will periodically check for the presence of a master on those networks for which it is operating as a slave. If it finds that there are no trusted masters on a network, it will begin the election process on that network. .Pp One way to synchronize a group of machines is to use .Xr ntpd 8 to synchronize the clock of one machine to a distant standard or a radio receiver and .Fl F Ar hostname to tell its .Nm to trust only itself. .Pp Messages printed by the kernel on the system console occur with interrupts disabled. This means that the clock stops while they are printing. A machine with many disk or network hardware problems and consequent messages cannot keep good time by itself. Each message typically causes the clock to lose a dozen milliseconds. A time daemon can correct the result. .Pp Messages in the system log about machines that failed to respond usually indicate machines that crashed or were turned off. Complaints about machines that failed to respond to initial time settings are often associated with .Dq multi-homed machines that looked for time masters on more than one network and eventually chose to become a slave on the other network. .Sh WARNINGS Temporal chaos will result if two or more time daemons attempt to adjust the same clock. If both .Nm and another time daemon are run on the same machine, ensure that the .Fl F flag is used, so that .Nm never attempts to adjust the local clock. .Pp The protocol is based on .Tn UDP/IP broadcasts. All machines within the range of a broadcast that are using the .Tn TSP protocol must cooperate. There cannot be more than a single administrative domain using the .Fl F flag among all machines reached by a broadcast packet. Failure to follow this rule is usually indicated by complaints concerning .Dq untrusted machines in the system log. .Sh FILES .Bl -tag -width /var/log/timed.masterlog -compact .It Pa /var/log/timed.log tracing file for .Nm .It Pa /var/log/timed.masterlog log file for master .Nm .El .Sh SEE ALSO .Xr date 1 , .Xr adjtime 2 , .Xr gettimeofday 2 , .Xr icmp 4 , .Xr networks 5 , .Xr ntpd 8 , .Xr timedc 8 .Rs .%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" .%A R. Gusella .%A S. Zatti .Re .Sh HISTORY The .Nm utility appeared in .Bx 4.3 . Index: stable/9/usr.sbin/timed/timed =================================================================== --- stable/9/usr.sbin/timed/timed (revision 237215) +++ stable/9/usr.sbin/timed/timed (revision 237216) Property changes on: stable/9/usr.sbin/timed/timed ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,4 ## Merged /head/usr.sbin/timed/timed:r226702,227006,228714,228719-228720,229067,233648 Merged /projects/largeSMP/usr.sbin/timed/timed:r221273-222812,222815-223757 Merged /vendor/resolver/dist/usr.sbin/timed/timed:r1540-186085 Merged /projects/quota64/usr.sbin/timed/timed:r184125-207707 Index: stable/9/usr.sbin/wlandebug/wlandebug.8 =================================================================== --- stable/9/usr.sbin/wlandebug/wlandebug.8 (revision 237215) +++ stable/9/usr.sbin/wlandebug/wlandebug.8 (revision 237216) @@ -1,177 +1,177 @@ .\" Copyright (c) 2007 Sam Leffler, Errno Consulting .\" 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. .\" .\" $FreeBSD$ .\" .Dd July 17, 2009 .Dt WLANDEBUG 8 .Os .Sh NAME .Nm wlandebug .Nd "set/query 802.11 wireless debugging messages" .Sh SYNOPSIS .Nm .Op Fl d | Fl i Ar ifnet .Op Fl flag|+flag Ar ... .Sh DESCRIPTION The .Nm command is a tool for enabling and disabling debugging messages in the .Xr wlan 4 module. Running .Nm without any options will display the current messages enabled for the specified network interface (by default, ``ath0'). The default debugging level for new interfaces can be set by specifying the .Fl d option. When run as the super-user .Nm can be used to enable and/or disable debugging messages. .Pp To enable debugging messages of a certain .Ar type use .Ar +type ; to disable such messages use .Ar -type . Multiple messages can be enabled and disabled with a single command. .Pp Messages are organized in the following groups: .Bl -tag -width ".Ar dumppkts" .It Ar debug general debugging facilities; equivalent to setting the debug parameter with .Xr ifconfig 8 . .It Ar dumppkts dump packet contents on transmit and receive. .It Ar crypto crypto-related work. .It Ar input errors encountered during input handling. .It Ar xrate extended rate set handling (for 802.11g). .It Ar elemid information element processing in 802.11 management frames. .It Ar node management of per-station state. .It Ar assoc 802.11 station association processing; particularly useful to see when stations join and leave a BSS. .It Ar auth 802.11 station authentication processing. .It Ar scan scanning operation; especially useful for debugging problems with not locating an access point. .It Ar output errors encountered during output handling. .It Ar state .Xr wlan 4 state machine operation. .It Ar power 802.11 power save operation; in hostap mode this enables copious information about buffered frames for stations operating in power save mode. .It Ar hwmp trace operation of Hybrid Wireless Mesh Protocol processing. .It Ar dot1xsm 802.1x state machine operation; not presently meaningful as 802.1x protocol support is implemented in user mode by the .Xr hostapd 8 program. .It Ar radius radius backend operation as it relates to 802.1x operation; not presently meaningful as 802.1x protocol support is implemented in user mode by the .Xr hostapd 8 program. .It Ar raddump dump packets exchanged with the radius backend for 802.1x operation; not presently meaningful as 802.1x protocol support is implemented in user mode by the .Xr hostapd 8 program. .It Ar mesh trace operation of 802.11s mesh protocol processing. .It Ar wpa -trace operation of the WPA protocol; +trace operation of the WPA protocol; only partly meaningful as WPA protocol support is mostly implemented in user mode by the .Xr hostapd 8 and .Xr wpa_supplicant 8 programs. .It Ar acl trace operation of the Access Control List (ACL) support; see .Xr wlan_acl 4 for more details. .It Ar wme trace operation of WME/WMM protocol processing. .It Ar superg trace operation of Atheros SuperG protocol processing. .It Ar doth trace operation of IEEE 802.11h protocol processing. .It Ar inact trace station inactivity processing; in particular, show when stations associated to an access point are dropped due to inactivity. .It Ar roam trace station mode roaming between access points. .It Ar rate trace transmit rate control operation. .El .Sh EXAMPLES The following might be used to debug basic station mode operation: .Pp .Dl "wlandebug -i ral0 scan+auth+assoc" .Pp it enables debug messages while scanning, authenticating to an access point, and associating to an access point. .Sh SEE ALSO .Xr ifconfig 8 , .Xr wlanstats 8 , .Xr athdebug 8 , .Xr athstats 8 . .Sh NOTES Different wireless drivers support different debugging messages. Drivers such as .Xr ath 4 and .Xr ral 4 that depend on the .Xr wlan 4 module for 802.11 protocol processing typically support most of the debugging messages while devices that implement parts of the 802.11 protocol in firmware do not. .Pp Some debugging messages are no longer meaningful because protocol processing has moved from the operating system to user mode programs such as .Xr hostapd 8 and .Xr wpa_supplicant 8 . Index: stable/9/usr.sbin/wlandebug =================================================================== --- stable/9/usr.sbin/wlandebug (revision 237215) +++ stable/9/usr.sbin/wlandebug (revision 237216) Property changes on: stable/9/usr.sbin/wlandebug ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,5 ## Merged /vendor/resolver/dist/usr.sbin/wlandebug:r1540-186085 Merged /projects/quota64/usr.sbin/wlandebug:r184125-207707 Merged /projects/largeSMP/usr.sbin/wlandebug:r221273-222812,222815-223757 Merged /head/usr.sbin/wlandebug:r226702,226785,227006,228761,229067,229997,230127,230587,233648,233713,234313,234315,234322,234351,234870,235726 Merged /projects/head_mfi/usr.sbin/wlandebug:r233621