Index: head/bin/dd/dd.1 =================================================================== --- head/bin/dd/dd.1 (revision 81621) +++ head/bin/dd/dd.1 (revision 81622) @@ -1,371 +1,375 @@ .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Keith Muller of the University of California, San Diego. .\" .\" 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. .\" .\" @(#)dd.1 8.2 (Berkeley) 1/13/94 .\" $FreeBSD$ .\" .Dd January 13, 1994 .Dt DD 1 .Os .Sh NAME .Nm dd .Nd convert and copy a file .Sh SYNOPSIS .Nm .Op operands ... .Sh DESCRIPTION The .Nm utility copies the standard input to the standard output. Input data is read and written in 512-byte blocks. If input reads are short, input from multiple reads are aggregated to form the output block. When finished, .Nm displays the number of complete and partial input and output blocks and truncated input records to the standard error output. .Pp The following operands are available: .Bl -tag -width of=file .It Cm bs= Ns Ar n Set both input and output block size to .Va n bytes, superseding the .Cm ibs and .Cm obs operands. If no conversion values other than .Cm noerror , .Cm notrunc or .Cm sync are specified, then each input block is copied to the output as a single block without any aggregation of short blocks. .It Cm cbs= Ns Ar n Set the conversion record size to .Va n bytes. The conversion record size is required by the record oriented conversion values. .It Cm count= Ns Ar n Copy only .Va n input blocks. .It Cm files= Ns Ar n Copy .Va n input files before terminating. This operand is only applicable when the input device is a tape. .It Cm ibs= Ns Ar n Set the input block size to .Va n bytes instead of the default 512. .It Cm if= Ns Ar file Read input from .Ar file instead of the standard input. .It Cm iseek= Ns Ar n Seek on the input file .Va n blocks. This is synonymous with .Cm skip= Ns Ar n . .It Cm obs= Ns Ar n Set the output block size to .Va n bytes instead of the default 512. .It Cm of= Ns Ar file Write output to .Ar file instead of the standard output. Any regular output file is truncated unless the .Cm notrunc conversion value is specified. If an initial portion of the output file is seeked past (see the .Cm oseek operand), the output file is truncated at that point. .It Cm oseek= Ns Ar n Seek on the output file .Va n blocks. This is synonymous with .Cm seek= Ns Ar n . .It Cm seek= Ns Ar n Seek .Va n blocks from the beginning of the output before copying. On non-tape devices, an .Xr lseek 2 operation is used. Otherwise, existing blocks are read and the data discarded. If the user does not have read permission for the tape, it is positioned using the tape .Xr ioctl 2 function calls. If the seek operation is past the end of file, space from the current end of file to the specified offset is filled with blocks of .Tn NUL bytes. .It Cm skip= Ns Ar n Skip .Va n blocks from the beginning of the input before copying. On input which supports seeks, an .Xr lseek 2 operation is used. Otherwise, input data is read and discarded. For pipes, the correct number of bytes is read. For all other devices, the correct number of blocks is read without distinguishing between a partial or complete block being read. .It Xo .Cm conv= .Ns Cm value Ns Op \&, Cm value \&... .Xc Where .Cm value is one of the symbols from the following list. .Bl -tag -width unblock .It Cm ascii , oldascii The same as the .Cm unblock value except that characters are translated from .Tn EBCDIC to .Tn ASCII before the records are converted. (These values imply .Cm unblock if the operand .Cm cbs is also specified.) There are two conversion maps for .Tn ASCII . The value .Cm ascii specifies the recommended one which is compatible with System V. The value .Cm oldascii specifies the one used in historic .Tn AT&T -and pre-4.3BSD-reno systems. +and +.No pre- Ns Bx 4.3 reno +systems. .It Cm block Treats the input as a sequence of newline or end-of-file terminated variable length records independent of input and output block boundaries. Any trailing newline character is discarded. Each input record is converted to a fixed length output record where the length is specified by the .Cm cbs operand. Input records shorter than the conversion record size are padded with spaces. Input records longer than the conversion record size are truncated. The number of truncated input records, if any, are reported to the standard error output at the completion of the copy. .It Cm ebcdic , ibm , oldebcdic , oldibm The same as the .Cm block value except that characters are translated from .Tn ASCII to .Tn EBCDIC after the records are converted. (These values imply .Cm block if the operand .Cm cbs is also specified.) There are four conversion maps for .Tn EBCDIC . The value .Cm ebcdic specifies the recommended one which is compatible with .At V . The value .Cm ibm is a slightly different mapping, which is compatible with the .At V .Cm ibm value. The values .Cm oldebcdic and .Cm oldibm are maps used in historic .Tn AT&T -and pre-4.3BSD-reno systems. +and +.No pre- Ns Bx 4.3 reno +systems. .It Cm lcase Transform uppercase characters into lowercase characters. .It Cm noerror Do not stop processing on an input error. When an input error occurs, a diagnostic message followed by the current input and output block counts will be written to the standard error output in the same format as the standard completion message. If the .Cm sync conversion is also specified, any missing input data will be replaced with .Tn NUL bytes (or with spaces if a block oriented conversion value was specified) and processed as a normal input buffer. If the .Cm sync conversion is not specified, the input block is omitted from the output. On input files which are not tapes or pipes, the file offset will be positioned past the block in which the error occurred using .Xr lseek 2 . .It Cm notrunc Do not truncate the output file. This will preserve any blocks in the output file not explicitly written by .Nm . The .Cm notrunc value is not supported for tapes. .It Cm osync Pad the final output block to the full output block size. If the input file is not a multiple of the output block size after conversion, this conversion forces the final output block to be the same size as preceding blocks for use on devices that require regularly sized blocks to be written. This option is incompatible with use of the .Cm bs= Ns Ar n block size specification. .It Cm sparse If one or more output blocks would consist solely of .Tn NUL bytes, try to seek the output file by the required space instead of filling them with .Tn NULs , resulting in a sparse file. .It Cm swab Swap every pair of input bytes. If an input buffer has an odd number of bytes, the last byte will be ignored during swapping. .It Cm sync Pad every input block to the input buffer size. Spaces are used for pad bytes if a block oriented conversion value is specified, otherwise .Tn NUL bytes are used. .It Cm ucase Transform lowercase characters into uppercase characters. .It Cm unblock Treats the input as a sequence of fixed length records independent of input and output block boundaries. The length of the input records is specified by the .Cm cbs operand. Any trailing space characters are discarded and a newline character is appended. .El .El .Pp Where sizes are specified, a decimal, octal, or hexadecimal number of bytes is expected. If the number ends with a ``b'', ``k'', ``m'', ``g'', or ``w'', the number is multiplied by 512, 1024 (1K), 1048576 (1M), 1073741824 (1G) or the number of bytes in an integer, respectively. Two or more numbers may be separated by an ``x'' to indicate a product. .Pp When finished, .Nm displays the number of complete and partial input and output blocks, truncated input records and odd-length byte-swapping blocks to the standard error output. A partial input block is one where less than the input block size was read. A partial output block is one where less than the output block size was written. Partial output blocks to tape devices are considered fatal errors. Otherwise, the rest of the block will be written. Partial output blocks to character devices will produce a warning message. A truncated input block is one where a variable length record oriented conversion value was specified and the input line was too long to fit in the conversion record or was not newline terminated. .Pp Normally, data resulting from input or conversion or both are aggregated into output blocks of the specified size. After the end of input is reached, any remaining output is written as a block. This means that the final output block may be shorter than the output block size. .Pp If .Nm receives a .Dv SIGINFO (see the ``status'' argument for .Xr stty 1 ) signal, the current input and output block counts will be written to the standard error output in the same format as the standard completion message. If .Nm receives a .Dv SIGINT signal, the current input and output block counts will be written to the standard error output in the same format as the standard completion message and .Nm will exit. .Sh DIAGNOSTICS The .Nm utility exits 0 on success or >0 if an error occurs. .Sh SEE ALSO .Xr cp 1 , .Xr mt 1 , .Xr tr 1 .Sh STANDARDS The .Nm utility is expected to be a superset of the .St -p1003.2 standard. The .Cm files operand and the .Cm ascii , .Cm ebcdic , .Cm ibm , .Cm oldascii , .Cm oldebcdic and .Cm oldibm values are extensions to the .Tn POSIX standard. Index: head/bin/ln/symlink.7 =================================================================== --- head/bin/ln/symlink.7 (revision 81621) +++ head/bin/ln/symlink.7 (revision 81622) @@ -1,448 +1,452 @@ .\" Copyright (c) 1992, 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. .\" 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. .\" .\" @(#)symlink.7 8.3 (Berkeley) 3/31/94 .\" $FreeBSD$ .\" .Dd March 31, 1994 .Dt SYMLINK 7 .Os .Sh NAME .Nm symlink .Nd symbolic link handling .Sh SYMBOLIC LINK HANDLING Symbolic links are files that act as pointers to other files. To understand their behavior, you must first understand how hard links work. A hard link to a file is indistinguishable from the original file because it is a reference to the object underlying the original file name. Changes to a file are independent of the name used to reference the file. Hard links may not refer to directories and may not reference files on different file systems. A symbolic link contains the name of the file to which it is linked, i.e. it is a pointer to another name, and not to an underlying object. For this reason, symbolic links may reference directories and may span file systems. .Pp Because a symbolic link and its referenced object coexist in the filesystem name space, confusion can arise in distinguishing between the link itself and the referenced object. Historically, commands and system calls have adopted their own link following conventions in a somewhat ad-hoc fashion. Rules for more a uniform approach, as they are implemented in this system, are outlined here. It is important that local applications conform to these rules, too, so that the user interface can be as consistent as possible. .Pp Symbolic links are handled either by operating on the link itself, or by operating on the object referenced by the link. In the latter case, an application or system call is said to .Dq follow the link. Symbolic links may reference other symbolic links, in which case the links are dereferenced until an object that is not a symbolic link is found, a symbolic link which references a file which doesn't exist is found, or a loop is detected. (Loop detection is done by placing an upper limit on the number of links that may be followed, and an error results if this limit is exceeded.) .Pp There are three separate areas that need to be discussed. They are as follows: .Pp .Bl -enum -compact -offset indent .It Symbolic links used as file name arguments for system calls. .It Symbolic links specified as command line arguments to utilities that are not traversing a file tree. .It Symbolic links encountered by utilities that are traversing a file tree (either specified on the command line or encountered as part of the file hierarchy walk). .El .Ss System calls. The first area is symbolic links used as file name arguments for system calls. .Pp Except as noted below, all system calls follow symbolic links. For example, if there were a symbolic link .Dq Li slink which pointed to a file named .Dq Li afile , the system call .Dq Li open("slink" ...\&) would return a file descriptor to the file .Dq afile . .Pp There are six system calls that do not follow links, and which operate on the symbolic link itself. They are: .Xr lchown 2 , .Xr lstat 2 , .Xr readlink 2 , .Xr rename 2 , .Xr rmdir 2 , and .Xr unlink 2 . Because .Xr remove 3 is an alias for .Xr unlink 2 , it also does not follow symbolic links. When .Xr rmdir 2 is applied to a symbolic link, it fails with the error .Er ENOTDIR . .Pp The owner and group of an existing symbolic link can be changed by means of the .Xr lchown 2 system call. The other file attributes, such as the modification time and access permissions, are not used by the system and cannot be changed. .Pp The .Bx 4.4 -system differs from historical 4BSD systems in that the system call +system differs from historical +.Bx 4 +systems in that the system call .Xr chown 2 has been changed to follow symbolic links. The .Xr lchown 2 system call was added later when the limitations of the new .Xr chown 2 became apparent. .Ss Commands not traversing a file tree. The second area is symbolic links, specified as command line file name arguments, to commands which are not traversing a file tree. .Pp Except as noted below, commands follow symbolic links named as command line arguments. For example, if there were a symbolic link .Dq Li slink which pointed to a file named .Dq Li afile , the command .Dq Li cat slink would display the contents of the file .Dq Li afile . .Pp It is important to realize that this rule includes commands which may optionally traverse file trees, e.g. the command .Dq Li "chown file" is included in this rule, while the command .Dq Li "chown -R file" is not. (The latter is described in the third area, below.) .Pp If it is explicitly intended that the command operate on the symbolic link instead of following the symbolic link, e.g., it is desired that .Dq Li "chown slink" change the ownership of the file that .Dq Li slink is, whether it is a symbolic link or not, the .Fl h option should be used. In the above example, .Dq Li "chown root slink" would change the ownership of the file referenced by .Dq Li slink , while .Dq Li "chown -h root slink" would change the ownership of .Dq Li slink itself. .Pp There are four exceptions to this rule. The .Xr mv 1 and .Xr rm 1 commands do not follow symbolic links named as arguments, but respectively attempt to rename and delete them. (Note, if the symbolic link references a file via a relative path, moving it to another directory may very well cause it to stop working, since the path may no longer be correct.) .Pp The .Xr ls 1 command is also an exception to this rule. For compatibility with historic systems (when .Nm ls is not doing a tree walk, i.e. the .Fl R option is not specified), the .Nm ls command follows symbolic links named as arguments if the .Fl H or .Fl L option is specified, or if the .Fl F , .Fl d or .Fl l options are not specified. (The .Nm ls command is the only command where the .Fl H and .Fl L options affect its behavior even though it is not doing a walk of a file tree.) .Pp The .Xr file 1 command is also an exception to this rule. The .Xr file 1 command does not follow symbolic links named as argument by default. The .Xr file 1 command does follow symbolic links named as argument if .Fl L option is specified. .Pp The .Bx 4.4 -system differs from historical 4BSD systems in that the +system differs from historical +.Bx 4 +systems in that the .Nm chown and .Nm chgrp commands follow symbolic links specified on the command line. .Ss Commands traversing a file tree. The following commands either optionally or always traverse file trees: .Xr chflags 1 , .Xr chgrp 1 , .Xr chmod 1 , .Xr cp 1 , .Xr du 1 , .Xr find 1 , .Xr ls 1 , .Xr pax 1 , .Xr rm 1 , .Xr tar 1 and .Xr chown 8 . .Pp It is important to realize that the following rules apply equally to symbolic links encountered during the file tree traversal and symbolic links listed as command line arguments. .Pp The first rule applies to symbolic links that reference files that are not of type directory. Operations that apply to symbolic links are performed on the links themselves, but otherwise the links are ignored. .Pp For example, the command .Dq Li "chown -R user slink directory" will ignore .Dq Li slink , because symbolic links in this system do not have owners. Any symbolic links encountered during the tree traversal will also be ignored. The command .Dq Li "rm -r slink directory" will remove .Dq Li slink , as well as any symbolic links encountered in the tree traversal of .Dq Li directory , because symbolic links may be removed. In no case will either .Nm chown or .Nm rm affect the file which .Dq Li slink references in any way. .Pp The second rule applies to symbolic links that reference files of type directory. Symbolic links which reference files of type directory are never .Dq followed by default. This is often referred to as a .Dq physical walk, as opposed to a .Dq logical walk (where symbolic links referencing directories are followed). .Pp As consistently as possible, you can make commands doing a file tree walk follow any symbolic links named on the command line, regardless of the type of file they reference, by specifying the .Fl H (for .Dq half\-logical ) flag. This flag is intended to make the command line name space look like the logical name space. (Note, for commands that do not always do file tree traversals, the .Fl H flag will be ignored if the .Fl R flag is not also specified.) .Pp For example, the command .Dq Li "chown -HR user slink" will traverse the file hierarchy rooted in the file pointed to by .Dq Li slink . Note, the .Fl H is not the same as the previously discussed .Fl h flag. The .Fl H flag causes symbolic links specified on the command line to be dereferenced both for the purposes of the action to be performed and the tree walk, and it is as if the user had specified the name of the file to which the symbolic link pointed. .Pp As consistently as possible, you can make commands doing a file tree walk follow any symbolic links named on the command line, as well as any symbolic links encountered during the traversal, regardless of the type of file they reference, by specifying the .Fl L (for .Dq logical ) flag. This flag is intended to make the entire name space look like the logical name space. (Note, for commands that do not always do file tree traversals, the .Fl L flag will be ignored if the .Fl R flag is not also specified.) .Pp For example, the command .Dq Li "chown -LR user slink" will change the owner of the file referenced by .Dq Li slink . If .Dq Li slink references a directory, .Nm chown will traverse the file hierarchy rooted in the directory that it references. In addition, if any symbolic links are encountered in any file tree that .Nm chown traverses, they will be treated in the same fashion as .Dq Li slink . .Pp As consistently as possible, you can specify the default behavior by specifying the .Fl P (for .Dq physical ) flag. This flag is intended to make the entire name space look like the physical name space. .Pp For commands that do not by default do file tree traversals, the .Fl H , .Fl L and .Fl P flags are ignored if the .Fl R flag is not also specified. In addition, you may specify the .Fl H , .Fl L and .Fl P options more than once; the last one specified determines the command's behavior. This is intended to permit you to alias commands to behave one way or the other, and then override that behavior on the command line. .Pp The .Xr ls 1 and .Xr rm 1 commands have exceptions to these rules. The .Nm rm command operates on the symbolic link, and not the file it references, and therefore never follows a symbolic link. The .Nm rm command does not support the .Fl H , .Fl L or .Fl P options. .Pp To maintain compatibility with historic systems, the .Nm ls command acts a little differently. If you do not specify the .Fl F , .Fl d or .Fl l options, .Nm ls will follow symbolic links specified on the command line. If the .Fl L flag is specified, .Nm ls follows all symbolic links, regardless of their type, whether specified on the command line or encountered in the tree walk. .Sh SEE ALSO .Xr chflags 1 , .Xr chgrp 1 , .Xr chmod 1 , .Xr cp 1 , .Xr du 1 , .Xr find 1 , .Xr ln 1 , .Xr ls 1 , .Xr mv 1 , .Xr pax 1 , .Xr rm 1 , .Xr tar 1 , .Xr lchown 2 , .Xr lstat 2 , .Xr readlink 2 , .Xr rename 2 , .Xr symlink 2 , .Xr unlink 2 , .Xr fts 3 , .Xr remove 3 , .Xr chown 8 Index: head/bin/pax/pax.1 =================================================================== --- head/bin/pax/pax.1 (revision 81621) +++ head/bin/pax/pax.1 (revision 81622) @@ -1,1188 +1,1191 @@ .\" Copyright (c) 1992 Keith Muller. .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Keith Muller of the University of California, San Diego. .\" .\" 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. .\" .\" @(#)pax.1 8.4 (Berkeley) 4/18/94 .\" $FreeBSD$ .\" .Dd April 18, 1994 .Dt PAX 1 .Os .Sh NAME .Nm pax .Nd read and write file archives and copy directory hierarchies .Sh SYNOPSIS .Nm .Op Fl cdnvz .Bk -words .Op Fl f Ar archive .Ek .Bk -words .Op Fl s Ar replstr .Ar ...\& .Ek .Bk -words .Op Fl U Ar user .Ar ...\& .Ek .Bk -words .Op Fl G Ar group .Ar ...\& .Ek .Bk -words .Oo .Fl T .Op Ar from_date .Op Ar ,to_date .Oc .Ar ...\& .Ek .Op Ar pattern ...\& .Nm .Fl r .Op Fl cdiknuvzDYZ .Bk -words .Op Fl f Ar archive .Ek .Bk -words .Op Fl o Ar options .Ar ...\& .Ek .Bk -words .Op Fl p Ar string .Ar ...\& .Ek .Bk -words .Op Fl s Ar replstr .Ar ...\& .Ek .Op Fl E Ar limit .Bk -words .Op Fl U Ar user .Ar ...\& .Ek .Bk -words .Op Fl G Ar group .Ar ...\& .Ek .Bk -words .Oo .Fl T .Op Ar from_date .Op Ar ,to_date .Oc .Ar ...\& .Ek .Op Ar pattern ...\& .Nm .Fl w .Op Fl dituvzHLPX .Bk -words .Op Fl b Ar blocksize .Ek .Oo .Op Fl a .Op Fl f Ar archive .Oc .Bk -words .Op Fl x Ar format .Ek .Bk -words .Op Fl s Ar replstr .Ar ...\& .Ek .Bk -words .Op Fl o Ar options .Ar ...\& .Ek .Bk -words .Op Fl U Ar user .Ar ...\& .Ek .Bk -words .Op Fl G Ar group .Ar ...\& .Ek .Bk -words .Op Fl B Ar bytes .Ek .Bk -words .Oo .Fl T .Op Ar from_date .Op Ar ,to_date .Op Ar /[c][m] .Oc .Ar ...\& .Ek .Op Ar .Nm .Fl r .Fl w .Op Fl diklntuvDHLPXYZ .Bk -words .Op Fl p Ar string .Ar ...\& .Ek .Bk -words .Op Fl s Ar replstr .Ar ...\& .Ek .Bk -words .Op Fl U Ar user .Ar ...\& .Ek .Bk -words .Op Fl G Ar group .Ar ...\& .Ek .Bk -words .Oo .Fl T .Op Ar from_date .Op Ar ,to_date .Op Ar /[c][m] .Oc .Ar ...\& .Ek .Op Ar .Ar directory .Sh DESCRIPTION .Nm Pax will read, write, and list the members of an archive file, and will copy directory hierarchies. .Nm Pax operation is independent of the specific archive format, and supports a wide variety of different archive formats. A list of supported archive formats can be found under the description of the .Fl x option. .Pp The presence of the .Fl r and the .Fl w options specifies which of the following functional modes .Nm will operate under: .Em list , read , write , and .Em copy . .Bl -tag -width 6n .It .Em List . .Nm Pax will write to .Dv standard output a table of contents of the members of the archive file read from .Dv standard input , whose pathnames match the specified .Ar patterns . The table of contents contains one filename per line and is written using single line buffering. .It Fl r .Em Read . .Nm Pax extracts the members of the archive file read from the .Dv standard input , with pathnames matching the specified .Ar patterns . The archive format and blocking is automatically determined on input. When an extracted file is a directory, the entire file hierarchy rooted at that directory is extracted. All extracted files are created relative to the current file hierarchy. The setting of ownership, access and modification times, and file mode of the extracted files are discussed in more detail under the .Fl p option. .It Fl w .Em Write . .Nm Pax writes an archive containing the .Ar file operands to .Dv standard output using the specified archive format. When no .Ar file operands are specified, a list of files to copy with one per line is read from .Dv standard input . When a .Ar file operand is also a directory, the entire file hierarchy rooted at that directory will be included. .It Fl r Fl w .Em Copy . .Nm Pax copies the .Ar file operands to the destination .Ar directory . When no .Ar file operands are specified, a list of files to copy with one per line is read from the .Dv standard input . When a .Ar file operand is also a directory the entire file hierarchy rooted at that directory will be included. The effect of the .Em copy is as if the copied files were written to an archive file and then subsequently extracted, except that there may be hard links between the original and the copied files (see the .Fl l option below). .Pp .Em Warning : The destination .Ar directory must not be one of the .Ar file operands or a member of a file hierarchy rooted at one of the .Ar file operands. The result of a .Em copy under these conditions is unpredictable. .El .Pp While processing a damaged archive during a .Em read or .Em list operation, .Nm will attempt to recover from media defects and will search through the archive to locate and process the largest number of archive members possible (see the .Fl E option for more details on error handling). .Sh OPERANDS The .Ar directory operand specifies a destination directory pathname. If the .Ar directory operand does not exist, or it is not writable by the user, or it is not of type directory, .Nm will exit with a non-zero exit status. .Pp The .Ar pattern operand is used to select one or more pathnames of archive members. Archive members are selected using the pattern matching notation described by .Xr fnmatch 3 . When the .Ar pattern operand is not supplied, all members of the archive will be selected. When a .Ar pattern matches a directory, the entire file hierarchy rooted at that directory will be selected. When a .Ar pattern operand does not select at least one archive member, .Nm will write these .Ar pattern operands in a diagnostic message to .Dv standard error and then exit with a non-zero exit status. .Pp The .Ar file operand specifies the pathname of a file to be copied or archived. When a .Ar file operand does not select at least one archive member, .Nm will write these .Ar file operand pathnames in a diagnostic message to .Dv standard error and then exit with a non-zero exit status. .Sh OPTIONS The following options are supported: .Bl -tag -width 4n .It Fl r Read an archive file from .Dv standard input and extract the specified .Ar files . If any intermediate directories are needed in order to extract an archive member, these directories will be created as if .Xr mkdir 2 was called with the bitwise inclusive .Dv OR of .Dv S_IRWXU , S_IRWXG , and .Dv S_IRWXO as the mode argument. When the selected archive format supports the specification of linked files and these files cannot be linked while the archive is being extracted, .Nm will write a diagnostic message to .Dv standard error and exit with a non-zero exit status at the completion of operation. .It Fl w Write files to the .Dv standard output in the specified archive format. When no .Ar file operands are specified, .Dv standard input is read for a list of pathnames with one per line without any leading or trailing .Aq blanks . .It Fl a Append .Ar files to the end of an archive that was previously written. If an archive format is not specified with a .Fl x option, the format currently being used in the archive will be selected. Any attempt to append to an archive in a format different from the format already used in the archive will cause .Nm to exit immediately with a non-zero exit status. The blocking size used in the archive volume where writing starts will continue to be used for the remainder of that archive volume. .Pp .Em Warning : Many storage devices are not able to support the operations necessary to perform an append operation. Any attempt to append to an archive stored on such a device may damage the archive or have other unpredictable results. Tape drives in particular are more likely to not support an append operation. An archive stored in a regular file system file or on a disk device will usually support an append operation. .It Fl b Ar blocksize When .Em writing an archive, block the output at a positive decimal integer number of bytes per write to the archive file. The .Ar blocksize must be a multiple of 512 bytes with a maximum of 64512 bytes. Archives larger than 32256 bytes violate the .Tn POSIX standard and will not be portable to all systems. A .Ar blocksize can end with .Li k or .Li b to specify multiplication by 1024 (1K) or 512, respectively. A pair of .Ar blocksizes can be separated by .Li x to indicate a product. A specific archive device may impose additional restrictions on the size of blocking it will support. When blocking is not specified, the default .Ar blocksize is dependent on the specific archive format being used (see the .Fl x option). .It Fl c Match all file or archive members .Em except those specified by the .Ar pattern and .Ar file operands. .It Fl d Cause files of type directory being copied or archived, or archive members of type directory being extracted, to match only the directory file or archive member and not the file hierarchy rooted at the directory. .It Fl f Ar archive Specify .Ar archive as the pathname of the input or output archive, overriding the default .Dv standard input (for .Em list and .Em read ) or .Dv standard output (for .Em write ) . A single archive may span multiple files and different archive devices. When required, .Nm will prompt for the pathname of the file or device of the next volume in the archive. .It Fl i Interactively rename files or archive members. For each archive member matching a .Ar pattern operand or each file matching a .Ar file operand, .Nm will prompt to .Pa /dev/tty giving the name of the file, its file mode and its modification time. .Nm Pax will then read a line from .Pa /dev/tty . If this line is blank, the file or archive member is skipped. If this line consists of a single period, the file or archive member is processed with no modification to its name. Otherwise, its name is replaced with the contents of the line. .Nm Pax will immediately exit with a non-zero exit status if .Dv is encountered when reading a response or if .Pa /dev/tty cannot be opened for reading and writing. .It Fl k Do not overwrite existing files. .It Fl l Link files. (The letter ell). In the .Em copy mode .Pq Fl r w , hard links are made between the source and destination file hierarchies whenever possible. .It Fl n Select the first archive member that matches each .Ar pattern operand. No more than one archive member is matched for each .Ar pattern . When members of type directory are matched, the file hierarchy rooted at that directory is also matched (unless .Fl d is also specified). .It Fl o Ar options Information to modify the algorithm for extracting or writing archive files which is specific to the archive format specified by .Fl x . In general, .Ar options take the form: .Cm name=value .It Fl p Ar string Specify one or more file characteristic options (privileges). The .Ar string option-argument is a string specifying file characteristics to be retained or discarded on extraction. The string consists of the specification characters .Cm a , e , m , o , and .Cm p . Multiple characteristics can be concatenated within the same string and multiple .Fl p options can be specified. The meaning of the specification characters are as follows: .Bl -tag -width 2n .It Cm a Do not preserve file access times. By default, file access times are preserved whenever possible. .It Cm e .Sq Preserve everything , the user ID, group ID, file mode bits, file access time, and file modification time. This is intended to be used by .Em root , someone with all the appropriate privileges, in order to preserve all aspects of the files as they are recorded in the archive. The .Cm e flag is the sum of the .Cm o and .Cm p flags. .It Cm m Do not preserve file modification times. By default, file modification times are preserved whenever possible. .It Cm o Preserve the user ID and group ID. .It Cm p .Sq Preserve the file mode bits. This intended to be used by a .Em user with regular privileges who wants to preserve all aspects of the file other than the ownership. The file times are preserved by default, but two other flags are offered to disable this and use the time of extraction instead. .El .Pp In the preceding list, .Sq preserve indicates that an attribute stored in the archive is given to the extracted file, subject to the permissions of the invoking process. Otherwise the attribute of the extracted file is determined as part of the normal file creation action. If neither the .Cm e nor the .Cm o specification character is specified, or the user ID and group ID are not preserved for any reason, .Nm will not set the .Dv S_ISUID .Em ( setuid ) and .Dv S_ISGID .Em ( setgid ) bits of the file mode. If the preservation of any of these items fails for any reason, .Nm will write a diagnostic message to .Dv standard error . Failure to preserve these items will affect the final exit status, but will not cause the extracted file to be deleted. If the file characteristic letters in any of the string option-arguments are duplicated or conflict with each other, the one(s) given last will take precedence. For example, if .Dl Fl p Ar eme is specified, file modification times are still preserved. .It Fl s Ar replstr Modify the file or archive member names specified by the .Ar pattern or .Ar file operands according to the substitution expression .Ar replstr , using the syntax of the .Xr ed 1 utility regular expressions. The format of these regular expressions are: .Dl /old/new/[gp] As in .Xr ed 1 , .Cm old is a basic regular expression and .Cm new can contain an ampersand (&), \\n (where n is a digit) back-references, or subexpression matching. The .Cm old string may also contain .Dv characters. Any non-null character can be used as a delimiter (/ is shown here). Multiple .Fl s expressions can be specified. The expressions are applied in the order they are specified on the command line, terminating with the first successful substitution. The optional trailing .Cm g continues to apply the substitution expression to the pathname substring which starts with the first character following the end of the last successful substitution. The first unsuccessful substitution stops the operation of the .Cm g option. The optional trailing .Cm p will cause the final result of a successful substitution to be written to .Dv standard error in the following format: .Dl >> File or archive member names that substitute to the empty string are not selected and will be skipped. .It Fl t Reset the access times of any file or directory read or accessed by .Nm to be the same as they were before being read or accessed by .Nm . .It Fl u Ignore files that are older (having a less recent file modification time) than a pre-existing file or archive member with the same name. During .Em read , an archive member with the same name as a file in the file system will be extracted if the archive member is newer than the file. During .Em write , a file system member with the same name as an archive member will be written to the archive if it is newer than the archive member. During .Em copy , the file in the destination hierarchy is replaced by the file in the source hierarchy or by a link to the file in the source hierarchy if the file in the source hierarchy is newer. .It Fl v During a .Em list operation, produce a verbose table of contents using the format of the .Xr ls 1 utility with the .Fl l option. For pathnames representing a hard link to a previous member of the archive, the output has the format: .Dl == For pathnames representing a symbolic link, the output has the format: .Dl => Where is the output format specified by the .Xr ls 1 utility when used with the .Fl l option. Otherwise for all the other operational modes .Em ( read , write , and .Em copy ) , pathnames are written and flushed to .Dv standard error without a trailing .Dv as soon as processing begins on that file or archive member. The trailing .Dv , is not buffered, and is written only after the file has been read or written. .It Fl x Ar format Specify the output archive format, with the default format being .Ar ustar . .Nm Pax currently supports the following formats: .Bl -tag -width "sv4cpio" .It Ar cpio The extended cpio interchange format specified in the .St -p1003.2 standard. The default blocksize for this format is 5120 bytes. Inode and device information about a file (used for detecting file hard links by this format) which may be truncated by this format is detected by .Nm and is repaired. .It Ar bcpio The old binary cpio format. The default blocksize for this format is 5120 bytes. This format is not very portable and should not be used when other formats are available. Inode and device information about a file (used for detecting file hard links by this format) which may be truncated by this format is detected by .Nm and is repaired. .It Ar sv4cpio The System V release 4 cpio. The default blocksize for this format is 5120 bytes. Inode and device information about a file (used for detecting file hard links by this format) which may be truncated by this format is detected by .Nm and is repaired. .It Ar sv4crc The System V release 4 cpio with file crc checksums. The default blocksize for this format is 5120 bytes. Inode and device information about a file (used for detecting file hard links by this format) which may be truncated by this format is detected by .Nm and is repaired. .It Ar tar -The old BSD tar format as found in BSD4.3. +The old +.Bx +tar format as found in +.Bx 4.3 . The default blocksize for this format is 10240 bytes. Pathnames stored by this format must be 100 characters or less in length. Only .Em regular files, .Em hard links , soft links , and .Em directories will be archived (other file system types are not supported). For backwards compatibility with even older tar formats, a .Fl o option can be used when writing an archive to omit the storage of directories. This option takes the form: .Dl Fl o Cm write_opt=nodir .It Ar ustar The extended tar interchange format specified in the .St -p1003.2 standard. The default blocksize for this format is 10240 bytes. Pathnames stored by this format must be 250 characters or less in length. .El .Pp .Nm Pax will detect and report any file that it is unable to store or extract as the result of any specific archive format restrictions. The individual archive formats may impose additional restrictions on use. Typical archive format restrictions include (but are not limited to): file pathname length, file size, link pathname length and the type of the file. .It Fl z Use .Xr gzip 1 to compress (decompress) the archive while writing (reading). Incompatible with .Fl a . .It Fl B Ar bytes Limit the number of bytes written to a single archive volume to .Ar bytes . The .Ar bytes limit can end with .Li m , .Li k , or .Li b to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively. A pair of .Ar bytes limits can be separated by .Li x to indicate a product. .Pp .Em Warning : Only use this option when writing an archive to a device which supports an end of file read condition based on last (or largest) write offset (such as a regular file or a tape drive). The use of this option with a floppy or hard disk is not recommended. .It Fl D This option is the same as the .Fl u option, except that the file inode change time is checked instead of the file modification time. The file inode change time can be used to select files whose inode information (e.g. uid, gid, etc.) is newer than a copy of the file in the destination .Ar directory . .It Fl E Ar limit Limit the number of consecutive read faults while trying to read a flawed archives to .Ar limit . With a positive .Ar limit , .Nm will attempt to recover from an archive read error and will continue processing starting with the next file stored in the archive. A .Ar limit of 0 will cause .Nm to stop operation after the first read error is detected on an archive volume. A .Ar limit of .Li NONE will cause .Nm to attempt to recover from read errors forever. The default .Ar limit is a small positive number of retries. .Pp .Em Warning : Using this option with .Li NONE should be used with extreme caution as .Nm may get stuck in an infinite loop on a very badly flawed archive. .It Fl G Ar group Select a file based on its .Ar group name, or when starting with a .Cm # , a numeric gid. A '\\' can be used to escape the .Cm # . Multiple .Fl G options may be supplied and checking stops with the first match. .It Fl H Follow only command line symbolic links while performing a physical file system traversal. .It Fl L Follow all symbolic links to perform a logical file system traversal. .It Fl P Do not follow symbolic links, perform a physical file system traversal. This is the default mode. .It Fl T Ar [from_date][,to_date][/[c][m]] Allow files to be selected based on a file modification or inode change time falling within a specified time range of .Ar from_date to .Ar to_date (the dates are inclusive). If only a .Ar from_date is supplied, all files with a modification or inode change time equal to or younger are selected. If only a .Ar to_date is supplied, all files with a modification or inode change time equal to or older will be selected. When the .Ar from_date is equal to the .Ar to_date , only files with a modification or inode change time of exactly that time will be selected. .Pp When .Nm is in the .Em write or .Em copy mode, the optional trailing field .Ar [c][m] can be used to determine which file time (inode change, file modification or both) are used in the comparison. If neither is specified, the default is to use file modification time only. The .Ar m specifies the comparison of file modification time (the time when the file was last written). The .Ar c specifies the comparison of inode change time (the time when the file inode was last changed; e.g. a change of owner, group, mode, etc). When .Ar c and .Ar m are both specified, then the modification and inode change times are both compared. The inode change time comparison is useful in selecting files whose attributes were recently changed or selecting files which were recently created and had their modification time reset to an older time (as what happens when a file is extracted from an archive and the modification time is preserved). Time comparisons using both file times is useful when .Nm is used to create a time based incremental archive (only files that were changed during a specified time range will be archived). .Pp A time range is made up of six different fields and each field must contain two digits. The format is: .Dl [yy[mm[dd[hh]]]]mm[.ss] Where .Cm yy is the last two digits of the year, the first .Cm mm is the month (from 01 to 12), .Cm dd is the day of the month (from 01 to 31), .Cm hh is the hour of the day (from 00 to 23), the second .Cm mm is the minute (from 00 to 59), and .Cm ss is the seconds (from 00 to 59). The minute field .Cm mm is required, while the other fields are optional and must be added in the following order: .Dl Cm hh , dd , mm , yy . The .Cm ss field may be added independently of the other fields. Time ranges are relative to the current time, so .Dl Fl T Ar 1234/cm would select all files with a modification or inode change time of 12:34 PM today or later. Multiple .Fl T time range can be supplied and checking stops with the first match. .It Fl U Ar user Select a file based on its .Ar user name, or when starting with a .Cm # , a numeric uid. A '\\' can be used to escape the .Cm # . Multiple .Fl U options may be supplied and checking stops with the first match. .It Fl X When traversing the file hierarchy specified by a pathname, do not descend into directories that have a different device ID. See the .Li st_dev field as described in .Xr stat 2 for more information about device ID's. .It Fl Y This option is the same as the .Fl D option, except that the inode change time is checked using the pathname created after all the file name modifications have completed. .It Fl Z This option is the same as the .Fl u option, except that the modification time is checked using the pathname created after all the file name modifications have completed. .El .Pp The options that operate on the names of files or archive members .Fl ( c , .Fl i , .Fl n , .Fl s , .Fl u , .Fl v , .Fl D , .Fl G , .Fl T , .Fl U , .Fl Y , and .Fl Z ) interact as follows. .Pp When extracting files during a .Em read operation, archive members are .Sq selected , based only on the user specified pattern operands as modified by the .Fl c , .Fl n , .Fl u , .Fl D , .Fl G , .Fl T , .Fl U options. Then any .Fl s and .Fl i options will modify in that order, the names of these selected files. Then the .Fl Y and .Fl Z options will be applied based on the final pathname. Finally the .Fl v option will write the names resulting from these modifications. .Pp When archiving files during a .Em write operation, or copying files during a .Em copy operation, archive members are .Sq selected , based only on the user specified pathnames as modified by the .Fl n , .Fl u , .Fl D , .Fl G , .Fl T , and .Fl U options (the .Fl D option only applies during a copy operation). Then any .Fl s and .Fl i options will modify in that order, the names of these selected files. Then during a .Em copy operation the .Fl Y and the .Fl Z options will be applied based on the final pathname. Finally the .Fl v option will write the names resulting from these modifications. .Pp When one or both of the .Fl u or .Fl D options are specified along with the .Fl n option, a file is not considered selected unless it is newer than the file to which it is compared. .Sh EXAMPLES The command: .Dl "pax -w -f /dev/rst0 ." copies the contents of the current directory to the device .Pa /dev/rst0 . .Pp The command: .Dl pax -v -f filename gives the verbose table of contents for an archive stored in .Pa filename . .Pp The following commands: .Dl mkdir /tmp/foo .Dl cd /tmp/bar .Dl pax -rw .\ /tmp/foo will copy the entire .Pa /tmp/bar directory hierarchy to .Pa /tmp/foo . .Pp The command: .Dl pax -r -s ',^//*usr//*,,' -f a.pax reads the archive .Pa a.pax , with all files rooted in ``/usr'' into the archive extracted relative to the current directory. .Pp The command: .Dl pax -rw -i .\ dest_dir can be used to interactively select the files to copy from the current directory to .Pa dest_dir . .Pp The command: .Dl pax -r -pe -U root -G bin -f a.pax will extract all files from the archive .Pa a.pax which are owned by .Em root with group .Em bin and will preserve all file permissions. .Pp The command: .Dl pax -r -w -v -Y -Z home /backup will update (and list) only those files in the destination directory .Pa /backup which are older (less recent inode change or file modification times) than files with the same name found in the source file tree .Pa home . .Sh STANDARDS The .Nm utility is a superset of the .St -p1003.2 standard. The options .Fl z , .Fl B , .Fl D , .Fl E , .Fl G , .Fl H , .Fl L , .Fl P , .Fl T , .Fl U , .Fl Y , .Fl Z , the archive formats .Ar bcpio , .Ar sv4cpio , .Ar sv4crc , .Ar tar , and the flawed archive handling during .Ar list and .Ar read operations are extensions to the .Tn POSIX standard. .Sh SEE ALSO .Xr cpio 1 , .Xr tar 1 .Sh HISTORY The .Nm utility appeared in .Bx 4.4 . .Sh AUTHORS .An Keith Muller at the University of California, San Diego .Sh DIAGNOSTICS .Nm Pax will exit with one of the following values: .Bl -tag -width 2n .It 0 All files were processed successfully. .It 1 An error occurred. .El .Pp Whenever .Nm cannot create a file or a link when reading an archive or cannot find a file when writing an archive, or cannot preserve the user ID, group ID, or file mode when the .Fl p option is specified, a diagnostic message is written to .Dv standard error and a non-zero exit status will be returned, but processing will continue. In the case where pax cannot create a link to a file, .Nm will not create a second copy of the file. .Pp If the extraction of a file from an archive is prematurely terminated by a signal or error, .Nm may have only partially extracted a file the user wanted. Additionally, the file modes of extracted files and directories may have incorrect file bits, and the modification and access times may be wrong. .Pp If the creation of an archive is prematurely terminated by a signal or error, .Nm may have only partially created the archive which may violate the specific archive format specification. .Pp If while doing a .Em copy , .Nm detects a file is about to overwrite itself, the file is not copied, a diagnostic message is written to .Dv standard error and when .Nm completes it will exit with a non-zero exit status. Index: head/bin/stty/stty.1 =================================================================== --- head/bin/stty/stty.1 (revision 81621) +++ head/bin/stty/stty.1 (revision 81622) @@ -1,595 +1,595 @@ .\" Copyright (c) 1990, 1993, 1994 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the Institute of Electrical and Electronics Engineers, Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. 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. .\" .\" @(#)stty.1 8.4 (Berkeley) 4/18/94 .\" $FreeBSD$ .\" .Dd April 18, 1994 .Dt STTY 1 .Os .Sh NAME .Nm stty .Nd set the options for a terminal device interface .Sh SYNOPSIS .Nm .Op Fl a | Fl e | Fl g .Op Fl f Ar file .Op operands .Sh DESCRIPTION The .Nm utility sets or reports on terminal characteristics for the device that is its standard input. If no options or operands are specified, it reports the settings of a subset of characteristics as well as additional ones if they differ from their default values. Otherwise it modifies the terminal state according to the specified arguments. Some combinations of arguments are mutually exclusive on some terminal types. .Pp The following options are available: .Bl -tag -width indent .It Fl a Display all the current settings for the terminal to standard output as per .St -p1003.2 . .It Fl e Display all the current settings for the terminal to standard output in the traditional -.Tn BSD +.Bx ``all'' and ``everything'' formats. .It Fl f Open and use the terminal named by .Ar file rather than using standard input. The file is opened using the .Dv O_NONBLOCK flag of .Fn open , making it possible to set or display settings on a terminal that might otherwise block on the open. .It Fl g Display all the current settings for the terminal to standard output in a form that may be used as an argument to a subsequent invocation of .Nm to restore the current terminal state as per .St -p1003.2 . .El .Pp The following arguments are available to set the terminal characteristics: .Ss Control Modes: .Pp Control mode flags affect hardware characteristics associated with the terminal. This corresponds to the c_cflag in the termios structure. .Bl -tag -width Fl .It Cm parenb Pq Fl parenb Enable (disable) parity generation and detection. .It Cm parodd Pq Fl parodd Select odd (even) parity. .It Cm cs5 cs6 cs7 cs8 Select character size, if possible. .It Ar number Set terminal baud rate to the number given, if possible. If the baud rate is set to zero, modem control is no longer asserted. .It Cm ispeed Ar number Set terminal input baud rate to the number given, if possible. If the input baud rate is set to zero, the input baud rate is set to the value of the output baud rate. .It Cm ospeed Ar number Set terminal output baud rate to the number given, if possible. If the output baud rate is set to zero, modem control is no longer asserted. .It Cm speed Ar number This sets both .Cm ispeed and .Cm ospeed to .Ar number . .It Cm hupcl Pq Fl hupcl Stop asserting modem control (do not stop asserting modem control) on last close. .It Cm hup Pq Fl hup Same as hupcl .Pq Fl hupcl . .It Cm cstopb Pq Fl cstopb Use two (one) stop bits per character. .It Cm cread Pq Fl cread Enable (disable) the receiver. .It Cm clocal Pq Fl clocal Assume a line without (with) modem control. .It Cm crtscts Pq Fl crtscts Enable (disable) RTS/CTS flow control. .El .Ss Input Modes: This corresponds to the c_iflag in the termios structure. .Bl -tag -width Fl .It Cm ignbrk Pq Fl ignbrk Ignore (do not ignore) break on input. .It Cm brkint Pq Fl brkint Signal (do not signal) .Dv INTR on break. .It Cm ignpar Pq Fl ignpar Ignore (do not ignore) characters with parity errors. .It Cm parmrk Pq Fl parmrk Mark (do not mark) characters with parity errors. .It Cm inpck Pq Fl inpck Enable (disable) input parity checking. .It Cm istrip Pq Fl istrip Strip (do not strip) input characters to seven bits. .It Cm inlcr Pq Fl inlcr Map (do not map) .Dv NL to .Dv CR on input. .It Cm igncr Pq Fl igncr Ignore (do not ignore) .Dv CR on input. .It Cm icrnl Pq Fl icrnl Map (do not map) .Dv CR to .Dv NL on input. .It Cm ixon Pq Fl ixon Enable (disable) .Dv START/STOP output control. Output from the system is stopped when the system receives .Dv STOP and started when the system receives .Dv START , or if .Cm ixany is set, any character restarts output. .It Cm ixoff Pq Fl ixoff Request that the system send (not send) .Dv START/STOP characters when the input queue is nearly empty/full. .It Cm ixany Pq Fl ixany Allow any character (allow only .Dv START ) to restart output. .It Cm imaxbel Pq Fl imaxbel The system imposes a limit of .Dv MAX_INPUT (currently 255) characters in the input queue. If .Cm imaxbel is set and the input queue limit has been reached, subsequent input causes the system to send an ASCII BEL character to the output queue (the terminal beeps at you). Otherwise, if .Cm imaxbel is unset and the input queue is full, the next input character causes the entire input and output queues to be discarded. .El .Ss Output Modes: This corresponds to the c_oflag of the termios structure. .Bl -tag -width Fl .It Cm opost Pq Fl opost Post-process output (do not post-process output; ignore all other output modes). .It Cm onlcr Pq Fl onlcr Map (do not map) .Dv NL to .Dv CR-NL on output. .It Cm ocrnl Pq Fl ocrnl Map (do not map) .Dv CR to .Dv NL on output. .It Cm oxtabs Pq Fl oxtabs Expand (do not expand) tabs to spaces on output. .It Cm onocr Pq Fl onocr Do not (do) output CRs at column zero. .It Cm onlret Pq Fl onlret On the terminal NL performs (does not perform) the CR function. .El .Ss Local Modes: .Pp Local mode flags (lflags) affect various and sundry characteristics of terminal processing. Historically the term "local" pertained to new job control features implemented by Jim Kulp on a .Tn Pdp 11/70 at .Tn IIASA . Later the driver ran on the first .Tn VAX at Evans Hall, UC Berkeley, where the job control details were greatly modified but the structure definitions and names remained essentially unchanged. The second interpretation of the 'l' in lflag is ``line discipline flag'' which corresponds to the .Ar c_lflag of the .Ar termios structure. .Bl -tag -width Fl .It Cm isig Pq Fl isig Enable (disable) the checking of characters against the special control characters .Dv INTR , QUIT , and .Dv SUSP . .It Cm icanon Pq Fl icanon Enable (disable) canonical input .Pf ( Dv ERASE and .Dv KILL processing). .It Cm iexten Pq Fl iexten Enable (disable) any implementation defined special control characters not currently controlled by icanon, isig, or ixon. .It Cm echo Pq Fl echo Echo back (do not echo back) every character typed. .It Cm echoe Pq Fl echoe The .Dv ERASE character shall (shall not) visually erase the last character in the current line from the display, if possible. .It Cm echok Pq Fl echok Echo (do not echo) .Dv NL after .Dv KILL character. .It Cm echoke Pq Fl echoke The .Dv KILL character shall (shall not) visually erase the current line from the display, if possible. .It Cm echonl Pq Fl echonl Echo (do not echo) .Dv NL , even if echo is disabled. .It Cm echoctl Pq Fl echoctl If .Cm echoctl is set, echo control characters as ^X. Otherwise control characters echo as themselves. .It Cm echoprt Pq Fl echoprt For printing terminals. If set, echo erased characters backwards within ``\\'' and ``/''. Otherwise, disable this feature. .It Cm noflsh Pq Fl noflsh Disable (enable) flush after .Dv INTR , QUIT , SUSP . .It Cm tostop Pq Fl tostop Send (do not send) .Dv SIGTTOU for background output. This causes background jobs to stop if they attempt terminal output. .It Cm altwerase Pq Fl altwerase Use (do not use) an alternate word erase algorithm when processing .Dv WERASE characters. This alternate algorithm considers sequences of alphanumeric/underscores as words. It also skips the first preceding character in its classification (as a convenience since the one preceding character could have been erased with simply an .Dv ERASE character.) .It Cm mdmbuf Pq Fl mdmbuf If set, flow control output based on condition of Carrier Detect. Otherwise writes return an error if Carrier Detect is low (and Carrier is not being ignored with the .Dv CLOCAL flag.) .It Cm flusho Pq Fl flusho Indicates output is (is not) being discarded. .It Cm pendin Pq Fl pendin Indicates input is (is not) pending after a switch from non-canonical to canonical mode and will be re-input when a read becomes pending or more input arrives. .El .Ss Control Characters: .Bl -tag -width Fl .It Ar control-character Ar string Set .Ar control-character to .Ar string . If string is a single character, the control character is set to that character. If string is the two character sequence "^-" or the string "undef" the control character is disabled (i.e. set to .Pf { Dv _POSIX_VDISABLE Ns } . ) .Pp Recognized control-characters: .Bd -ragged -offset indent .Bl -column character Subscript .It control- .It character Ta Subscript Ta Description .It _________ Ta _________ Ta _______________ .It eof Ta Tn VEOF Ta EOF No character .It eol Ta Tn VEOL Ta EOL No character .It eol2 Ta Tn VEOL2 Ta EOL2 No character .It erase Ta Tn VERASE Ta ERASE No character .It erase2 Ta Tn VERASE2 Ta ERASE2 No character .It werase Ta Tn VWERASE Ta WERASE No character .It intr Ta Tn VINTR Ta INTR No character .It kill Ta Tn VKILL Ta KILL No character .It quit Ta Tn VQUIT Ta QUIT No character .It susp Ta Tn VSUSP Ta SUSP No character .It start Ta Tn VSTART Ta START No character .It stop Ta Tn VSTOP Ta STOP No character .It dsusp Ta Tn VDSUSP Ta DSUSP No character .It lnext Ta Tn VLNEXT Ta LNEXT No character .It reprint Ta Tn VREPRINT Ta REPRINT No character .It status Ta Tn VSTATUS Ta STATUS No character .El .Ed .It Cm min Ar number .It Cm time Ar number Set the value of min or time to number. .Dv MIN and .Dv TIME are used in Non-Canonical mode input processing (-icanon). .El .Ss Combination Modes: .Pp .Bl -tag -width Fl .It Ar saved settings Set the current terminal characteristics to the saved settings produced by the .Fl g option. .It Cm evenp No or Cm parity Enable parenb and cs7; disable parodd. .It Cm oddp Enable parenb, cs7, and parodd. .It Fl parity , evenp , oddp Disable parenb, and set cs8. .It Cm \&nl Pq Fl \&nl Enable (disable) icrnl. In addition -nl unsets inlcr and igncr. .It Cm ek Reset .Dv ERASE , .Dv ERASE2 , and .Dv KILL characters back to system defaults. .It Cm sane Resets all modes to reasonable values for interactive terminal use. .It Cm tty Set the line discipline to the standard terminal line discipline .Dv TTYDISC . .It Cm crt Pq Fl crt Set (disable) all modes suitable for a CRT display device. .It Cm kerninfo Pq Fl kerninfo Enable (disable) the system generated status line associated with processing a .Dv STATUS character (usually set to ^T). The status line consists of the system load average, the current command name, its process ID, the event the process is waiting on (or the status of the process), the user and system times, percent cpu, and current memory usage. .It Cm columns Ar number The terminal size is recorded as having .Ar number columns. .It Cm cols Ar number is an alias for .Cm columns . .It Cm rows Ar number The terminal size is recorded as having .Ar number rows. .It Cm dec Set modes suitable for users of Digital Equipment Corporation systems .Dv ( ERASE , .Dv KILL , and .Dv INTR characters are set to ^?, ^U, and ^C; .Dv ixany is disabled, and .Dv crt is enabled.) .It Cm extproc Pq Fl extproc If set, this flag indicates that some amount of terminal processing is being performed by either the terminal hardware or by the remote side connected to a pty. .It Cm raw Pq Fl raw If set, change the modes of the terminal so that no input or output processing is performed. If unset, change the modes of the terminal to some reasonable state that performs input and output processing. Note that since the terminal driver no longer has a single .Dv RAW bit, it is not possible to intuit what flags were set prior to setting .Cm raw . This means that unsetting .Cm raw may not put back all the setting that were previously in effect. To set the terminal into a raw state and then accurately restore it, the following shell code is recommended: .Bd -literal save_state=$(stty -g) stty raw \&... stty "$save_state" .Ed .It Cm size The size of the terminal is printed as two numbers on a single line, first rows, then columns. .El .Ss Compatibility Modes: .Pp These modes remain for compatibility with the previous version of the .Nm command. .Bl -tag -width Fl .It Cm all Reports all the terminal modes as with .Cm stty Fl a except that the control characters are printed in a columnar format. .It Cm everything Same as .Cm all . .It Cm cooked Same as .Cm sane . .It Cm cbreak If set, enables .Cm brkint , ixon , imaxbel , opost , .Cm isig , iexten , and .Fl icanon . If unset, same as .Cm sane . .It Cm new Same as .Cm tty . .It Cm old Same as .Cm tty . .It Cm newcrt Pq Fl newcrt Same as .Cm crt . .It Cm pass8 The converse of .Cm parity . .It Cm tandem Pq Fl tandem Same as .Cm ixoff . .It Cm decctlq Pq Fl decctlq The converse of .Cm ixany . .It Cm crterase Pq Fl crterase Same as .Cm echoe . .It Cm crtbs Pq Fl crtbs Same as .Cm echoe . .It Cm crtkill Pq Fl crtkill Same as .Cm echoke . .It Cm ctlecho Pq Fl ctlecho Same as .Cm echoctl . .It Cm prterase Pq Fl prterase Same as .Cm echoprt . .It Cm litout Pq Fl litout The converse of .Cm opost . .It Cm tabs Pq Fl tabs The converse of .Cm oxtabs . .It Cm brk Ar value Same as the control character .Cm eol . .It Cm flush Ar value Same as the control character .Cm discard . .It Cm rprnt Ar value Same as the control character .Cm reprint . .El .Sh DIAGNOSTICS The .Nm utility exits 0 on success, and >0 if an error occurs. .Sh SEE ALSO .Xr termios 4 .Sh STANDARDS The .Nm function is expected to be .St -p1003.2 compatible. The flags .Fl e and .Fl f are extensions to the standard. Index: head/contrib/amd/amd/amd.8 =================================================================== --- head/contrib/amd/amd/amd.8 (revision 81621) +++ head/contrib/amd/amd/amd.8 (revision 81622) @@ -1,346 +1,347 @@ .\" .\" Copyright (c) 1997-1999 Erez Zadok .\" Copyright (c) 1989 Jan-Simon Pendry .\" Copyright (c) 1989 Imperial College of Science, Technology & Medicine .\" Copyright (c) 1989 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Jan-Simon Pendry at Imperial College, London. .\" .\" 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 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. .\" .\" %W% (Berkeley) %G% .\" .\" $Id: amd.8,v 1.3 1999/09/30 21:01:29 ezk Exp $ .\" $FreeBSD$ .\" .Dd April 19, 1994 .Dt AMD 8 .Os .Sh NAME .Nm amd .Nd automatically mount file systems .Sh SYNOPSIS .Nm amd .Fl H .Nm amd .Op Fl F Ar conf_file .Nm amd .Op Fl nprvHS .Op Fl a Ar mount_point .Op Fl c Ar duration .Op Fl d Ar domain .Bk -words .Op Fl k Ar kernel-arch .Ek .Op Fl l Ar logfile .Op Fl o Ar op_sys_ver .Op Fl t Ar timeout.retransmit .Bk -words .Op Fl w Ar interval .Ek .Op Fl x Ar log-option .Op Fl y Ar YP-domain .Bk -words .Op Fl C Ar cluster-name .Ek .Op Fl D Ar option .Op Fl F Ar conf_file .Op Fl O Ar op_sys_name .Op Fl T Ar tag .Oo .Ar directory mapname .Op Fl map-options .Oc .Ar ... .Sh DESCRIPTION .Nm Amd is a daemon that automatically mounts filesystems whenever a file or directory within that filesystem is accessed. Filesystems are automatically unmounted when they appear to be quiescent. .Pp .Nm Amd operates by attaching itself as an .Tn NFS server to each of the specified .Ar directories . Lookups within the specified directories are handled by .Nm amd , which uses the map defined by .Ar mapname to determine how to resolve the lookup. Generally, this will be a host name, some filesystem information and some mount options for the given filesystem. .Pp In the first form depicted above, .Nm amd will print a short help string. In the second form, if no options are specified, or if the .Fl F is used, .Nm amd will read configuration parameters from the file .Ar conf_file which defaults to .Pa /etc/amd.conf . The last form is described below. .Sh OPTIONS .Bl -tag -width Ds .It Fl a Ar temporary-directory Specify an alternative location for the real mount points. The default is .Pa /.amd_mnt . .It Fl c Ar duration Specify a .Ar duration , in seconds, that a looked up name remains cached when not in use. The default is 5 minutes. .It Fl d Ar domain Specify the local domain name. If this option is not given the domain name is determined from the hostname. .It Fl k Ar kernel-arch Specifies the kernel architecture. This is used solely to set the ${karch} selector. .It Fl l Ar logfile Specify a logfile in which to record mount and unmount events. If .Ar logfile is the string .Em syslog , the log messages will be sent to the system log daemon by .Xr syslog 3 . The default syslog facility used is LOG_DAEMON. If you wish to change it, append its name to the log file name, delimited by a single colon. For example, if .Ar logfile is the string .Dq Li syslog:local7 then .Nm amd will log messages via .Xr syslog 3 using the LOG_LOCAL7 facility (if it exists on the system). .It Fl n Normalize hostnames. The name referred to by ${rhost} is normalized relative to the host database before being used. The effect is to translate aliases into ``official'' names. .It Fl o Ar op_sys_ver Override the compiled-in version number of the operating system. Useful when the built in version is not desired for backward compatibility reasons. For example, if the build in version is .Dq 2.5.1 , you can override it to .Dq 5.5.1 , and use older maps that were written with the latter in mind. .It Fl p Print .Em PID . Outputs the process-id of .Nm amd to standard output where it can be saved into a file. .It Fl r Restart existing mounts. .Nm Amd will scan the mount file table to determine which filesystems are currently mounted. Whenever one of these would have been auto-mounted, .Nm amd .Em inherits it. .It Fl t Ar timeout.retransmit Specify the NFS timeout .Ar interval , in tenths of a second, between .Tn NFS/RPC retries (for UDP only). The default is 0.8 seconds. The second value alters the restransmit counter, which defaults to 11 retransmissions. Both of these values are used by the kernel to communicate with amd. Useful defaults are supplied if either or both values are missing. .Pp Amd relies on the kernel RPC retransmit mechanism to trigger mount retries. The values of these parameters change the overall retry interval. Too long an interval gives poor interactive response; too short an interval causes excessive retries. .It Fl v Version. Displays version and configuration information on standard error. .It Fl w Ar interval Specify an .Ar interval , in seconds, between attempts to dismount filesystems that have exceeded their cached times. The default is 2 minutes. .It Fl x Ar options Specify run-time logging options. The options are a comma separated list chosen from: fatal, error, user, warn, info, map, stats, all. .It Fl y Ar domain Specify an alternative .Tn NIS domain from which to fetch the .Tn NIS maps. The default is the system domain name. This option is ignored if .Tn NIS support is not available. .It Fl C Ar cluster-name Specify an alternative HP-UX cluster name to use. .It Fl D Ar option Select from a variety of debug options. Prefixing an option with the string .Em no reverses the effect of that option. Options are cumulative. The most useful option is .Ar all . .Pp Since .Fl D is only used for debugging other options are not documented here: the current supported set of options is listed by the .Fl v option and a fuller description is available in the program source. .It Fl F Ar conf_file Specify an .Nm amd configuration file to use. See .Xr amd.conf 5 for description of this file's format. This configuration file is used to specify any options in lieu of typing many of them on the command line. The .Nm amd.conf file includes directives for every command line option amd has, and many more that are only available via the configuration file facility. The configuration file specified by this option is processed after all other options have been processed, regardless of the actual location of this option on the command line. .It Fl H Print help and usage string. .It Fl O Ar op_sys_name Override the compiled-in name of the operating system. Useful when the built in name is not desired for backward compatibility reasons. For example, if the build in name is .Dq sunos5 , you can override it to .Dq sos5 and use older maps which were written with the latter in mind. .It Fl S Do not lock the running executable pages of .Nm amd into memory. To improve .Nm amd's performance, systems that support the .Xr plock 3 call, could lock the .Nm amd process into memory. This way there is less chance the operating system will schedule, page out, and swap the .Nm amd process as needed. This tends to improve .Nm amd's performance, at the cost of reserving the memory used by the .Nm amd process (making it unavailable for other processes). If this behavior is not desired, use the .Fl S option. .It Fl T Ar tag Specify a tag to use with .Xr amd.conf 5 . All Map entries tagged with tag will be processed. Map entries that are not tagged are always processed. Map entries that are tagged with a tag other than .Ar tag will not be processed. .El .Sh FILES .Bl -tag -width /axx .It Pa /.amd_mnt directory under which filesystems are dynamically mounted .It Pa /etc/amd.conf default configuration file .El .Sh CAVEATS Some care may be required when creating a mount map. .Pp Symbolic links on an .Tn NFS filesystem can be incredibly inefficient. In most implementations of .Tn NFS , their interpolations are not cached by the kernel and each time a symbolic link is encountered during a .Em lookuppn translation it costs an .Tn RPC call to the .Tn NFS server. A large improvement in real-time performance could be gained by adding a cache somewhere. Replacing .Xr symlink 2 with a suitable incarnation of the auto-mounter results in a large real-time speedup, but also causes a large number of process context switches. .Pp A weird imagination is most useful to gain full advantage of all the features. .Sh SEE ALSO .Xr domainname 1 , .Xr hostname 1 , .Xr syslog 3 , .Xr amd.conf 5 , .Xr mtab 5 , .Xr amq 8 , .Xr mount 8 , .Xr umount 8 .Rs .%T Amd \- The 4.4 BSD Automounter .Re .Sh AUTHORS .An Jan-Simon Pendry Aq jsp@doc.ic.ac.uk , Department of Computing, Imperial College, London, UK. .Pp .An Erez Zadok Aq ezk@cs.columbia.edu , Department of Computer Science, Columbia University, New York, USA. .Pp Other authors and contributors to am-utils are listed in the .Pa AUTHORS file distributed with am-utils. .Sh HISTORY The .Nm amd -utility first appeared in 4.4BSD. +utility first appeared in +.Bx 4.4 . Index: head/contrib/amd/amq/amq.8 =================================================================== --- head/contrib/amd/amq/amq.8 (revision 81621) +++ head/contrib/amd/amq/amq.8 (revision 81622) @@ -1,213 +1,214 @@ .\" .\" Copyright (c) 1997-1999 Erez Zadok .\" Copyright (c) 1990 Jan-Simon Pendry .\" Copyright (c) 1990 Imperial College of Science, Technology & Medicine .\" Copyright (c) 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Jan-Simon Pendry at Imperial College, London. .\" .\" 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 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. .\" .\" %W% (Berkeley) %G% .\" .\" $Id: amq.8,v 1.2 1999/01/10 21:53:58 ezk Exp $ .\" $FreeBSD$ .\" .Dd March 16, 1991 .Dt AMQ 8 .Os .Sh NAME .Nm amq .Nd automounter query tool .Sh SYNOPSIS .Nm amq .Op Fl fmpsuvTU .Op Fl h Ar hostname .Op Fl l Ar log_file .Op Fl x Ar log_options .Op Fl D Ar debug_options .Op Fl M Ar mountmap_entry .Op Fl P Ar program_number .Op Ar directory .Ar ... .Sh DESCRIPTION .Nm Amq provides a simple way of determining the current state of the .Xr amd 8 program. Communication is by .Tn RPC . Three modes of operation are supported by the current protocol. By default a list of mount points and auto-mounted filesystems is output. An alternative host can be specified using the .Fl h option. .Pp If directory names are given, as output by default, then per-filesystem information is displayed. .Sh OPTIONS .Bl -tag -width Ds .It Fl f Request automounter to flush the internal caches. .It Fl h Ar hostname Query alternate host .Ar hostname . By default the local host is used. In an .Tn HP-UX cluster, the root server is queried by default, since that is the system on which the automounter is normally run. .It Fl l Ar log_file Tell amd to use .Ar log_file as the log file name. For security reasons, this must be the same log file which .Nm amd used when started. This option is therefore only useful to refresh .Nm amd Ns \'s open file handle on the log file, so that it can be rotated and compressed via daily cron jobs. .It Fl m Request the automounter to provide a list of mounted filesystems, including the number of references to each filesystem and any error which occurred while mounting. .It Fl p Return the process ID of the remote or locally running .Nm amd . Useful when you need to send a signal to the local .Nm amd process, and would rather not have to search through the process table. This option is used in the .Pa ctl-amd script. .It Fl s Request the automounter to provide system-wide mount statistics. .It Fl u Request the automounter to unmount the named filesystems instead of providing information about them. Unmounts are requested, not forced. They merely cause the mounted filesystem to timeout, which will be picked up by .Nm amd Ns \'s main scheduler thus causing the normal timeout action to be taken. .It Fl v Request the automounter to provide version information. This is a subset of the information provided by .Nm amd Ns \'s Fl v option. .It Fl x Ar log_options Ask the automounter to use the logging options specified in .Ar log_options from now on. .It Fl D Ar log_options Ask the automounter to use the debugging options specified in .Ar debug_options from now on. .It Fl M Pass a mount map entry to .Nm amd and wait for it to be evaluated, possibly causing a mount. This option is highly insecure. By default, .Nm amd and .Nm amq do not support it. It is necessary to configure .Nm am-utils with .Ar --enable-amq-mount to enable this option. .It Fl P Ar program_number Contact an alternate running .Nm amd that had registered itself on a different RPC .Ar program_number and apply all other operations to that instance of the automounter. This is useful when running multiple copies of .Nm amd , and need to manage each one separately. If not specified, .Nm amq will use the default program number for .Nm amd , 300019. For security reasons, the only alternate program numbers .Nm amd can use range from 300019 to 300029, inclusive. .It Fl T Contact .Nm amd using the TCP transport only. Normally .Nm amq will try TCP, and if that fails, will try UDP. .It Fl U Contact .Nm amd using UDP (connectionless) transport only. Normally .Nm amq will try TCP, and if that fails, will try UDP. .El .Sh FILES .Bl -tag -width amq.x -compact .It Pa amq.x .Tn RPC protocol description. .El .Sh CAVEATS .Nm Amq uses a Sun registered .Tn RPC program number (300019 decimal) which may not be in the .Pa /etc/rpc database. .Sh SEE ALSO .Xr amd.conf 5 , .Xr amd 8 .Sh AUTHORS .An Jan-Simon Pendry Aq jsp@doc.ic.ac.uk , Department of Computing, Imperial College, London, UK. .Pp .An Erez Zadok Aq ezk@cs.columbia.edu , Department of Computer Science, Columbia University, New York, USA. .Pp .An Other authors and contributors to .Nm am-utils are listed in the .Nm AUTHORS file distributed with .Nm am-utils . .Sh HISTORY .Nm Amq -first appeared in 4.4BSD. +first appeared in +.Bx 4.4 . Index: head/contrib/telnet/telnetd/telnetd.8 =================================================================== --- head/contrib/telnet/telnetd/telnetd.8 (revision 81621) +++ head/contrib/telnet/telnetd/telnetd.8 (revision 81622) @@ -1,616 +1,619 @@ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. 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. .\" .\" @(#)telnetd.8 8.4 (Berkeley) 6/1/94 .\" $FreeBSD$ .\" .Dd January 27, 2000 .Dt TELNETD 8 .Os .Sh NAME .Nm telnetd .Nd DARPA .Tn TELNET protocol server .Sh SYNOPSIS .Nm /usr/libexec/telnetd .Op Fl BUhlkns .Op Fl D Ar debugmode .Op Fl I Ns Ar initid .Op Fl S Ar tos .Op Fl X Ar authtype .Op Fl a Ar authmode .Op Fl edebug .Op Fl p Ar loginprog .Op Fl r Ns Ar lowpty-highpty .Op Fl u Ar len .Op Fl debug Op Ar port .Sh DESCRIPTION The .Nm command is a server which supports the .Tn DARPA standard .Tn TELNET virtual terminal protocol. .Nm Telnetd is normally invoked by the internet server (see .Xr inetd 8 ) for requests to connect to the .Tn TELNET port as indicated by the .Pa /etc/services file (see .Xr services 5 ) . The .Fl debug option may be used to start up .Nm manually, instead of through .Xr inetd 8 . If started up this way, .Ar port may be specified to run .Nm on an alternate .Tn TCP port number. .Pp The .Nm command accepts the following options: .Bl -tag -width indent .It Fl a Ar authmode This option may be used for specifying what mode should be used for authentication. Note that this option is only useful if .Nm has been compiled with support for the .Dv AUTHENTICATION option. There are several valid values for .Ar authmode : .Bl -tag -width debug .It Cm debug Turn on authentication debugging code. .It Cm user Only allow connections when the remote user can provide valid authentication information to identify the remote user, and is allowed access to the specified account without providing a password. .It Cm valid Only allow connections when the remote user can provide valid authentication information to identify the remote user. The .Xr login 1 command will provide any additional user verification needed if the remote user is not allowed automatic access to the specified account. .It Cm other Only allow connections that supply some authentication information. This option is currently not supported by any of the existing authentication mechanisms, and is thus the same as specifying .Fl a .Cm valid . .It Cm none This is the default state. Authentication information is not required. If no or insufficient authentication information is provided, then the .Xr login 1 program will provide the necessary user verification. .It Cm off Disable the authentication code. All user verification will happen through the .Xr login 1 program. .El .It Fl B Specify bftp server mode. In this mode, .Nm causes login to start a .Xr bftp 1 session rather than the user's normal shell. In bftp daemon mode normal logins are not supported, and it must be used on a port other than the normal .Tn TELNET port. .It Fl D Ar debugmode This option may be used for debugging purposes. This allows .Nm to print out debugging information to the connection, allowing the user to see what .Nm is doing. There are several possible values for .Ar debugmode : .Bl -tag -width exercise .It Cm options Print information about the negotiation of .Tn TELNET options. .It Cm report Print the .Cm options information, plus some additional information about what processing is going on. .It Cm netdata Display the data stream received by .Nm . .It Cm ptydata Display data written to the pty. .It Cm exercise Has not been implemented yet. .El .It Fl debug Enable debugging on each socket created by .Nm (see .Dv SO_DEBUG in .Xr socket 2 ) . .It Fl edebug If .Nm has been compiled with support for data encryption, then the .Fl edebug option may be used to enable encryption debugging code. .It Fl p Ar loginprog Specify an alternate .Xr login 1 command to run to complete the login. The alternate command must understand the same command arguments as the standard login. .It Fl h Disable the printing of host-specific information before login has been completed. .It Fl I Ar initid This option is only applicable to .Tn UNICOS systems prior to 7.0. It specifies the .Dv ID from .Pa /etc/inittab to use when init starts login sessions. The default .Dv ID is .Dv fe . .It Fl k This option is only useful if .Nm has been compiled with both linemode and kludge linemode support. If the .Fl k option is specified, then if the remote client does not support the .Dv LINEMODE option, then .Nm will operate in character at a time mode. It will still support kludge linemode, but will only go into kludge linemode if the remote client requests it. (This is done by the client sending .Dv DONT SUPPRESS-GO-AHEAD and .Dv DONT ECHO . ) The .Fl k option is most useful when there are remote clients that do not support kludge linemode, but pass the heuristic (if they respond with .Dv WILL TIMING-MARK in response to a .Dv DO TIMING-MARK ) for kludge linemode support. .It Fl l Specify line mode. Try to force clients to use line- at-a-time mode. If the .Dv LINEMODE option is not supported, it will go into kludge linemode. .It Fl n Disable .Dv TCP keep-alives. Normally .Nm enables the .Tn TCP keep-alive mechanism to probe connections that have been idle for some period of time to determine if the client is still there, so that idle connections from machines that have crashed or can no longer be reached may be cleaned up. .It Fl r Ar lowpty-highpty This option is only enabled when .Nm is compiled for .Dv UNICOS . It specifies an inclusive range of pseudo-terminal devices to use. If the system has sysconf variable .Dv _SC_CRAY_NPTY configured, the default pty search range is 0 to .Dv _SC_CRAY_NPTY ; otherwise, the default range is 0 to 128. Either .Ar lowpty or .Ar highpty may be omitted to allow changing either end of the search range. If .Ar lowpty is omitted, the - character is still required so that .Nm can differentiate .Ar highpty from .Ar lowpty . .It Fl s This option is only enabled if .Nm is compiled with support for .Tn SecurID cards. It causes the .Fl s option to be passed on to .Xr login 1 , and thus is only useful if .Xr login 1 supports the .Fl s flag to indicate that only .Tn SecurID validated logins are allowed, and is usually useful for controlling remote logins from outside of a firewall. .It Fl S Ar tos .It Fl u Ar len This option is used to specify the size of the field in the .Dv utmp structure that holds the remote host name. If the resolved host name is longer than .Ar len , the dotted decimal value will be used instead. This allows hosts with very long host names that overflow this field to still be uniquely identified. Specifying .Fl u0 indicates that only dotted decimal addresses should be put into the .Pa utmp file. .It Fl U This option causes .Nm to refuse connections from addresses that cannot be mapped back into a symbolic name via the .Xr gethostbyaddr 3 routine. .It Fl X Ar authtype This option is only valid if .Nm has been built with support for the authentication option. It disables the use of .Ar authtype authentication, and can be used to temporarily disable a specific authentication type without having to recompile .Nm . .El .Pp .Nm Telnetd operates by allocating a pseudo-terminal device (see .Xr pty 4 ) for a client, then creating a login process which has the slave side of the pseudo-terminal as .Dv stdin , .Dv stdout and .Dv stderr . .Nm Telnetd manipulates the master side of the pseudo-terminal, implementing the .Tn TELNET protocol and passing characters between the remote client and the login process. .Pp When a .Tn TELNET session is started up, .Nm sends .Tn TELNET options to the client side indicating a willingness to do the following .Tn TELNET options, which are described in more detail below: .Bd -literal -offset indent DO AUTHENTICATION WILL ENCRYPT DO TERMINAL TYPE DO TSPEED DO XDISPLOC DO NEW-ENVIRON DO ENVIRON WILL SUPPRESS GO AHEAD DO ECHO DO LINEMODE DO NAWS WILL STATUS DO LFLOW DO TIMING-MARK .Ed .Pp The pseudo-terminal allocated to the client is configured to operate in .Dq cooked mode, and with .Dv XTABS and .Dv CRMOD enabled (see .Xr tty 4 ) . .Pp .Nm Telnetd has support for enabling locally the following .Tn TELNET options: .Bl -tag -width "DO AUTHENTICATION" .It "WILL ECHO" When the .Dv LINEMODE option is enabled, a .Dv WILL ECHO or .Dv WONT ECHO will be sent to the client to indicate the current state of terminal echoing. When terminal echo is not desired, a .Dv WILL ECHO is sent to indicate that .Nm will take care of echoing any data that needs to be echoed to the terminal, and then nothing is echoed. When terminal echo is desired, a .Dv WONT ECHO is sent to indicate that .Nm will not be doing any terminal echoing, so the client should do any terminal echoing that is needed. .It "WILL BINARY" Indicate that the client is willing to send a 8 bits of data, rather than the normal 7 bits of the Network Virtual Terminal. .It "WILL SGA" Indicate that it will not be sending .Dv IAC GA , go ahead, commands. .It "WILL STATUS" Indicate a willingness to send the client, upon request, of the current status of all .Tn TELNET options. .It "WILL TIMING-MARK" Whenever a .Dv DO TIMING-MARK command is received, it is always responded to with a .Dv WILL TIMING-MARK .It "WILL LOGOUT" When a .Dv DO LOGOUT is received, a .Dv WILL LOGOUT is sent in response, and the .Tn TELNET session is shut down. .It "WILL ENCRYPT" Only sent if .Nm is compiled with support for data encryption, and indicates a willingness to decrypt the data stream. .El .Pp .Nm Telnetd has support for enabling remotely the following .Tn TELNET options: .Bl -tag -width "DO AUTHENTICATION" .It "DO BINARY" Sent to indicate that .Nm is willing to receive an 8 bit data stream. .It "DO LFLOW" Requests that the client handle flow control characters remotely. .It "DO ECHO" -This is not really supported, but is sent to identify a 4.2BSD +This is not really supported, but is sent to identify a +.Bx 4.2 .Xr telnet 1 client, which will improperly respond with .Dv WILL ECHO . If a .Dv WILL ECHO is received, a .Dv DONT ECHO will be sent in response. .It "DO TERMINAL-TYPE" Indicate a desire to be able to request the name of the type of terminal that is attached to the client side of the connection. .It "DO SGA" Indicate that it does not need to receive .Dv IAC GA , the go ahead command. .It "DO NAWS" Requests that the client inform the server when the window (display) size changes. .It "DO TERMINAL-SPEED" Indicate a desire to be able to request information about the speed of the serial line to which the client is attached. .It "DO XDISPLOC" Indicate a desire to be able to request the name of the X Window System display that is associated with the telnet client. .It "DO NEW-ENVIRON" Indicate a desire to be able to request environment variable information, as described in RFC 1572. .It "DO ENVIRON" Indicate a desire to be able to request environment variable information, as described in RFC 1408. .It "DO LINEMODE" Only sent if .Nm is compiled with support for linemode, and requests that the client do line by line processing. .It "DO TIMING-MARK" Only sent if .Nm is compiled with support for both linemode and kludge linemode, and the client responded with .Dv WONT LINEMODE . If the client responds with .Dv WILL TM , the it is assumed that the client supports kludge linemode. Note that the .Op Fl k option can be used to disable this. .It "DO AUTHENTICATION" Only sent if .Nm is compiled with support for authentication, and indicates a willingness to receive authentication information for automatic login. .It "DO ENCRYPT" Only sent if .Nm is compiled with support for data encryption, and indicates a willingness to decrypt the data stream. .El .Sh FILES .Bl -tag -width /usr/ucb/bftp -compact .It Pa /etc/services .It Pa /etc/inittab (UNICOS systems only) .It Pa /etc/iptos (if supported) .It Pa /usr/ucb/bftp (if supported) .El .Sh "SEE ALSO" .Xr bftp 1 , .Xr login 1 , .Xr telnet 1 (if supported) .Sh STANDARDS .Bl -tag -compact -width RFC-1572 .It Cm RFC-854 .Tn TELNET PROTOCOL SPECIFICATION .It Cm RFC-855 TELNET OPTION SPECIFICATIONS .It Cm RFC-856 TELNET BINARY TRANSMISSION .It Cm RFC-857 TELNET ECHO OPTION .It Cm RFC-858 TELNET SUPPRESS GO AHEAD OPTION .It Cm RFC-859 TELNET STATUS OPTION .It Cm RFC-860 TELNET TIMING MARK OPTION .It Cm RFC-861 TELNET EXTENDED OPTIONS - LIST OPTION .It Cm RFC-885 TELNET END OF RECORD OPTION .It Cm RFC-1073 Telnet Window Size Option .It Cm RFC-1079 Telnet Terminal Speed Option .It Cm RFC-1091 Telnet Terminal-Type Option .It Cm RFC-1096 Telnet X Display Location Option .It Cm RFC-1123 Requirements for Internet Hosts -- Application and Support .It Cm RFC-1184 Telnet Linemode Option .It Cm RFC-1372 Telnet Remote Flow Control Option .It Cm RFC-1416 Telnet Authentication Option .It Cm RFC-1411 Telnet Authentication: Kerberos Version 4 .It Cm RFC-1412 Telnet Authentication: SPX .It Cm RFC-1571 Telnet Environment Option Interoperability Issues .It Cm RFC-1572 Telnet Environment Option .El .Sh BUGS Some .Tn TELNET commands are only partially implemented. .Pp -Because of bugs in the original 4.2 BSD +Because of bugs in the original +.Bx 4.2 .Xr telnet 1 , .Nm performs some dubious protocol exchanges to try to discover if the remote -client is, in fact, a 4.2 BSD +client is, in fact, a +.Bx 4.2 .Xr telnet 1 . .Pp Binary mode has no common interpretation except between similar operating systems (Unix in this case). .Pp The terminal type name received from the remote client is converted to lower case. .Pp .Nm Telnetd never sends .Tn TELNET .Dv IAC GA (go ahead) commands. .Sh HISTORY IPv6 support was added by WIDE/KAME project. Index: head/crypto/telnet/telnetd/telnetd.8 =================================================================== --- head/crypto/telnet/telnetd/telnetd.8 (revision 81621) +++ head/crypto/telnet/telnetd/telnetd.8 (revision 81622) @@ -1,616 +1,619 @@ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. 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. .\" .\" @(#)telnetd.8 8.4 (Berkeley) 6/1/94 .\" $FreeBSD$ .\" .Dd January 27, 2000 .Dt TELNETD 8 .Os .Sh NAME .Nm telnetd .Nd DARPA .Tn TELNET protocol server .Sh SYNOPSIS .Nm /usr/libexec/telnetd .Op Fl BUhlkns .Op Fl D Ar debugmode .Op Fl I Ns Ar initid .Op Fl S Ar tos .Op Fl X Ar authtype .Op Fl a Ar authmode .Op Fl edebug .Op Fl p Ar loginprog .Op Fl r Ns Ar lowpty-highpty .Op Fl u Ar len .Op Fl debug Op Ar port .Sh DESCRIPTION The .Nm command is a server which supports the .Tn DARPA standard .Tn TELNET virtual terminal protocol. .Nm Telnetd is normally invoked by the internet server (see .Xr inetd 8 ) for requests to connect to the .Tn TELNET port as indicated by the .Pa /etc/services file (see .Xr services 5 ) . The .Fl debug option may be used to start up .Nm manually, instead of through .Xr inetd 8 . If started up this way, .Ar port may be specified to run .Nm on an alternate .Tn TCP port number. .Pp The .Nm command accepts the following options: .Bl -tag -width indent .It Fl a Ar authmode This option may be used for specifying what mode should be used for authentication. Note that this option is only useful if .Nm has been compiled with support for the .Dv AUTHENTICATION option. There are several valid values for .Ar authmode : .Bl -tag -width debug .It Cm debug Turn on authentication debugging code. .It Cm user Only allow connections when the remote user can provide valid authentication information to identify the remote user, and is allowed access to the specified account without providing a password. .It Cm valid Only allow connections when the remote user can provide valid authentication information to identify the remote user. The .Xr login 1 command will provide any additional user verification needed if the remote user is not allowed automatic access to the specified account. .It Cm other Only allow connections that supply some authentication information. This option is currently not supported by any of the existing authentication mechanisms, and is thus the same as specifying .Fl a .Cm valid . .It Cm none This is the default state. Authentication information is not required. If no or insufficient authentication information is provided, then the .Xr login 1 program will provide the necessary user verification. .It Cm off Disable the authentication code. All user verification will happen through the .Xr login 1 program. .El .It Fl B Specify bftp server mode. In this mode, .Nm causes login to start a .Xr bftp 1 session rather than the user's normal shell. In bftp daemon mode normal logins are not supported, and it must be used on a port other than the normal .Tn TELNET port. .It Fl D Ar debugmode This option may be used for debugging purposes. This allows .Nm to print out debugging information to the connection, allowing the user to see what .Nm is doing. There are several possible values for .Ar debugmode : .Bl -tag -width exercise .It Cm options Print information about the negotiation of .Tn TELNET options. .It Cm report Print the .Cm options information, plus some additional information about what processing is going on. .It Cm netdata Display the data stream received by .Nm . .It Cm ptydata Display data written to the pty. .It Cm exercise Has not been implemented yet. .El .It Fl debug Enable debugging on each socket created by .Nm (see .Dv SO_DEBUG in .Xr socket 2 ) . .It Fl edebug If .Nm has been compiled with support for data encryption, then the .Fl edebug option may be used to enable encryption debugging code. .It Fl p Ar loginprog Specify an alternate .Xr login 1 command to run to complete the login. The alternate command must understand the same command arguments as the standard login. .It Fl h Disable the printing of host-specific information before login has been completed. .It Fl I Ar initid This option is only applicable to .Tn UNICOS systems prior to 7.0. It specifies the .Dv ID from .Pa /etc/inittab to use when init starts login sessions. The default .Dv ID is .Dv fe . .It Fl k This option is only useful if .Nm has been compiled with both linemode and kludge linemode support. If the .Fl k option is specified, then if the remote client does not support the .Dv LINEMODE option, then .Nm will operate in character at a time mode. It will still support kludge linemode, but will only go into kludge linemode if the remote client requests it. (This is done by the client sending .Dv DONT SUPPRESS-GO-AHEAD and .Dv DONT ECHO . ) The .Fl k option is most useful when there are remote clients that do not support kludge linemode, but pass the heuristic (if they respond with .Dv WILL TIMING-MARK in response to a .Dv DO TIMING-MARK ) for kludge linemode support. .It Fl l Specify line mode. Try to force clients to use line- at-a-time mode. If the .Dv LINEMODE option is not supported, it will go into kludge linemode. .It Fl n Disable .Dv TCP keep-alives. Normally .Nm enables the .Tn TCP keep-alive mechanism to probe connections that have been idle for some period of time to determine if the client is still there, so that idle connections from machines that have crashed or can no longer be reached may be cleaned up. .It Fl r Ar lowpty-highpty This option is only enabled when .Nm is compiled for .Dv UNICOS . It specifies an inclusive range of pseudo-terminal devices to use. If the system has sysconf variable .Dv _SC_CRAY_NPTY configured, the default pty search range is 0 to .Dv _SC_CRAY_NPTY ; otherwise, the default range is 0 to 128. Either .Ar lowpty or .Ar highpty may be omitted to allow changing either end of the search range. If .Ar lowpty is omitted, the - character is still required so that .Nm can differentiate .Ar highpty from .Ar lowpty . .It Fl s This option is only enabled if .Nm is compiled with support for .Tn SecurID cards. It causes the .Fl s option to be passed on to .Xr login 1 , and thus is only useful if .Xr login 1 supports the .Fl s flag to indicate that only .Tn SecurID validated logins are allowed, and is usually useful for controlling remote logins from outside of a firewall. .It Fl S Ar tos .It Fl u Ar len This option is used to specify the size of the field in the .Dv utmp structure that holds the remote host name. If the resolved host name is longer than .Ar len , the dotted decimal value will be used instead. This allows hosts with very long host names that overflow this field to still be uniquely identified. Specifying .Fl u0 indicates that only dotted decimal addresses should be put into the .Pa utmp file. .It Fl U This option causes .Nm to refuse connections from addresses that cannot be mapped back into a symbolic name via the .Xr gethostbyaddr 3 routine. .It Fl X Ar authtype This option is only valid if .Nm has been built with support for the authentication option. It disables the use of .Ar authtype authentication, and can be used to temporarily disable a specific authentication type without having to recompile .Nm . .El .Pp .Nm Telnetd operates by allocating a pseudo-terminal device (see .Xr pty 4 ) for a client, then creating a login process which has the slave side of the pseudo-terminal as .Dv stdin , .Dv stdout and .Dv stderr . .Nm Telnetd manipulates the master side of the pseudo-terminal, implementing the .Tn TELNET protocol and passing characters between the remote client and the login process. .Pp When a .Tn TELNET session is started up, .Nm sends .Tn TELNET options to the client side indicating a willingness to do the following .Tn TELNET options, which are described in more detail below: .Bd -literal -offset indent DO AUTHENTICATION WILL ENCRYPT DO TERMINAL TYPE DO TSPEED DO XDISPLOC DO NEW-ENVIRON DO ENVIRON WILL SUPPRESS GO AHEAD DO ECHO DO LINEMODE DO NAWS WILL STATUS DO LFLOW DO TIMING-MARK .Ed .Pp The pseudo-terminal allocated to the client is configured to operate in .Dq cooked mode, and with .Dv XTABS and .Dv CRMOD enabled (see .Xr tty 4 ) . .Pp .Nm Telnetd has support for enabling locally the following .Tn TELNET options: .Bl -tag -width "DO AUTHENTICATION" .It "WILL ECHO" When the .Dv LINEMODE option is enabled, a .Dv WILL ECHO or .Dv WONT ECHO will be sent to the client to indicate the current state of terminal echoing. When terminal echo is not desired, a .Dv WILL ECHO is sent to indicate that .Nm will take care of echoing any data that needs to be echoed to the terminal, and then nothing is echoed. When terminal echo is desired, a .Dv WONT ECHO is sent to indicate that .Nm will not be doing any terminal echoing, so the client should do any terminal echoing that is needed. .It "WILL BINARY" Indicate that the client is willing to send a 8 bits of data, rather than the normal 7 bits of the Network Virtual Terminal. .It "WILL SGA" Indicate that it will not be sending .Dv IAC GA , go ahead, commands. .It "WILL STATUS" Indicate a willingness to send the client, upon request, of the current status of all .Tn TELNET options. .It "WILL TIMING-MARK" Whenever a .Dv DO TIMING-MARK command is received, it is always responded to with a .Dv WILL TIMING-MARK .It "WILL LOGOUT" When a .Dv DO LOGOUT is received, a .Dv WILL LOGOUT is sent in response, and the .Tn TELNET session is shut down. .It "WILL ENCRYPT" Only sent if .Nm is compiled with support for data encryption, and indicates a willingness to decrypt the data stream. .El .Pp .Nm Telnetd has support for enabling remotely the following .Tn TELNET options: .Bl -tag -width "DO AUTHENTICATION" .It "DO BINARY" Sent to indicate that .Nm is willing to receive an 8 bit data stream. .It "DO LFLOW" Requests that the client handle flow control characters remotely. .It "DO ECHO" -This is not really supported, but is sent to identify a 4.2BSD +This is not really supported, but is sent to identify a +.Bx 4.2 .Xr telnet 1 client, which will improperly respond with .Dv WILL ECHO . If a .Dv WILL ECHO is received, a .Dv DONT ECHO will be sent in response. .It "DO TERMINAL-TYPE" Indicate a desire to be able to request the name of the type of terminal that is attached to the client side of the connection. .It "DO SGA" Indicate that it does not need to receive .Dv IAC GA , the go ahead command. .It "DO NAWS" Requests that the client inform the server when the window (display) size changes. .It "DO TERMINAL-SPEED" Indicate a desire to be able to request information about the speed of the serial line to which the client is attached. .It "DO XDISPLOC" Indicate a desire to be able to request the name of the X Window System display that is associated with the telnet client. .It "DO NEW-ENVIRON" Indicate a desire to be able to request environment variable information, as described in RFC 1572. .It "DO ENVIRON" Indicate a desire to be able to request environment variable information, as described in RFC 1408. .It "DO LINEMODE" Only sent if .Nm is compiled with support for linemode, and requests that the client do line by line processing. .It "DO TIMING-MARK" Only sent if .Nm is compiled with support for both linemode and kludge linemode, and the client responded with .Dv WONT LINEMODE . If the client responds with .Dv WILL TM , the it is assumed that the client supports kludge linemode. Note that the .Op Fl k option can be used to disable this. .It "DO AUTHENTICATION" Only sent if .Nm is compiled with support for authentication, and indicates a willingness to receive authentication information for automatic login. .It "DO ENCRYPT" Only sent if .Nm is compiled with support for data encryption, and indicates a willingness to decrypt the data stream. .El .Sh FILES .Bl -tag -width /usr/ucb/bftp -compact .It Pa /etc/services .It Pa /etc/inittab (UNICOS systems only) .It Pa /etc/iptos (if supported) .It Pa /usr/ucb/bftp (if supported) .El .Sh "SEE ALSO" .Xr bftp 1 , .Xr login 1 , .Xr telnet 1 (if supported) .Sh STANDARDS .Bl -tag -compact -width RFC-1572 .It Cm RFC-854 .Tn TELNET PROTOCOL SPECIFICATION .It Cm RFC-855 TELNET OPTION SPECIFICATIONS .It Cm RFC-856 TELNET BINARY TRANSMISSION .It Cm RFC-857 TELNET ECHO OPTION .It Cm RFC-858 TELNET SUPPRESS GO AHEAD OPTION .It Cm RFC-859 TELNET STATUS OPTION .It Cm RFC-860 TELNET TIMING MARK OPTION .It Cm RFC-861 TELNET EXTENDED OPTIONS - LIST OPTION .It Cm RFC-885 TELNET END OF RECORD OPTION .It Cm RFC-1073 Telnet Window Size Option .It Cm RFC-1079 Telnet Terminal Speed Option .It Cm RFC-1091 Telnet Terminal-Type Option .It Cm RFC-1096 Telnet X Display Location Option .It Cm RFC-1123 Requirements for Internet Hosts -- Application and Support .It Cm RFC-1184 Telnet Linemode Option .It Cm RFC-1372 Telnet Remote Flow Control Option .It Cm RFC-1416 Telnet Authentication Option .It Cm RFC-1411 Telnet Authentication: Kerberos Version 4 .It Cm RFC-1412 Telnet Authentication: SPX .It Cm RFC-1571 Telnet Environment Option Interoperability Issues .It Cm RFC-1572 Telnet Environment Option .El .Sh BUGS Some .Tn TELNET commands are only partially implemented. .Pp -Because of bugs in the original 4.2 BSD +Because of bugs in the original +.Bx 4.2 .Xr telnet 1 , .Nm performs some dubious protocol exchanges to try to discover if the remote -client is, in fact, a 4.2 BSD +client is, in fact, a +.Bx 4.2 .Xr telnet 1 . .Pp Binary mode has no common interpretation except between similar operating systems (Unix in this case). .Pp The terminal type name received from the remote client is converted to lower case. .Pp .Nm Telnetd never sends .Tn TELNET .Dv IAC GA (go ahead) commands. .Sh HISTORY IPv6 support was added by WIDE/KAME project. Index: head/games/fortune/strfile/strfile.8 =================================================================== --- head/games/fortune/strfile/strfile.8 (revision 81621) +++ head/games/fortune/strfile/strfile.8 (revision 81622) @@ -1,156 +1,157 @@ .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" .\" This code is derived from software contributed to Berkeley by .\" Ken Arnold. .\" .\" 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. .\" .\" @(#)strfile.8 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" .Dd June 9, 1993 .Dt STRFILE 8 .Os .Sh NAME .Nm strfile , .Nm unstr .Nd "create a random access file for storing strings" .Sh SYNOPSIS .Nm .Op Fl iorsx .Op Fl c Ar char .Ar source_file .Op Ar output_file .Nm unstr .Ar source_file .Sh DESCRIPTION .Nm Strfile reads a file containing groups of lines separated by a line containing a single percent .Ql \&% sign and creates a data file which contains a header structure and a table of file offsets for each group of lines. This allows random access of the strings. .Pp The output file, if not specified on the command line, is named .Ar source_file Ns Sy .dat . .Pp The options are as follows: .Bl -tag -width "-c char" .It Fl C Flag the file as containing comments. This option cases the .Dv STR_COMMENTS bit in the header .Ar str_flags field to be set. Comments are designated by two delimiter characters at the beginning of the line, though strfile does not give any special treatment to comment lines. .It Fl c Ar char Change the delimiting character from the percent sign to .Ar char . .It Fl i Ignore case when ordering the strings. .It Fl o Order the strings in alphabetical order. The offset table will be sorted in the alphabetical order of the groups of lines referenced. Any initial non-alphanumeric characters are ignored. This option causes the .Dv STR_ORDERED bit in the header .Ar str_flags field to be set. .It Fl r Randomize access to the strings. Entries in the offset table will be randomly ordered. This option causes the .Dv STR_RANDOM bit in the header .Ar str_flags field to be set. .It Fl s Run silently; don't give a summary message when finished. .It Fl x Note that each alphabetic character in the groups of lines is rotated 13 positions in a simple caesar cypher. This option causes the .Dv STR_ROTATED bit in the header .Ar str_flags field to be set. .El .Pp The format of the header is: .Bd -literal #define VERSION 1 unsigned long str_version; /* version number */ unsigned long str_numstr; /* # of strings in the file */ unsigned long str_longlen; /* length of longest string */ unsigned long str_shortlen; /* length of shortest string */ #define STR_RANDOM 0x1 /* randomized pointers */ #define STR_ORDERED 0x2 /* ordered pointers */ #define STR_ROTATED 0x4 /* rot-13'd text */ unsigned long str_flags; /* bit field for flags */ char str_delim; /* delimiting character */ .Ed .Pp All fields are written in network byte order. .Pp The purpose of .Nm unstr is to undo the work of .Nm . It prints out the strings contained in the file .Ar source_file in the order that they are listed in the header file .Ar source_file Ns Pa .dat to standard output. It is possible to create sorted versions of input files by using .Fl o when .Nm is run and then using .Nm unstr to dump them out in the table order. .Sh SEE ALSO .Xr byteorder 3 , .Xr fortune 6 .Sh FILES .Bl -tag -width strfile.dat -compact .It Pa strfile.dat default output file. .El .Sh HISTORY The .Nm -utility first appeared in 4.4BSD. +utility first appeared in +.Bx 4.4 . Index: head/gnu/usr.bin/ld/ld.1 =================================================================== --- head/gnu/usr.bin/ld/ld.1 (revision 81621) +++ head/gnu/usr.bin/ld/ld.1 (revision 81622) @@ -1,294 +1,295 @@ .\" .\" Copyright (c) 1993 Paul Kranenburg .\" 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 Paul Kranenburg. .\" 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 ``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 14, 1993 .Dt LD 1 .Os .Sh NAME .Nm ld .Nd link editor .Sh SYNOPSIS .Nm .Op Fl fMNnrSstXxz .Bk -words .Op Fl A Ar symbol-file .Op Fl assert Ar keyword .Op Fl B Ns Ar linkmode .Op Fl D Ar datasize .Op Fl d Ar c .Op Fl d Ar p .Op Fl e Ar entry .Op Fl l Ns Ar library-specifier .Op Fl L Ns Ar library-search-path .Op Fl nostdlib .Op Fl O Ar filename .Op Fl o Ar filename .Op Fl R Ns Ar record-library-search-path .Op Fl T Ar address .Op Fl u Ar symbol .Op Fl V Ar shlib-version .Op Fl y Ar symbol .Ek .Sh DESCRIPTION .Nm combines the object and archive files given on the command line into a new object file. The output object file is either an executable program, a shared object suitable for loading at run-time, or an object file that can once again be processed by .Nm . Object files and archives are processed in the order given on the command line. .Pp The options are as follows: .Pp .Bl -tag -width indent .It Fl A Ar symbol-file The the symbol-file is taken as a base for link-editing the object files on the command line. .It Fl assert Ar keyword This option is here mainly for compatibility with SunOS .Nm . Most conditions which would cause a Sun assertion to fail will currently always cause error or warning messages from .Nm . The only keyword implemented by .Nm is .Ar pure-text , which generates a warning if a position independent object is being created and some of the files being linked are not position independent. .It Fl B Ns Ar dynamic Specifies that linking against dynamic libraries can take place. If a library specifier of the form -lx appears on the command line, .Nm searches for a library of the from libx.so.n.m (see the .Fl l option) according to the search rules in effect. If such a file can not be found a traditional archive is looked for. This options can appear anywhere on the command line and is complementary to .Fl B Ns Ar static . .It Fl B Ns Ar forcedynamic This is similar to .Fl B Ns Ar dynamic except that if no dynamic libraries are linked against, .Nm will still produce a dynamic executable. This is useful for programs which are static but still need to load dynamic objects at runtime. .It Fl B Ns Ar static The counterpart of .Fl B Ns Ar dynamic . This option turns off dynamic linking for all library specifiers until a .Fl B Ns Ar dynamic is once again given. Any explicitly mentioned shared object encountered on the command line while this option is in effect is flagged as an error. .It Fl B Ns Ar shareable Instructs the linker to build a shared object from the object files rather than a normal executable image. .It Fl B Ns Ar symbolic This option causes all symbolic references in the output to be resolved in this link-edit session. The only remaining run-time relocation requirements are .Em base-relative relocations, ie. translation with respect to the load address. Failure to resolve any symbolic reference causes an error to be reported. .It Fl B Ns Ar forcearchive Force all members of archives to be loaded, whether or not such members contribute a definition to any plain object files. Useful for making a shared library from an archive of PIC objects without having to unpack the archive. .It Fl B Ns Ar silly Search for .Em \.sa silly archive companions of shared objects. Useful for compatibility with version 3 shared objects. .It Fl D Ar data-size Set the size of the data segment. For sanity's sake, this should be larger than the cumulative data sizes of the input files. .It Fl d Ar c Force allocation of commons even producing relocatable output. .It Fl d Ar p Force alias definitions of procedure calls in non-PIC code. Useful to obtain shareable code in the presence of run-time relocations as such calls will be re-directed through the Procedure Linkage Table (see .Xr link 5 ) .It Fl e Ar entry-symbol Specifies the entry symbol for an executable. .It Fl f List the resolved paths of all the object files and libraries on the standard output, and exit. .It Fl L Ns Ar path Add .Ar path to the list of directories to search for libraries specified with the .Fl l option. .It Fl l Ns Ar lib-spec This option specifies a library to be considered for inclusion in the output. If the .Fl B Ns Ar dynamic option is in effect, a shared library of the form lib.so.m.n (where .Em m is the major, and .Em n is the minor version number, respectively) is searched for first. The library with the highest version found in the search path is selected. If no shared library is found or the .Fl B Ns Ar static options is in effect, an archive of the form lib.a is looked for in the library search path. .It Fl M Produce output about the mapping of segments of the input files and the values assigned to (global) symbols in the output file. .It Fl N Produce a .Dv OMAGIC output file. .It Fl n Produce a .Dv NMAGIC output file. .It Fl nostdlib Do not search the built-in path (usually .Dq /usr/lib ) for .Fl l specified libraries. .It Fl O Ar filename Specifies the name of the output file. The file is created as .Ar filename Ns Pa .tmp and when output is complete renamed to .Ar filename . .It Fl o Ar filename Specifies the name of the output file. Defaults to .Dq Pa a.out . .It Fl Q Produce a .Dv QMAGIC .Pq Fx Ns / Ns Tn BSDi Ns -i386 output file. This is the default. .It Fl r Produce relocatable object file, suitable for another pass through .Nm . .It Fl R Record the given path within the executable for run-time library search. This only applies to dynamically linked executables. .It Fl S Strip all debugger symbols from the output. .It Fl s Strip all symbols from the output. .It Fl T Specifies the start address of the text segment, with respect to which all input files will be relocated. .It Fl t Leave a trace of the input files as they are processed. .It Fl u Ar symbol Force .Ar symbol to be marked as undefined. Useful to force loading of an archive member in the absence of any other references to that member. .It Fl V Ar version Put the given version number into the output shared library (if one is created). Useful to make shared libraries compatible with other operating systems. E.g., SunOS 4.x libraries use version number 3. Defaults to 8. .It Fl X Discard local symbols in the input files that start with the letter .Dq L .It Fl x Discard all local symbols in the input files. .It Fl y Ar symbol Trace the manipulations inflicted on .Ar symbol .It Fl Z -Make a 386BSD +Make a +.Bx 386 .Dv ZMAGIC output file. .It Fl z Make a .Nx .Dv ZMAGIC output file. .El .Sh ENVIRONMENT .Nm utilizes the following environment variables: .Bl -tag -width "LD_LIBRARY_PATH" .It Ev LD_LIBRARY_PATH This colon-separated list of directories is inserted into the search path for libraries following any directories specified via .Fl L options and preceding the built-in path. .\" .It Ev LD_NOSTD_PATH .\" When set, do not search the built-in path for libraries. .\" This is an alternative to the .\" .Fl nostdlib .\" command-line flag. .El .Sh FILES .Sh SEE ALSO .Xr ldd 1 , .Xr rtld 1 , .Xr link 5 , .Xr ldconfig 8 .Sh CAVEATS An entry point must now explicitly be given if the output is intended to be a normal executable program. This was not the case for the previous version of .Nm . .Sh BUGS Shared objects are not properly checked for undefined symbols. .Pp Cascading of shared object defeats the .Dq -Bstatic option. .Pp All shared objects presented to .Nm are marked for run-time loading in the output file, even if no symbols are needed from them. .Sh HISTORY A .Nm command appeared in .At v1 . The shared library model employed by .Nm appeared first in SunOS 4.0 Index: head/gnu/usr.bin/ld/ld.1aout =================================================================== --- head/gnu/usr.bin/ld/ld.1aout (revision 81621) +++ head/gnu/usr.bin/ld/ld.1aout (revision 81622) @@ -1,294 +1,295 @@ .\" .\" Copyright (c) 1993 Paul Kranenburg .\" 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 Paul Kranenburg. .\" 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 ``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 14, 1993 .Dt LD 1 .Os .Sh NAME .Nm ld .Nd link editor .Sh SYNOPSIS .Nm ld .Op Fl fMNnrSstXxz .Bk -words .Op Fl A Ar symbol-file .Op Fl assert Ar keyword .Op Fl B Ns Ar linkmode .Op Fl D Ar datasize .Op Fl d Ar c .Op Fl d Ar p .Op Fl e Ar entry .Op Fl l Ns Ar library-specifier .Op Fl L Ns Ar library-search-path .Op Fl nostdlib .Op Fl O Ar filename .Op Fl o Ar filename .Op Fl R Ns Ar record-library-search-path .Op Fl T Ar address .Op Fl u Ar symbol .Op Fl V Ar shlib-version .Op Fl y Ar symbol .Ek .Sh DESCRIPTION .Nm combines the object and archive files given on the command line into a new object file. The output object file is either an executable program, a shared object suitable for loading at run-time, or an object file that can once again be processed by .Nm . Object files and archives are processed in the order given on the command line. .Pp The options are as follows: .Pp .Bl -tag -width indent .It Fl A Ar symbol-file The the symbol-file is taken as a base for link-editing the object files on the command line. .It Fl assert Ar keyword This option is here mainly for compatibility with SunOS .Nm . Most conditions which would cause a Sun assertion to fail will currently always cause error or warning messages from .Nm . The only keyword implemented by .Nm is .Nm pure-text , which generates a warning if a position independent object is being created and some of the files being linked are not position independent. .It Fl B Ns Ar dynamic Specifies that linking against dynamic libraries can take place. If a library specifier of the form -lx appears on the command line, .Nm searches for a library of the from libx.so.n.m (see the .Fl l option) according to the search rules in effect. If such a file can not be found a traditional archive is looked for. This options can appear anywhere on the command line and is complementary to .Fl B Ns Ar static . .It Fl B Ns Ar forcedynamic This is similar to .Fl B Ns Ar dynamic except that if no dynamic libraries are linked against, .Nm will still produce a dynamic executable. This is useful for programs which are static but still need to load dynamic objects at runtime. .It Fl B Ns Ar static The counterpart of .Fl B Ns Ar dynamic . This option turns off dynamic linking for all library specifiers until a .Fl B Ns Ar dynamic is once again given. Any explicitly mentioned shared object encountered on the command line while this option is in effect is flagged as an error. .It Fl B Ns Ar shareable Instructs the linker to build a shared object from the object files rather than a normal executable image. .It Fl B Ns Ar symbolic This option causes all symbolic references in the output to be resolved in this link-edit session. The only remaining run-time relocation requirements are .Em base-relative relocations, ie. translation with respect to the load address. Failure to resolve any symbolic reference causes an error to be reported. .It Fl B Ns Ar forcearchive Force all members of archives to be loaded, whether or not such members contribute a definition to any plain object files. Useful for making a shared library from an archive of PIC objects without having to unpack the archive. .It Fl B Ns Ar silly Search for .Em \.sa silly archive companions of shared objects. Useful for compatibility with version 3 shared objects. .It Fl D Ar data-size Set the size of the data segment. For sanity's sake, this should be larger than the cumulative data sizes of the input files. .It Fl d Ar c Force allocation of commons even producing relocatable output. .It Fl d Ar p Force alias definitions of procedure calls in non-PIC code. Useful to obtain shareable code in the presence of run-time relocations as such calls will be re-directed through the Procedure Linkage Table (see .Xr link 5 ) .It Fl e Ar entry-symbol Specifies the entry symbol for an executable. .It Fl f List the resolved paths of all the object files and libraries on the standard output, and exit. .It Fl L Ns Ar path Add .Ar path to the list of directories to search for libraries specified with the .Fl l option. .It Fl l Ns Ar lib-spec This option specifies a library to be considered for inclusion in the output. If the .Fl B Ns Ar dynamic option is in effect, a shared library of the form lib.so.m.n (where .Em m is the major, and .Em n is the minor version number, respectively) is searched for first. The library with the highest version found in the search path is selected. If no shared library is found or the .Fl B Ns Ar static options is in effect, an archive of the form lib.a is looked for in the library search path. .It Fl M Produce output about the mapping of segments of the input files and the values assigned to (global) symbols in the output file. .It Fl N Produce a .Dv OMAGIC output file. .It Fl n Produce a .Dv NMAGIC output file. .It Fl nostdlib Do not search the built-in path (usually .Dq /usr/lib ) for .Fl l specified libraries. .It Fl O Ar filename Specifies the name of the output file. The file is created as .Ar filename Ns Pa .tmp and when output is complete renamed to .Ar filename . .It Fl o Ar filename Specifies the name of the output file. Defaults to .Dq Pa a.out . .It Fl Q Produce a .Dv QMAGIC .Pq Fx , Bsx Ns -i386 output file. This is the default. .It Fl r Produce relocatable object file, suitable for another pass through .Nm . .It Fl R Record the given path within the executable for run-time library search. This only applies to dynamically linked executables. .It Fl S Strip all debugger symbols from the output. .It Fl s Strip all symbols from the output. .It Fl T Specifies the start address of the text segment, with respect to which all input files will be relocated. .It Fl t Leave a trace of the input files as they are processed. .It Fl u Ar symbol Force .Ar symbol to be marked as undefined. Useful to force loading of an archive member in the absence of any other references to that member. .It Fl V Ar version Put the given version number into the output shared library (if one is created). Useful to make shared libraries compatible with other operating systems. E.g., SunOS 4.x libraries use version number 3. Defaults to 8. .It Fl X Discard local symbols in the input files that start with the letter .Dq L .It Fl x Discard all local symbols in the input files. .It Fl y Ar symbol Trace the manipulations inflicted on .Ar symbol .It Fl Z -Make a 386BSD +Make a +.Bx 386 .Dv ZMAGIC output file. .It Fl z Make a .Nx .Dv ZMAGIC output file. .El .Sh ENVIRONMENT .Nm utilizes the following environment variables: .Bl -tag -width "LD_LIBRARY_PATH" .It Ev LD_LIBRARY_PATH This colon-separated list of directories is inserted into the search path for libraries following any directories specified via .Fl L options and preceding the built-in path. .\" .It Ev LD_NOSTD_PATH .\" When set, do not search the built-in path for libraries. .\" This is an alternative to the .\" .Fl nostdlib .\" command-line flag. .El .Sh FILES .Sh SEE ALSO .Xr ldd 1 , .Xr rtld 1 , .Xr link 5 , .Xr ldconfig 8 .Sh CAVEATS An entry point must now explicitly be given if the output is intended to be a normal executable program. This was not the case for the previous version of .Nm . .Sh BUGS Shared objects are not properly checked for undefined symbols. .Pp Cascading of shared object defeats the .Dq -Bstatic option. .Pp All shared objects presented to .Nm are marked for run-time loading in the output file, even if no symbols are needed from them. .Sh HISTORY A .Nm command appeared in .At v1 . The shared library model employed by .Nm appeared first in SunOS 4.0 Index: head/lib/libc/gen/getnetgrent.3 =================================================================== --- head/lib/libc/gen/getnetgrent.3 (revision 81621) +++ head/lib/libc/gen/getnetgrent.3 (revision 81622) @@ -1,132 +1,133 @@ .\" Copyright (c) 1992, 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. .\" .\" @(#)getnetgrent.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd June 4, 1993 .Dt GETNETGRENT 3 .Os .Sh NAME .Nm getnetgrent , .Nm innetgr , .Nm setnetgrent , .Nm endnetgrent .Nd netgroup database operations .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd #include .Ft int .Fn getnetgrent "char **host" "char **user" "char **domain" .Ft int .Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain" .Ft void .Fn setnetgrent "const char *netgroup" .Ft void .Fn endnetgrent void .Sh DESCRIPTION These functions operate on the netgroup database file .Pa /etc/netgroup which is described in .Xr netgroup 5 . The database defines a set of netgroups, each made up of one or more triples: .Bd -literal -offset indent (host, user, domain) .Ed that defines a combination of host, user and domain. Any of the three fields may be specified as ``wildcards'' that match any string. .Pp The function .Fn getnetgrent sets the three pointer arguments to the strings of the next member of the current netgroup. If any of the string pointers are .Sy (char *)0 that field is considered a wildcard. .Pp The functions .Fn setnetgrent and .Fn endnetgrent set the current netgroup and terminate the current netgroup respectively. If .Fn setnetgrent is called with a different netgroup than the previous call, an implicit .Fn endnetgrent is implied. .Fn Setnetgrent also sets the offset to the first member of the netgroup. .Pp The function .Fn innetgr searches for a match of all fields within the specified group. If any of the .Sy host , .Sy user , or .Sy domain arguments are .Sy (char *)0 those fields will match any string value in the netgroup member. .Sh RETURN VALUES The function .Fn getnetgrent returns 0 for ``no more netgroup members'' and 1 otherwise. The function .Fn innetgr returns 1 for a successful match and 0 otherwise. The functions .Fn setnetgrent and .Fn endnetgrent have no return value. .Sh FILES .Bl -tag -width /etc/netgroup -compact .It Pa /etc/netgroup netgroup database file .El .Sh SEE ALSO .Xr netgroup 5 .Sh COMPATIBILITY The netgroup members have three string fields to maintain compatibility with other vendor implementations, however it is not obvious what use the .Sy domain -string has within BSD. +string has within +.Bx . .Sh BUGS The function .Fn getnetgrent returns pointers to dynamically allocated data areas that are freed when the function .Fn endnetgrent is called. Index: head/lib/libc/sys/sigaction.2 =================================================================== --- head/lib/libc/sys/sigaction.2 (revision 81621) +++ head/lib/libc/sys/sigaction.2 (revision 81622) @@ -1,601 +1,611 @@ .\" Copyright (c) 1980, 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. .\" 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: @(#)sigaction.2 8.2 (Berkeley) 4/3/94 .\" $FreeBSD$ .\" .Dd April 3, 1994 .Dt SIGACTION 2 .Os .Sh NAME .Nm sigaction .Nd software signal facilities .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd #include .Bd -literal struct sigaction { union { void (*__sa_handler) __P((int)); void (*__sa_sigaction) __P((int, struct __siginfo *, void *)); } __sigaction_u; /* signal handler */ int sa_flags; /* see signal options below */ sigset_t sa_mask; /* signal mask to apply */ }; #define sa_handler __sigaction_u.__sa_handler #define sa_sigaction __sigaction_u.__sa_sigaction .Ed .Ft int .Fn sigaction "int sig" "const struct sigaction *act" "struct sigaction *oact" .Sh DESCRIPTION The system defines a set of signals that may be delivered to a process. Signal delivery resembles the occurrence of a hardware interrupt: the signal is normally blocked from further occurrence, the current process context is saved, and a new one is built. A process may specify a .Em handler to which a signal is delivered, or specify that a signal is to be .Em ignored . A process may also specify that a default action is to be taken by the system when a signal occurs. A signal may also be .Em blocked , in which case its delivery is postponed until it is .Em unblocked . The action to be taken on delivery is determined at the time of delivery. Normally, signal handlers execute on the current stack of the process. This may be changed, on a per-handler basis, so that signals are taken on a special .Em "signal stack" . .Pp Signal routines normally execute with the signal that caused their invocation .Em blocked , but other signals may yet occur. A global .Em "signal mask" defines the set of signals currently blocked from delivery to a process. The signal mask for a process is initialized from that of its parent (normally empty). It may be changed with a .Xr sigprocmask 2 call, or when a signal is delivered to the process. .Pp When a signal condition arises for a process, the signal is added to a set of signals pending for the process. If the signal is not currently .Em blocked by the process then it is delivered to the process. Signals may be delivered any time a process enters the operating system (e.g., during a system call, page fault or trap, or clock interrupt). If multiple signals are ready to be delivered at the same time, any signals that could be caused by traps are delivered first. Additional signals may be processed at the same time, with each appearing to interrupt the handlers for the previous signals before their first instructions. The set of pending signals is returned by the .Xr sigpending 2 function. When a caught signal is delivered, the current state of the process is saved, a new signal mask is calculated (as described below), and the signal handler is invoked. The call to the handler is arranged so that if the signal handling routine returns normally the process will resume execution in the context from before the signal's delivery. If the process wishes to resume in a different context, then it must arrange to restore the previous context itself. .Pp When a signal is delivered to a process a new signal mask is installed for the duration of the process' signal handler (or until a .Xr sigprocmask call is made). This mask is formed by taking the union of the current signal mask set, the signal to be delivered, and the signal mask associated with the handler to be invoked. .Pp .Fn Sigaction assigns an action for a signal specified by .Fa sig . If .Fa act is non-zero, it specifies an action .Pf ( Dv SIG_DFL , .Dv SIG_IGN , or a handler routine) and mask to be used when delivering the specified signal. If .Fa oact is non-zero, the previous handling information for the signal is returned to the user. .Pp Once a signal handler is installed, it normally remains installed until another .Fn sigaction call is made, or an .Xr execve 2 is performed. A signal-specific default action may be reset by setting .Fa sa_handler to .Dv SIG_DFL . The defaults are process termination, possibly with core dump; no action; stopping the process; or continuing the process. See the signal list below for each signal's default action. If .Fa sa_handler is .Dv SIG_DFL , the default action for the signal is to discard the signal, and if a signal is pending, the pending signal is discarded even if the signal is masked. If .Fa sa_handler is set to .Dv SIG_IGN current and pending instances of the signal are ignored and discarded. .Pp Options may be specified by setting .Em sa_flags . The meaning of the various bits is as follows: .Bl -tag -offset indent -width SA_RESETHANDXX .It Dv SA_NOCLDSTOP If this bit is set when installing a catching function for the .Dv SIGCHLD signal, the .Dv SIGCHLD signal will be generated only when a child process exits, not when a child process stops. .It Dv SA_NOCLDWAIT If this bit is set when calling .Fn sigaction for the .Dv SIGCHLD signal, the system will not create zombie processes when children of the calling process exit. If the calling process subsequently issues a .Xr wait 2 (or equivalent), it blocks until all of the calling process's child processes terminate, and then returns a value of -1 with errno set to .Er ECHILD . .It Dv SA_ONSTACK If this bit is set, the system will deliver the signal to the process on a .Em "signal stack" , specified with .Xr sigaltstack 2 . .It Dv SA_NODEFER If this bit is set, further occurrences of the delivered signal are not masked during the execution of the handler. .It Dv SA_RESETHAND If this bit is set, the handler is reset back to .Dv SIG_DFL at the moment the signal is delivered. .It Dv SA_RESTART See paragraph below. .It Dv SA_SIGINFO If this bit is set, the handler function is assumed to be pointed to by the .Dv sa_sigaction member of struct sigaction and should match the prototype shown above or as below in .Sx EXAMPLES . This bit should not be set when assigning .Dv SIG_DFL or .Dv SIG_IGN . .El .Pp If a signal is caught during the system calls listed below, the call may be forced to terminate with the error .Er EINTR , the call may return with a data transfer shorter than requested, or the call may be restarted. Restart of pending calls is requested by setting the .Dv SA_RESTART bit in .Ar sa_flags . The affected system calls include .Xr open 2 , .Xr read 2 , .Xr write 2 , .Xr sendto 2 , .Xr recvfrom 2 , .Xr sendmsg 2 and .Xr recvmsg 2 on a communications channel or a slow device (such as a terminal, but not a regular file) and during a .Xr wait 2 or .Xr ioctl 2 . However, calls that have already committed are not restarted, but instead return a partial success (for example, a short read count). .Pp After a .Xr fork 2 or .Xr vfork 2 all signals, the signal mask, the signal stack, and the restart/interrupt flags are inherited by the child. .Pp .Xr Execve 2 reinstates the default action for all signals which were caught and resets all signals to be caught on the user stack. Ignored signals remain ignored; the signal mask remains the same; signals that restart pending system calls continue to do so. .Pp The following is a list of all signals with names as in the include file .Aq Pa signal.h : .Bl -column SIGVTALARMXX "create core imagexxx" .It Sy "NAME Default Action Description" .It Dv SIGHUP No " terminate process" " terminal line hangup" .It Dv SIGINT No " terminate process" " interrupt program" .It Dv SIGQUIT No " create core image" " quit program" .It Dv SIGILL No " create core image" " illegal instruction" .It Dv SIGTRAP No " create core image" " trace trap" .It Dv SIGABRT No " create core image" Ta Xr abort 3 call (formerly .Dv SIGIOT ) .It Dv SIGEMT No " create core image" " emulate instruction executed" .It Dv SIGFPE No " create core image" " floating-point exception" .It Dv SIGKILL No " terminate process" " kill program" .It Dv SIGBUS No " create core image" " bus error" .It Dv SIGSEGV No " create core image" " segmentation violation" .It Dv SIGSYS No " create core image" " non-existent system call invoked" .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" .It Dv SIGALRM No " terminate process" " real-time timer expired" .It Dv SIGTERM No " terminate process" " software termination signal" .It Dv SIGURG No " discard signal" " urgent condition present on socket" .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" .It Dv SIGCONT No " discard signal" " continue after stop" .It Dv SIGCHLD No " discard signal" " child status has changed" .It Dv SIGTTIN No " stop process" " background read attempted from control terminal" .It Dv SIGTTOU No " stop process" " background write attempted to control terminal" .It Dv SIGIO No " discard signal" Tn " I/O" is possible on a descriptor (see .Xr fcntl 2 ) .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" .Xr setrlimit 2 ) .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" .Xr setrlimit 2 ) .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" .Xr setitimer 2 ) .It Dv SIGPROF No " terminate process" " profiling timer alarm (see" .Xr setitimer 2 ) .It Dv SIGWINCH No " discard signal" " Window size change" .It Dv SIGINFO No " discard signal" " status request from keyboard" .It Dv SIGUSR1 No " terminate process" " User defined signal 1" .It Dv SIGUSR2 No " terminate process" " User defined signal 2" .El .Sh NOTE The .Fa sa_mask field specified in .Fa act is not allowed to block .Dv SIGKILL or .Dv SIGSTOP . Any attempt to do so will be silently ignored. .Pp The following functions are either reentrant or not interruptible by signals and are async-signal safe. Therefore applications may invoke them, without restriction, from signal-catching functions: .Pp Base Interfaces: .Pp .Fn _exit , .Fn access , .Fn alarm , .Fn cfgetispeed , .Fn cfgetospeed , .Fn cfsetispeed , .Fn cfsetospeed , .Fn chdir , .Fn chmod , .Fn chown , .Fn close , .Fn creat , .Fn dup , .Fn dup2 , .Fn execle , .Fn execve , .Fn fcntl , .Fn fork , .Fn fpathconf , .Fn fstat , .Fn fsync , .Fn getegid , .Fn geteuid , .Fn getgid , .Fn getgroups , .Fn getpgrp , .Fn getpid , .Fn getppid , .Fn getuid , .Fn kill , .Fn link , .Fn lseek , .Fn mkdir , .Fn mkfifo , .Fn open , .Fn pathconf , .Fn pause , .Fn pipe , .Fn raise , .Fn read , .Fn rename , .Fn rmdir , .Fn setgid , .Fn setpgid , .Fn setsid , .Fn setuid , .Fn sigaction , .Fn sigaddset , .Fn sigdelset , .Fn sigemptyset , .Fn sigfillset , .Fn sigismember , .Fn signal , .Fn sigpending , .Fn sigprocmask , .Fn sigsuspend , .Fn sleep , .Fn stat , .Fn sysconf , .Fn tcdrain , .Fn tcflow , .Fn tcflush , .Fn tcgetattr , .Fn tcgetpgrp , .Fn tcsendbreak , .Fn tcsetattr , .Fn tcsetpgrp , .Fn time , .Fn times , .Fn umask , .Fn uname , .Fn unlink , .Fn utime , .Fn wait , .Fn waitpid , .Fn write . .Pp Realtime Interfaces: .Pp .Fn aio_error , .Fn clock_gettime , .Fn sigpause , .Fn timer_getoverrun , .Fn aio_return , .Fn fdatasync , .Fn sigqueue , .Fn timer_gettime , .Fn aio_suspend , .Fn sem_post , .Fn sigset , .Fn timer_settime . .Pp ANSI C Interfaces: .Pp .Fn strcpy , .Fn strcat , .Fn strncpy , .Fn strncat , and perhaps some others. .Pp Extension Interfaces: .Pp .Fn strlcpy , .Fn strlcat . .Pp All functions not in the above lists are considered to be unsafe with respect to signals. That is to say, the behaviour of such functions when called from a signal handler is undefined. In general though, signal handlers should do little more than set a flag; most other actions are not safe. .Pp Also, it is good practice to make a copy of the global variable .Va errno and restore it before returning from the signal handler. This protects against the side effect of .Va errno being set by functions called from inside the signal handler. .Sh RETURN VALUES .Rv -std sigaction .Sh EXAMPLES There are three possible prototypes the handler may match: .Bl -tag -offset indent -width short .It ANSI C: .Ft void .Fn handler int ; .It Traditional BSD style: .Ft void .Fn handler int "int code" "struct sigcontext *scp" ; .It POSIX SA_SIGINFO: .Ft void .Fn handler int "siginfo_t *info" "void *context" ; .El .Pp The handler function should match the SA_SIGINFO prototype if the SA_SIGINFO bit is set in flags. It then should be pointed to by the .Dv sa_sigaction member of .Dv struct sigaction . Note that you should not assign SIG_DFL or SIG_IGN this way. .Pp If the SA_SIGINFO flag is not set, the handler function should match -either the ANSI C or traditional BSD prototype and be pointed to by +either the ANSI C or traditional +.Bx +prototype and be pointed to by the .Dv sa_handler member of .Dv struct sigaction . In pratice, .Fx always sends the three arguments of the latter and since the ANSI C prototype is a subset, both will work. The .Dv sa_handler member declaration in .Fx include files is that of ANSI C (as required by POSIX), -so a function pointer of a BSD-style function needs to be casted to +so a function pointer of a +.Bx Ns -style +function needs to be casted to compile without warning. -The traditional BSD style is not portable and since its capabilities +The traditional +.Bx +style is not portable and since its capabilities are a full subset of a SA_SIGINFO handler, its use is deprecated. .Pp The .Fa sig argument is the signal number, one of the .Dv SIG... values from . .Pp The .Fa code -argument of the BSD-style handler and the +argument of the +.Bx Ns -style +handler and the .Dv si_code member of the .Dv info argument to a SA_SIGINFO handler contain a numeric code explaning the cause of the signal, usually one of the .Dv SI_... values from or codes specific to a signal, i.e. one of the .Dv FPE_... values for SIGFPE. .Pp The .Fa scp -argument to a BSD-style handler points to an instance of struct +argument to a +.Bx Ns -style +handler points to an instance of struct sigcontext. .Pp The .Fa context argument to a POSIX SA_SIGINFO handler points to an instance of ucontext_t. .Sh ERRORS .Fn Sigaction will fail and no new signal handler will be installed if one of the following occurs: .Bl -tag -width Er .It Bq Er EFAULT Either .Fa act or .Fa oact points to memory that is not a valid part of the process address space. .It Bq Er EINVAL .Fa Sig is not a valid signal number. .It Bq Er EINVAL An attempt is made to ignore or supply a handler for .Dv SIGKILL or .Dv SIGSTOP . .El .Sh STANDARDS The .Fn sigaction function call is expected to conform to .St -p1003.1-90 . The .Dv SA_ONSTACK and .Dv SA_RESTART flags are Berkeley extensions, as are the signals, .Dv SIGTRAP , .Dv SIGEMT , .Dv SIGBUS , .Dv SIGSYS , .Dv SIGURG , .Dv SIGIO , .Dv SIGXCPU , .Dv SIGXFSZ , .Dv SIGVTALRM , .Dv SIGPROF , .Dv SIGWINCH , and .Dv SIGINFO . Those signals are available on most -.Tn BSD Ns \-derived +.Bx Ns \-derived systems. The .Dv SA_NODEFER and .Dv SA_RESETHAND flags are intended for backwards compatibility with other operating systems. The .Dv SA_NOCLDSTOP , and .Dv SA_NOCLDWAIT .\" and .\" SA_SIGINFO flags are featuring options commonly found in other operating systems. .Sh SEE ALSO .Xr kill 1 , .Xr kill 2 , .Xr ptrace 2 , .Xr sigaltstack 2 , .Xr sigblock 2 , .Xr sigpause 2 , .Xr sigpending 2 , .Xr sigprocmask 2 , .Xr sigsetmask 2 , .Xr sigsuspend 2 , .Xr sigvec 2 , .Xr wait 2 , .Xr fpsetmask 3 , .Xr setjmp 3 , .Xr siginterrupt 3 , .Xr sigsetops 3 , .Xr tty 4 Index: head/lib/libc/sys/sigreturn.2 =================================================================== --- head/lib/libc/sys/sigreturn.2 (revision 81621) +++ head/lib/libc/sys/sigreturn.2 (revision 81622) @@ -1,115 +1,115 @@ .\" Copyright (c) 1985, 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. .\" .\" @(#)sigreturn.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd June 4, 1993 .Dt SIGRETURN 2 .Os .Sh NAME .Nm sigreturn .Nd return from signal .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd #include .Pp .Bd -literal struct sigcontext { int sc_onstack; /* sigstack state to restore */ int sc_mask; /* signal mask to restore */ int sc_esp; /* machine state */ int sc_ebp; int sc_isp; int sc_eip; int sc_efl; int sc_es; int sc_ds; int sc_cs; int sc_ss; int sc_edi; int sc_esi; int sc_ebx; int sc_edx; int sc_ecx; int sc_eax; # define sc_sp sc_esp # define sc_fp sc_ebp # define sc_pc sc_eip # define sc_ps sc_efl }; .Ed .Ft int .Fn sigreturn "struct sigcontext *scp" .Sh DESCRIPTION .Fn Sigreturn allows users to atomically unmask, switch stacks, and return from a signal context. The processes signal mask and stack status are restored from the context. The system call does not return; the users stack pointer, frame pointer, argument pointer, and processor status longword are restored from the context. Execution resumes at the specified pc. This system call is used by the trampoline code and .Xr longjmp 3 when returning from a signal to the previously executing program. .Sh NOTES This system call is not available in 4.2 -.Tn BSD +.Bx hence it should not be used if backward compatibility is needed. .Sh RETURN VALUES If successful, the system call does not return. Otherwise, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS .Fn Sigreturn will fail and the process context will remain unchanged if one of the following occurs. .Bl -tag -width Er .It Bq Er EFAULT .Fa Scp points to memory that is not a valid part of the process address space. .It Bq Er EINVAL The process status longword is invalid or would improperly raise the privilege level of the process. .El .Sh SEE ALSO .Xr sigvec 2 , .Xr setjmp 3 .Sh HISTORY The .Fn sigreturn function call appeared in .Bx 4.3 . Index: head/lib/libc/sys/undelete.2 =================================================================== --- head/lib/libc/sys/undelete.2 (revision 81621) +++ head/lib/libc/sys/undelete.2 (revision 81622) @@ -1,103 +1,104 @@ .\" Copyright (c) 1994 .\" Jan-Simon Pendry .\" 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. .\" .\" @(#)undelete.2 8.4 (Berkeley) 10/18/94 .\" $FreeBSD$ .\" .Dd October 18, 1994 .Dt UNDELETE 2 .Os .Sh NAME .Nm undelete .Nd attempt to recover a deleted file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd #include .Ft int .Fn undelete "const char *path" .Sh DESCRIPTION The .Fn undelete function attempts to recover the deleted file named by .Fa path . Currently, this works only when the named object is a whiteout in a union filesystem. The system call removes the whiteout causing any objects in a lower layer of the union stack to become visible once more. .Pp Eventually, the .Fn undelete functionality may be expanded to other filesystems able to recover deleted files such as the log-structured filesystem. .Sh RETURN VALUES .Rv -std undelete .Sh ERRORS The .Fn undelete succeeds unless: .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 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er EEXIST The path does not reference a whiteout. .It Bq Er ENOENT The named whiteout does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EACCES Write permission is denied on the directory containing the name to be undeleted. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EPERM The directory containing the name is marked sticky, and the containing directory is not owned by the effective user ID. .It Bq Er EIO An I/O error occurred while updating the directory entry. .It Bq Er EROFS The name resides on a read-only file system. .It Bq Er EFAULT .Fa Path points outside the process's allocated address space. .El .Sh SEE ALSO .Xr unlink 2 , .Xr mount_unionfs 8 .Sh HISTORY An .Fn undelete -function call first appeared in 4.4BSD-Lite. +function call first appeared in +.Bx 4.4 Lite . Index: head/lib/libcam/cam_cdbparse.3 =================================================================== --- head/lib/libcam/cam_cdbparse.3 (revision 81621) +++ head/lib/libcam/cam_cdbparse.3 (revision 81622) @@ -1,545 +1,548 @@ .\" .\" Copyright (c) 1998 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$ .\" .\" This man page borrows heavily from the old scsi(3) man page, which had .\" the following copyright: .\" .\" Copyright (c) 1994 HD Associates (hd@world.std.com) .\" 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 HD Associates .\" 4. Neither the name of the HD Associates 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 HD ASSOCIATES``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 HD ASSOCIATES OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" .Dd October 13, 1998 .Os .Dt CAM_CDBPARSE 3 .Sh NAME .Nm csio_build , .Nm csio_build_visit , .Nm csio_decode , .Nm csio_decode_visit , .Nm buff_decode , .Nm buff_decode_visit , .Nm csio_encode , .Nm csio_encode_visit , .Nm buff_encode_visit .Nd CAM user library SCSI buffer parsing routines .Sh LIBRARY .Lb libcam .Sh SYNOPSIS .Fd #include .Fd #include .Ft int .Fo csio_build .Fa "struct ccb_scsiio *csio" .Fa "u_int8_t *data_ptr" .Fa "u_int32_t dxfer_len" .Fa "u_int32_t flags" .Fa "int retry_count" .Fa "int timeout" .Fa "char *cmd_spec" .Fa "..." .Fc .Ft int .Fo csio_build_visit .Fa "struct ccb_scsiio *csio" .Fa "u_int8_t *data_ptr" .Fa "u_int32_t dxfer_len" .Fa "u_int32_t flags" .Fa "int retry_count" .Fa "int timeout" .Fa "char *cmd_spec" .Fa "int (*arg_get)(void *hook, char *field_name)" .Fa "void *gethook" .Fc .Ft int .Fo csio_decode .Fa "struct ccb_scsiio *csio" .Fa "char *fmt" .Fa "..." .Fc .Ft int .Fo csio_decode_visit .Fa "struct ccb_scsiio *csio" .Fa "char *fmt" .Fa "void (*arg_put)(void *hook" .Fa "int letter" .Fa "void *val" .Fa "int count" .Fa "char *name)" .Fa "void *puthook" .Fc .Ft int .Fo buff_decode .Fa "u_int8_t *buff" .Fa "size_t len" .Fa "char *fmt" .Fa "..." .Fc .Ft int .Fo buff_decode_visit .Fa "u_int8_t *buff" .Fa "size_t len" .Fa "char *fmt" .Fa "void (*arg_put)(void *, int, void *, int, char *)" .Fa "void *puthook" .Fc .Ft int .Fo csio_encode .Fa "struct ccb_scsiio *csio" .Fa "char *fmt" .Fa "..." .Fc .Ft int .Fo csio_encode_visit .Fa "struct ccb_scsiio *csio" .Fa "char *fmt" .Fa "int (*arg_get)(void *hook, char *field_name)" .Fa "void *gethook" .Fc .Ft int .Fo buff_encode_visit .Fa "u_int8_t *buff" .Fa "size_t len" .Fa "char *fmt" .Fa "int (*arg_get)(void *hook, char *field_name)" .Fa "void *gethook" .Fc .Sh DESCRIPTION The CAM buffer/CDB encoding and decoding routines provide a relatively easy migration path for userland .Tn SCSI applications written with the similarly-named .Va scsireq_ Ns * functions from the old .Fx .Tn SCSI layer. .Pp These functions may be used in new applications, but users may find it easier to use the various SCSI CCB building functions included with the .Xr cam 3 library. (e.g.\& .Fn cam_fill_csio , .Fn scsi_start_stop , and .Fn scsi_read_write ) .Pp .Fn csio_build builds up a .Va ccb_scsiio structure based on the information provided in the variable argument list. It gracefully handles a NULL .Fa data_ptr argument passed to it. .Pp .Fa dxfer_len is the length of the data phase; the data transfer direction is determined by the .Fa flags argument. .Pp .Fa data_ptr is the data buffer used during the .Tn SCSI data phase. If no data is to be transferred for the .Tn SCSI command in question, this should be set to NULL. If there is data to transfer for the command, this buffer must be at least .Fa dxfer_len long. .Pp .Fa flags are the flags defined in .Aq Pa cam/cam_ccb.h : .Bd -literal /* Common CCB header */ /* CAM CCB flags */ typedef enum { CAM_CDB_POINTER = 0x00000001,/* The CDB field is a pointer */ CAM_QUEUE_ENABLE = 0x00000002,/* SIM queue actions are enabled */ CAM_CDB_LINKED = 0x00000004,/* CCB contains a linked CDB */ CAM_SCATTER_VALID = 0x00000010,/* Scatter/gather list is valid */ CAM_DIS_AUTOSENSE = 0x00000020,/* Disable autosense feature */ CAM_DIR_RESV = 0x00000000,/* Data direction (00:reserved) */ CAM_DIR_IN = 0x00000040,/* Data direction (01:DATA IN) */ CAM_DIR_OUT = 0x00000080,/* Data direction (10:DATA OUT) */ CAM_DIR_NONE = 0x000000C0,/* Data direction (11:no data) */ CAM_DIR_MASK = 0x000000C0,/* Data direction Mask */ CAM_SOFT_RST_OP = 0x00000100,/* Use Soft reset alternative */ CAM_ENG_SYNC = 0x00000200,/* Flush resid bytes on complete */ CAM_DEV_QFRZDIS = 0x00000400,/* Disable DEV Q freezing */ CAM_DEV_QFREEZE = 0x00000800,/* Freeze DEV Q on execution */ CAM_HIGH_POWER = 0x00001000,/* Command takes a lot of power */ CAM_SENSE_PTR = 0x00002000,/* Sense data is a pointer */ CAM_SENSE_PHYS = 0x00004000,/* Sense pointer is physical addr*/ CAM_TAG_ACTION_VALID = 0x00008000,/* Use the tag action in this ccb*/ CAM_PASS_ERR_RECOVER = 0x00010000,/* Pass driver does err. recovery*/ CAM_DIS_DISCONNECT = 0x00020000,/* Disable disconnect */ CAM_SG_LIST_PHYS = 0x00040000,/* SG list has physical addrs. */ CAM_MSG_BUF_PHYS = 0x00080000,/* Message buffer ptr is physical*/ CAM_SNS_BUF_PHYS = 0x00100000,/* Autosense data ptr is physical*/ CAM_DATA_PHYS = 0x00200000,/* SG/Buffer data ptrs are phys. */ CAM_CDB_PHYS = 0x00400000,/* CDB poiner is physical */ CAM_ENG_SGLIST = 0x00800000,/* SG list is for the HBA engine */ /* Phase cognizant mode flags */ CAM_DIS_AUTOSRP = 0x01000000,/* Diable autosave/restore ptrs */ CAM_DIS_AUTODISC = 0x02000000,/* Disable auto disconnect */ CAM_TGT_CCB_AVAIL = 0x04000000,/* Target CCB available */ CAM_TGT_PHASE_MODE = 0x08000000,/* The SIM runs in phase mode */ CAM_MSGB_VALID = 0x20000000,/* Message buffer valid */ CAM_STATUS_VALID = 0x40000000,/* Status buffer valid */ CAM_DATAB_VALID = 0x80000000,/* Data buffer valid */ /* Host target Mode flags */ CAM_TERM_IO = 0x20000000,/* Terminate I/O Message sup. */ CAM_DISCONNECT = 0x40000000,/* Disconnects are mandatory */ CAM_SEND_STATUS = 0x80000000,/* Send status after data phase */ } ccb_flags; .Ed .Pp Multiple flags should be ORed together. Any of the CCB flags may be used, although it is worth noting several important ones here: .Pp .Bl -tag -width CAM_PASS_ERR_RECOVER .It Dv CAM_DIR_IN This indicates that the operation in question is a read operation. i.e., data is being read from the .Tn SCSI device to the user-supplied buffer. .It Dv CAM_DIR_OUT This indicates that the operation is a write operation. i.e. data is being written from the user-supplied buffer to the device. .It Dv CAM_DIR_NONE This indicates that there is no data to be transferred for this command. .It Dv CAM_DEV_QFRZDIS This flag disables device queue freezing as an error recovery mechanism. .It Dv CAM_PASS_ERR_RECOVER This flag tells the .Xr pass 4 driver to enable error recovery. The default is to not perform error recovery, which means that the retry count won't be honored without this flag, among other things. .It Dv CAM_DATA_PHYS This indicates that the address contained in .Fa data_ptr is a physical address, not a virtual address. .El .Pp The .Fa retry_count tells the kernel how many times to retry the command in question. The retry count is ignored unless the .Xr pass 4 driver is told to enable error recovery via the .Dv CAM_PASS_ERR_RECOVER flag. .Pp The .Fa timeout tells the kernel how long to wait for the given command to complete. If the timeout expires and the command hasn't completed, the CCB will be returned from the kernel with an appropriate error status. .Pp .Fa cmd_spec is a CDB format specifier used to build up the SCSI CDB. This text string is made up of a list of field specifiers. Field specifiers specify the value for each CDB field (including indicating that the value be taken from the next argument in the variable argument list), the width of the field in bits or bytes, and an optional name. White space is ignored, and the pound sign ('#') introduces a comment that ends at the end of the current line. .Pp The optional name is the first part of a field specifier and is in curly braces. The text in curly braces in this example are the names: .Dl "{PS} v:b1 {Reserved} 0:b1 {Page Code} v:b6 # Mode select page" .Pp This field specifier has two one bit fields and one six bit field. The second one bit field is the constant value 0 and the first one bit field and the six bit field are taken from the variable argument list. Multi byte fields are swapped into the SCSI byte order in the CDB and white space is ignored. .Pp When the field is a hex value or the letter v, (e.g., .Fa "1A" or .Fa "v" ) then a single byte value is copied to the next unused byte of the CDB. When the letter .Fa v is used the next integer argument is taken from the variable argument list and that value used. .Pp A constant hex value followed by a field width specifier or the letter .Fa v followed by a field width specifier (e.g., .Fa 3:4 , .Fa 3:b4 , .Fa 3:i3 , .Fa v:i3 ) specifies a field of a given bit or byte width. Either the constant value or (for the V specifier) the next integer value from the variable argument list is copied to the next unused bits or bytes of the CDB. .Pp A decimal number or the letter .Fa b followed by a decimal number field width indicates a bit field of that width. The bit fields are packed as tightly as possible beginning with the high bit (so that it reads the same as the SCSI spec), and a new byte of the CDB is started whenever a byte fills completely or when an .Fa i field is encountered. .Pp A field width specifier consisting of the letter .Fa i followed by either 1, 2, 3 or 4 indicates a 1, 2, 3 or 4 byte integral value that must be swapped into SCSI byte order (MSB first). .Pp For the .Fa v field specifier the next integer argument is taken from the variable argument list and that value is used swapped into SCSI byte order. .Pp .Fn csio_build_visit operates similarly to .Fn csio_build , except that the values to substitute for variable arguments in .Fa cmd_spec are retrieved via the .Fn arg_get function passed in to .Fn csio_build_visit instead of via .Xr stdarg 3 . The .Fn arg_get function takes two arguments: .Bl -tag -width field_name .It Fa gethook is passed into the .Fn arg_get function at each invocation. This enables the .Fn arg_get function to keep some state in between calls without using global or static variables. .It Fa field_name is the field name supplied in .Fa fmt , if any. .El .Pp .Fn csio_decode is used to decode information from the data in phase of the SCSI transfer. .Pp The decoding is similar to the command specifier processing of .Fn csio_build except that the data is extracted from the data pointed to by .Fa csio->data_ptr . The stdarg list should be pointers to integers instead of integer values. A seek field type and a suppression modifier are added. The .Fa * suppression modifier (e.g., .Fa *i3 or .Fa *b4 ) suppresses assignment from the field and can be used to skip over bytes or bits in the data, without having to copy them to a dummy variable in the arg list. .Pp The seek field type .Fa s permits you to skip over data. This seeks to an absolute position .Pq Fa s3 or a relative position .Pq Fa s+3 in the data, based on whether or not the presence of the '+' sign. The seek value can be specified as .Fa v and the next integer value from the argument list will be used as the seek value. .Pp .Fn csio_decode_visit operates like .Fn csio_decode except that instead of placing the decoded contents of the buffer in varardic arguments, the decoded buffer contents are returned to the user via the .Fn arg_put function that is passed in. The .Fn arg_put function takes several arguments: .Bl -tag -width letter .It Fa hook The "hook" is a mechanism to allow the .Fn arg_put function to save state in between calls. .It Fa letter is the letter describing the format of the argument being passed into the function. .It Fa val is a void pointer to the value being passed into the function. .It Fa count is the size of the value being passed into the .Fn arg_put function. The argument format determines the unit of measure. .It Fa name This is a text description of the field, if one was provided in the .Fa fmt . .El .Pp .Fn buff_decode decodes an arbitrary data buffer using the method described above for .Fn csio_decode . .Pp .Fn buff_decode_visit decodes an arbitrary data buffer using the method described above for .Fn csio_decode_visit . .Pp .Fn csio_encode encodes the .Fa data_ptr portion (not the CDB!) of a .Va ccb_scsiio structure, using the method described above for .Fn csio_build . .Pp .Fn csio_encode_visit encodes the .Fa data_ptr portion (not the CDB!) of a .Va ccb_scsiio structure, using the method described above for .Fn csio_build_visit . .Pp .Fn buff_encode_visit encodes an arbitrary data pointer, using the method described above for .Fn csio_build_visit . .Sh RETURN VALUES .Fn csio_build , .Fn csio_build_visit , .Fn csio_encode , .Fn csio_encode_visit , and .Fn buff_encode_visit return the number of fields processed. .Pp .Fn csio_decode , .Fn csio_decode_visit , .Fn buff_decode , and .Fn buff_decode_visit return the number of assignments performed. .Sh SEE ALSO .Xr cam 3 , .Xr pass 4 , .Xr camcontrol 8 .Sh HISTORY The CAM versions of these functions are based upon similar functions implemented for the old .Fx .Tn SCSI layer. The encoding/decoding functions in the old .Tn SCSI code were written by Peter Dufault. .Pp Many systems have comparable interfaces to permit a user to construct a SCSI command in user space. .Pp The old .Va scsireq data structure was almost identical to the SGI /dev/scsi data structure. If anyone knows the name of the authors it should go here; Peter Dufault first read about it in a 1989 Sun Expert magazine. .Pp The new CCB data structures are derived from the CAM-2 and CAM-3 specifications. .Pp -Peter Dufault implemented a clone of SGI's interface in 386bsd that +.An Peter Dufault +implemented a clone of SGI's interface in +.Bx 386 +that led to the original .Fx .Tn SCSI library and the related kernel ioctl. If anyone needs that for compatibility contact dufault@hda.com. .Sh AUTHORS Kenneth Merry implemented the CAM versions of these encoding and decoding functions. This current work is based upon earlier work by Peter Dufault. .Sh BUGS There should probably be a function that encodes both the CDB and the data buffer portions of a .Tn SCSI CCB. I discovered this while implementing the arbitrary command execution code in .Xr camcontrol 8 , but I haven't yet had time to implement such a function. .Pp Some of the CCB flag descriptions really don't belong here. Rather they belong in a generic CCB man page. Since that man page hasn't yet been written, the shorter descriptions here will have to suffice. Index: head/lib/libdisk/libdisk.3 =================================================================== --- head/lib/libdisk/libdisk.3 (revision 81621) +++ head/lib/libdisk/libdisk.3 (revision 81622) @@ -1,337 +1,339 @@ .\" .\" Copyright (c) 1996 Joerg Wunsch .\" .\" 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 March 15, 1996 .Dt LIBDISK 3 .Os .Sh NAME .Nm Open_Disk , .Nm Clone_Disk , .Nm Free_Disk , .Nm Debug_Disk , .Nm Set_Bios_Geom , .Nm Delete_Chunk , .Nm Collapse_Disk , .Nm Collapse_Chunk , .Nm Create_Chunk , .Nm All_FreeBSD , .Nm CheckRules , .Nm Disk_Names , .Nm Set_Boot_Mgr , .Nm Set_Boot_Blocks , .Nm Write_Disk , .Nm Cyl_Aligned , .Nm Next_Cyl_Aligned , .Nm Prev_Cyl_Aligned , .Nm Track_Aligned , .Nm Next_Track_Aligned , .Nm Prev_Track_Aligned , .Nm Create_Chunk_DWIM , .Nm MakeDev , .Nm MakeDevDisk , .Nm ShowChunkFlags , .Nm ChunkCanBeRoot , .Nm chunk_n , .Nm slice_type_name .Nd library interface to slice and partition labels .Sh LIBRARY .Lb libdisk .Sh SYNOPSIS .Fd #include .Fd #include .Pp .Vt extern const char *chunk_n[] ; .Ft const char * .Fn slice_type_name "int type" "int subtype" .Ft struct disk * .Fn Open_Disk "const char *devname" .Ft struct disk * .Fn Clone_Disk "struct disk *disk" .Ft void .Fn Free_Disk "struct disk *disk" .Ft void .Fn Debug_Disk "struct disk *disk" .Ft void .Fn Set_Bios_Geom "struct disk *disk" "u_long cyl" "u_long heads" "u_long sects" .Ft int .Fn Delete_Chunk "struct disk *disk" "struct chunk *" .Ft void .Fn Collapse_Disk "struct disk *disk" .Ft int .Fn Collapse_Chunk "struct disk *disk" "struct chunk *chunk" .Ft int .Fn Create_Chunk "struct disk *disk" "u_long offset" "u_long size" "chunk_e type" "int subtype" "u_long flags" .Ft void .Fn All_FreeBSD "struct disk *d" "int force_all" .Ft char * .Fn CheckRules "struct disk *" .Ft char ** .Fn Disk_Names "void" .Ft void .Fn Set_Boot_Mgr "struct disk *d" "const u_char *bootmgr" "const size_t bootmgr_size" .Ft void .Fn Set_Boot_Blocks "struct disk *d" "const u_char *boot1" "const u_char *boot2" .Ft int .Fn Write_Disk "struct disk *d" .Ft int .Fn Cyl_Aligned "struct disk *d" "u_long offset" .Ft u_long .Fn Next_Cyl_Aligned "struct disk *d" "u_long offset" .Ft u_long .Fn Prev_Cyl_Aligned "struct disk *d" "u_long offset" .Ft int .Fn Track_Aligned "struct disk *d" "u_long offset" .Ft u_long .Fn Next_Track_Aligned "struct disk *d" "u_long offset" .Ft u_long .Fn Prev_Track_Aligned "struct disk *d" "u_long offset" .Ft struct chunk * .Fn Create_Chunk_DWIM "struct disk *d" "struct chunk *parent" "u_long size" "chunk_e type" "int subtype" "u_long flags" .Ft int .Fn MakeDev "struct chunk *c" "const char *path" .Ft int .Fn MakeDevDisk "struct disk *d" "const char *path" .Ft char * .Fn ShowChunkFlags "struct chunk *c" .Ft char * .Fn ChunkCanBeRoot "struct chunk *c" .Sh DESCRIPTION .Nm Libdisk provides an interface to the low-level disk slice and partition labels. Most functions operate with arguments of the types .Ql struct disk , or .Ql struct chunk . .Pp While both types are mostly opaque to the programmer, the internal structure is mentioned below for the sake of completeness. .Bd -literal -offset indent struct disk { char *name; u_long flags; u_long bios_cyl; u_long bios_hd; u_long bios_sect; u_char *bootmgr; u_char *boot1; u_char *boot2; struct chunk *chunks; u_long sector_size; }; .Ed The only flag value by now is .Ql DISK_ON_TRACK , meaning that this disk is handled by the On-Track Disk Manager. .Pp .Bd -literal -offset indent struct chunk { struct chunk *next; struct chunk *part; struct disk *disk; long offset; u_long size; u_long end; char *name; char *oname; chunk_e type; int subtype; u_long flags; void (*private_free)(void*); void *(*private_clone)(void*); void *private_data; }; .Ed The .Ql type field can be one of the following values: .Ql whole, unknown, fat, freebsd, extended, part, unused . .Pp These are the valid .Ql flag values for a .Ql struct chunk . .Bl -tag -offset indent -width CHUNK_BSD_COMPATXX .It CHUNK_PAST_1024 This chunk cannot be booted from because it extends past cylinder 1024. .It CHUNK_BSD_COMPAT -This chunk is in the BSD-compatibility, and has a short name too, i.e.\& +This chunk is in the +.Bx Ns -compatibility , +and has a short name too, i.e.\& .Ql wd0s4f -> wd0f . .It CHUNK_ALIGN This chunk should be aligned. .It CHUNK_IS_ROOT This .Ql part is a rootfs, allocate partition .Sq a . .It CHUNK_ACTIVE This is the active slice in the MBR. .It CHUNK_FORCE_ALL Force a dedicated disk for .Fx , bypassing all BIOS geometry considerations. .El .Pp The .Ql private_data , .Ql private_free , and .Ql private_clone fields are for data private to the application, and the management thereof. If the functions are not provided, no storage management is done, cloning will just copy the pointer and freeing will just forget it. .Pp .Fn Open_Disk will open the named disk, and return populated tree. .Pp .Fn Clone_Disk clones a copy of a tree. Useful for .Dq Undo functionality. .Pp .Fn Free_Disk frees a tree made with .Fn Open_Disk or .Fn Clone_Disk . .Pp .Fn Debug_Disk prints the content of the tree to stdout. .Pp .Fn Set_Bios_Geom sets the geometry the bios uses. .Pp .Fn Delete_Chunk frees a chunk of disk_space. .Pp .Fn Collapse_Disk and .Fn Collapse_Chunk are experimental, do not use. .Pp .Fn Create_Chunk creates a chunk with the specified parameters. .Pp .Fn All_FreeBSD makes one .Fx chunk covering the entire disk; if .Ql force_all is set, bypass all BIOS geometry considerations. .Pp .Fn CheckRules returns .Ql char* to warnings about broken design rules in this disklayout. .Pp .Fn Disk_Names returns .Ql char** with all disk's names (wd0, wd1 ...). You must free each pointer, as well as the array by hand. .Pp .Fn Set_Boot_Mgr sets this boot-manager for use on this disk. Gets written when .Fn Write_Disk is called. .Pp .Fn Set_Boot_Blocks sets the boot-blocks for use on this disk. Gets written when .Fn Write_Disk is called. .Pp .Fn Write_Disk writes all the MBRs, disklabels, bootblocks and boot managers. .Pp .Fn Cyl_Aligned checks if .Ql offset is aligned on a cylinder according to the BIOS geometry. .Pp .Fn Next_Cyl_Aligned rounds .Ql offset up to next cylinder according to the BIOS geometry. .Pp .Fn Prev_Cyl_Aligned rounds .Ql offset down to previous cylinder according to the BIOS geometry. .Pp .Fn Track_Aligned checks if .Ql offset is aligned on a track according to the BIOS geometry. .Pp .Fn Next_Track_Aligned rounds .Ql offset up to next track according to the BIOS geometry. .Pp .Fn Prev_Track_Aligned checks if .Ql offset is aligned on a track according to the BIOS geometry. .Pp .Fn Create_Chunk_DWIM creates a partition inside the given parent of the given size, and returns a pointer to it. The first unused chunk big enough is used. .Pp .Fn MakeDev makes the device nodes for this chunk. .Pp .Fn MakeDevDisk makes the device nodes for all chunks on this disk. .Pp .Fn ShowChunkFlags returns a string to show flags. .Pp .Fn ChunkCanBeRoot returns NULL if chunk can be .Ql / . .Pp Chunk name strings can be accessed directly using the external array .Va chunk_n . .Pp .Fn slice_type_name returns the name strings associated with the specified .Ql type . .Ql subtype . If .Fn slice_type_name returns "unknown" for slices it isn't familiar with. .Sh AUTHORS .An -nosplit The .Nm libdisk library was written by .An Poul-Henning Kamp . .Pp This manual page was written by .An J\(:org Wunsch . Index: head/lib/libkvm/kvm.3 =================================================================== --- head/lib/libkvm/kvm.3 (revision 81621) +++ head/lib/libkvm/kvm.3 (revision 81622) @@ -1,106 +1,110 @@ .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software developed by the Computer Systems .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract .\" BG 91-66 and contributed to Berkeley. .\" .\" 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. .\" .\" @(#)kvm.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd June 4, 1993 .Dt KVM 3 .Os .Sh NAME .Nm kvm .Nd kernel memory interface .Sh LIBRARY .Lb libkvm .Sh DESCRIPTION The .Xr kvm 3 library provides a uniform interface for accessing kernel virtual memory images, including live systems and crash dumps. Access to live systems is via .Pa /dev/mem while crash dumps can be examined via the core file generated by .Xr savecore 8 . The interface behaves identically in both cases. Memory can be read and written, kernel symbol addresses can be looked up efficiently, and information about user processes can be gathered. .Pp .Fn kvm_open is first called to obtain a descriptor for all subsequent calls. .Sh COMPATIBILITY The kvm interface was first introduced in SunOS. A considerable number of programs have been developed that use this interface, making backward compatibility highly desirable. In most respects, the Sun kvm interface is consistent and clean. Accordingly, the generic portion of the interface (i.e., .Fn kvm_open , .Fn kvm_close , .Fn kvm_read , .Fn kvm_write , and .Fn kvm_nlist ) -has been incorporated into the BSD interface. Indeed, many kvm +has been incorporated into the +.Bx +interface. Indeed, many kvm applications (i.e., debuggers and statistical monitors) use only this subset of the interface. .Pp The process interface was not kept. This is not a portability issue since any code that manipulates processes is inherently machine dependent. .Pp Finally, the Sun kvm error reporting semantics are poorly defined. The library can be configured either to print errors to stderr automatically, or to print no error messages at all. In the latter case, the nature of the error cannot be determined. -To overcome this, the BSD interface includes a +To overcome this, the +.Bx +interface includes a routine, .Xr kvm_geterr 3 , to return (not print out) the error message corresponding to the most recent error condition on the given descriptor. .Sh SEE ALSO .Xr kvm_close 3 , .Xr kvm_getargv 3 , .Xr kvm_getenvv 3 , .Xr kvm_geterr 3 , .Xr kvm_getfiles 3 , .Xr kvm_getloadavg 3 , .Xr kvm_getprocs 3 , .Xr kvm_getswapinfo 3 , .Xr kvm_nlist 3 , .Xr kvm_open 3 , .Xr kvm_openfiles 3 , .Xr kvm_read 3 , .Xr kvm_write 3 Index: head/lib/libkvm/kvm_open.3 =================================================================== --- head/lib/libkvm/kvm_open.3 (revision 81621) +++ head/lib/libkvm/kvm_open.3 (revision 81622) @@ -1,187 +1,191 @@ .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software developed by the Computer Systems .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract .\" BG 91-66 and contributed to Berkeley. .\" .\" 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. .\" .\" @(#)kvm_open.3 8.3 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd April 19, 1994 .Dt KVM_OPEN 3 .Os .Sh NAME .Nm kvm_open , .Nm kvm_openfiles , .Nm kvm_close .Nd initialize kernel virtual memory access .Sh LIBRARY .Lb libkvm .Sh SYNOPSIS .Fd #include .Fd #include .Ft kvm_t * .Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr" .Ft kvm_t * .Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf" .Ft int .Fn kvm_close "kvm_t *kd" .Sh DESCRIPTION The functions .Fn kvm_open and .Fn kvm_openfiles return a descriptor used to access kernel virtual memory via the .Xr kvm 3 library routines. Both active kernels and crash dumps are accessible through this interface. .Pp .Fa execfile is the executable image of the kernel being examined. This file must contain a symbol table. If this argument is .Dv NULL , the currently running system is assumed, as determined from .Xr getbootfile 3 . .Pp .Fa corefile is the kernel memory device file. It can be either /dev/mem or a crash dump core generated by .Xr savecore 8 . If .Fa corefile is .Dv NULL , the default indicated by .Dv _PATH_MEM from is used. .Pp .Fa swapfile should indicate the swap device. If .Dv NULL , .Dv _PATH_DRUM from is used. .Pp The .Fa flags argument indicates read/write access as in .Xr open 2 and applies only to the core file. Only .Dv O_RDONLY , .Dv O_WRONLY , and .Dv O_RDWR are permitted. .Pp There are two open routines which differ only with respect to the error mechanism. One provides backward compatibility with the SunOS kvm library, while the other provides an improved error reporting framework. .Pp The .Fn kvm_open function is the Sun kvm compatible open call. Here, the .Fa errstr argument indicates how errors should be handled. If it is .Dv NULL , no errors are reported and the application cannot know the specific nature of the failed kvm call. If it is not .Dv NULL , errors are printed to stderr with .Fa errstr prepended to the message, as in .Xr perror 3 . Normally, the name of the program is used here. The string is assumed to persist at least until the corresponding .Fn kvm_close call. .Pp The .Fn kvm_openfiles -function provides BSD style error reporting. +function provides +.Bx +style error reporting. Here, error messages are not printed out by the library. Instead, the application obtains the error message corresponding to the most recent kvm library call using .Fn kvm_geterr (see .Xr kvm_geterr 3 ) . The results are undefined if the most recent kvm call did not produce an error. Since .Fn kvm_geterr requires a kvm descriptor, but the open routines return .Dv NULL on failure, .Fn kvm_geterr cannot be used to get the error message if open fails. Thus, .Fn kvm_openfiles will place any error message in the .Fa errbuf argument. This buffer should be _POSIX2_LINE_MAX characters large (from ). .Sh RETURN VALUES The .Fn kvm_open and .Fn kvm_openfiles functions both return a descriptor to be used in all subsequent kvm library calls. The library is fully re-entrant. On failure, .Dv NULL is returned, in which case .Fn kvm_openfiles writes the error message into .Fa errbuf . .Pp The .Fn kvm_close function returns 0 on success and -1 on failure. .Sh BUGS There should not be two open calls. The ill-defined error semantics of the Sun library and the desire to have a backward-compatible library -for BSD left little choice. +for +.Bx +left little choice. .Sh SEE ALSO .Xr open 2 , .Xr kvm 3 , .Xr kvm_getargv 3 , .Xr kvm_getenvv 3 , .Xr kvm_geterr 3 , .Xr kvm_getprocs 3 , .Xr kvm_nlist 3 , .Xr kvm_read 3 , .Xr kvm_write 3 Index: head/lib/libstand/libstand.3 =================================================================== --- head/lib/libstand/libstand.3 (revision 81621) +++ head/lib/libstand/libstand.3 (revision 81622) @@ -1,634 +1,638 @@ .\" Copyright (c) Michael Smith .\" 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 Ohttp://wafu.netgate.net/tama/unix/indexe.htmlTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 22, 1998 .Dt LIBSTAND 3 .Os .Sh NAME .Nm libstand .Nd support library for standalone executables .Sh SYNOPSIS .Fd #include .Sh DESCRIPTION .Nm provides a set of supporting functions for standalone -applications, mimicking where possible the standard BSD programming +applications, mimicking where possible the standard +.Bx +programming environment. The following sections group these functions by kind. Unless specifically described here, see the corresponding section 3 manpages for the given functions. .Sh STRING FUNCTIONS String functions are available as documented in .Xr string 3 and .Xr bstring 3 . .Sh MEMORY ALLOCATION .Bl -hang -width 10n .It Xo .Ft "void *" .Fn malloc "size_t size" .Xc .Pp Allocate .Fa size bytes of memory from the heap using a best-fit algorithm. .It Xo .Ft void .Fn free "void *ptr" .Xc .Pp Free the allocated object at .Fa ptr . .It Xo .Ft void .Fn setheap "void *start" "void *limit" .Xc .Pp Initialise the heap. This function must be called before calling .Fn alloc for the first time. The region between .Fa start and .Fa limit will be used for the heap; attempting to allocate beyond this will result in a panic. .It Xo .Ft "char *" .Fn sbrk "int junk" .Xc .Pp Provides the behaviour of .Fn sbrk 0 , ie. returns the highest point that the heap has reached. This value can be used during testing to determine the actual heap usage. The .Fa junk argument is ignored. .El .Sh ENVIRONMENT A set of functions are provided for manipulating a flat variable space similar to the traditional shell-supported evironment. Major enhancements are support for set/unset hook functions. .Bl -hang -width 10n .It Xo .Ft "char *" .Fn getenv "const char *name" .Xc .It Xo .Ft int .Fn setenv "const char *name" "char *value" "int overwrite" .Xc .It Xo .Ft int .Fn putenv "const char *string" .Xc .It Xo .Ft int .Fn unsetenv "const char *name" .Xc .Pp These functions behave similarly to their standard library counterparts. .It Xo .Ft "struct env_var *" .Fn env_getenv "const char *name" .Xc .Pp Looks up a variable in the environment and returns its entire data structure. .It Xo .Ft int .Fn env_setenv "const char *name" "int flags" "char *value" "ev_sethook_t sethook" "ev_unsethook_t unsethook" .Xc .Pp Creates a new or sets an existing environment variable called .Fa name . If creating a new variable, the .Fa sethook and .Fa unsethook arguments may be specified. .Pp The set hook is invoked whenever an attempt is made to set the variable, unless the EV_NOHOOK flag is set. Typically a set hook will validate the .Fa value argument, and then call .Fn env_setenv again with EV_NOHOOK set to actually save the value. The predefined function .Fn env_noset may be specified to refuse all attempts to set a variable. .Pp The unset hook is invoked when an attempt is made to unset a variable. If it returns zero, the variable will be unset. The predefined function .Fa env_nounset may be used to prevent a variable being unset. .El .Sh STANDARD LIBRARY SUPPORT .Bl -hang -width 10n .It Xo .Ft int .Fn getopt "int argc" "char * const *argv" "cont char *optstring" .Xc .It Xo .Ft long .Fn strtol "const char *nptr" "char **endptr" "int base" .Xc .It Xo .Ft void .Fn srandom "unsigned long seed" .Xc .It Xo .Ft "unsigned long" .Fn random void .Xc .It Xo .Ft "char *" .Fn strerror "int error" .Xc .Pp Returns error messages for the subset of errno values supported by .Nm . .It Fn assert expression .Pp Requires .Fd #include .It Xo .Ft int .Fn setjmp "jmp_buf env" .Xc .It Xo .Ft void .Fn longjmp "jmp_buf env" "int val" .Xc .Pp Defined as .Fn _setjmp and .Fn _lonjmp respectively as there is no signal state to manipulate. Requires .Fd #include .El .Sh CHARACTER I/O .Bl -hang -width 10n .It Xo .Ft void .Fn gets "char *buf" .Xc .Pp Read characters from the console into .Fa buf . All of the standard cautions apply to this function. .It Xo .Ft void .Fn ngets "char *buf" "size_t size" .Xc .Pp Read at most .Fa size - 1 characters from the console into .Fa buf . If .Fa size is less than 1, the function's behaviour is as for .Fn gets . .It Xo .Ft int .Fn fgetstr "char *buf" "int size" "int fd" .Xc .Pp Read a line of at most .Fa size characters into .Fa buf . Line terminating characters are stripped, and the buffer is always nul terminated. Returns the number of characters in .Fa buf if successful, or -1 if a read error occurs. .It Xo .Ft int .Fn printf "const char *fmt" "..." .Xc .It Xo .Ft void .Fn vprintf "const char *fmt" "va_list ap" .Xc .It Xo .Ft int .Fn sprintf "char *buf" "const char *fmt" "..." .Xc .It Xo .Ft void .Fn vsprintf "char *buf" "const char *fmt" "va_list ap" .Xc .Pp The *printf functions implement a subset of the standard .Fn printf family functionality and some extensions. The following standard conversions are supported: c,d,n,o,p,s,u,x. The following modifiers are supported: +,-,#,*,0,field width,precision,l. .Pp The .Li b conversion is provided to decode error registers. Its usage is: .Pp .Bd -ragged -offset indent printf( .Qq reg=%b\en , regval, .Qq * ); .Ed .Pp where is the output expressed as a control character, eg. \e10 gives octal, \e20 gives hex. Each is a sequence of characters, the first of which gives the bit number to be inspected (origin 1) and the next characters (up to a character less than 32) give the text to be displayed if the bit is set. Thus .Pp .Bd -ragged -offset indent printf( .Qq reg=%b\en 3 .Qq \e10\e2BITTWO\e1BITONE\en ); .Ed .Pp would give the output .Pp .Bd -ragged -offset indent reg=3 .Ed .Pp The .Li D conversion provides a hexdump facility, eg. .Pp .Bd -ragged -offset indent printf( .Qq %6D , ptr, .Qq \&: ); gives .Qq XX:XX:XX:XX:XX:XX .Ed .Bd -ragged -offset indent printf( .Qq %*D , len, ptr, .Qq "\ " ); gives .Qq XX XX XX ... .Ed .El .Sh CHARACTER TESTS AND CONVERSIONS .Bl -hang -width 10n .It Xo .Ft int .Fn isupper "int c" .Xc .It Xo .Ft int .Fn islower "int c" .Xc .It Xo .Ft int .Fn isspace "int c" .Xc .It Xo .Ft int .Fn isdigit "int c" .Xc .It Xo .Ft int .Fn isxdigit "int c" .Xc .It Xo .Ft int .Fn isascii "int c" .Xc .It Xo .Ft int .Fn isalpha "int c" .Xc .It Xo .Ft int .Fn toupper "int c" .Xc .It Xo .Ft int .Fn tolower "int c" .Xc .El .Sh FILE I/O .Bl -hang -width 10n .It Xo .Ft int .Fn open "const char *path" "int flags" .Xc .Pp Similar to the behaviour as specified in .Xr open 2 , except that file creation is not supported, so the mode parameter is not required. The .Fa flags argument may be one of O_RDONLY, O_WRONLY and O_RDWR (although no filesystems currently support writing). .It Xo .Ft int .Fn close "int fd" .Xc .It Xo .Ft void .Fn closeall void .Xc .Pp Close all open files. .It Xo .Ft ssize_t .Fn read "int fd" "void *buf" "size_t len" .Xc .It Xo .Ft ssize_t .Fn write "int fd" "void *buf" "size_t len" .Xc .Pp (No filesystems currently support writing.) .It Xo .Ft off_t .Fn lseek "int fd" "off_t offset" "int whence" .Xc .Pp Files being automatically uncompressed during reading cannot seek backwards from the current point. .It Xo .Ft int .Fn stat "const char *path" "struct stat *sb" .Xc .It Xo .Ft int .Fn fstat "int fd" "struct stat *sb" .Xc .Pp The .Fn stat and .Fn fstat functions only fill out the following fields in the .Fa sb structure: st_mode,st_nlink,st_uid,st_gid,st_size. The .Nm tftp filesystem cannot provide meaningful values for this call, and the .Nm cd9660 filesystem always reports files having uid/gid of zero. .El .Sh PAGER .Nm supplies a simple internal pager to ease reading the output of large commands. .Bl -hang -width 10n .It Xo .Ft void .Fn pager_open .Xc .Pp Initialises the pager and tells it that the next line output will be the top of the display. The environment variable LINES is consulted to determine the number of lines to be displayed before pausing. .It Xo .Ft void .Fn pager_close void .Xc .Pp Closes the pager. .It Xo .Ft int .Fn pager_output "char *lines" .Xc .Pp Sends the lines in the nul-terminated buffer at .Fa lines to the pager. Newline characters are counted in order to determine the number of lines being output (wrapped lines are not accounted for). .Fn pager_output will return zero when all of the lines have been output, or nonzero if the display was paused and the user elected to quit. .It Xo .Ft int .Fn pager_file "char *fname" .Xc .Pp Attempts to open and display the file .Fa fname . Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading. .El .Sh MISC .Bl -hang -width 10n .It Xo .Ft void .Fn twiddle void .Xc .Pp Successive calls emit the characters in the sequence |,/,-,\\ followed by a backspace in order to provide reassurance to the user. .El .Sh REQUIRED LOW-LEVEL SUPPORT The following resources are consumed by .Nm - stack, heap, console and devices. .Pp The stack must be established before .Nm functions can be invoked. Stack requirements vary depending on the functions and filesystems used by the consumer and the support layer functions detailed below. .Pp The heap must be established before calling .Fn alloc or .Fn open by calling .Fn setheap . Heap usage will vary depending on the number of simultaneously open files, as well as client behaviour. Automatic decompression will allocate more than 64K of data per open file. .Pp Console access is performed via the .Fn getchar , .Fn putchar and .Fn ischar functions detailed below. .Pp Device access is initiated via .Fn devopen and is performed through the .Fn dv_strategy , .Fn dv_ioctl and .Fn dv_close functions in the device switch structure that .Fn devopen returns. .Pp The consumer must provide the following support functions: .Bl -hang -width 10n .It Xo .Ft int .Fn getchar void .Xc .Pp Return a character from the console, used by .Fn gets , .Fn ngets and pager functions. .It Xo .Ft int .Fn ischar void .Xc .Pp Returns nonzero if a character is waiting from the console. .It Xo .Ft void .Fn putchar int .Xc .Pp Write a character to the console, used by .Fn gets , .Fn ngets , .Fn *printf , .Fn panic and .Fn twiddle and thus by many other functions for debugging and informational output. .It Xo .Ft int .Fn devopen "struct open_file *of" "const char *name" "char **file" .Xc .Pp Open the appropriate device for the file named in .Fa name , returning in .Fa file a pointer to the remaining body of .Fa name which does not refer to the device. The .Va f_dev field in .Fa of will be set to point to the .Vt devsw structure for the opened device if successful. Device identifiers must always precede the path component, but may otherwise be arbitrarily formatted. Used by .Fn open and thus for all device-related I/O. .It Xo .Ft int .Fn devclose "struct open_file *of" .Xc Close the device allocated for .Fa of . The device driver itself will already have been called for the close; this call should clean up any allocation made by devopen only. .It Xo .Ft void .Fn panic "const char *msg" "..." .Xc .Pp Signal a fatal and unrecoverable error condition. The .Fa msg ... arguments are as for .Fn printf . .El .Sh INTERNAL FILESYSTEMS Internal filesystems are enabled by the consumer exporting the array .Vt struct fs_ops *file_system[] , which should be initialised with pointers to .Vt struct fs_ops structures. The following filesystem handlers are supplied by .Nm , the consumer may supply other filesystems of their own: .Bl -hang -width "cd9660_fsops " .It ufs_fsops -The BSD UFS. +The +.Bx +UFS. .It ext2fs_fsops Linux ext2fs filesystem. .It tftp_fsops File access via TFTP. .It nfs_fsops File access via NFS. .It cd9660_fsops ISO 9660 (CD-ROM) filesystem. .It zipfs_fsops Stacked filesystem supporting gzipped files. When trying the zipfs filesystem, .Nm appends .Li .gz to the end of the filename, and then tries to locate the file using the other filesystems. Placement of this filesystem in the .Va file_system[] array determines whether gzipped files will be opened in preference to non-gzipped files. It is only possible to seek a gzipped file forwards, and .Fn stat and .Fn fstat on gzipped files will report an invalid length. .El .Pp The array of .Vt struct fs_ops pointers should be terminated with a NULL. .Sh DEVICES Devices are exported by the supporting code via the array .Vt struct devsw *devsw[] which is a NULL terminated array of pointers to device switch structures. .Sh BUGS The lack of detailed memory usage data is unhelpful. .Sh HISTORY .Nm contains contributions from many sources, including: .Bl -bullet -compact .It .Nm libsa from .Nx .It .Nm libc and .Nm libkern from .Fx 3.0 . .It .Nm zalloc from .An Matthew Dillon Aq dillon@backplane.com .El .Pp The reorganisation and port to .Fx 3.0 , the environment functions and this manpage were written by .An Mike Smith Aq msmith@FreeBSD.org . Index: head/libexec/telnetd/telnetd.8 =================================================================== --- head/libexec/telnetd/telnetd.8 (revision 81621) +++ head/libexec/telnetd/telnetd.8 (revision 81622) @@ -1,631 +1,634 @@ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. 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. .\" .\" @(#)telnetd.8 8.3 (Berkeley) 3/1/94 .\" $FreeBSD$ .\" .Dd March 1, 1994 .Dt TELNETD 8 .Os .Sh NAME .Nm telnetd .Nd DARPA .Tn TELNET protocol server .Sh SYNOPSIS .Nm /usr/libexec/telnetd .Op Fl Uhlkns .Op Fl D Ar debugmode .Op Fl I Ns Ar initid .Op Fl S Ar tos .Op Fl X Ar authtype .Op Fl a Ar authmode .Op Fl edebug .Op Fl p Ar loginprog .Op Fl r Ns Ar lowpty-highpty .Op Fl u Ar len .Op Fl debug Op Ar port .Sh DESCRIPTION The .Nm command is a server which supports the .Tn DARPA standard .Tn TELNET virtual terminal protocol. .Nm Telnetd is normally invoked by the internet server (see .Xr inetd 8 ) for requests to connect to the .Tn TELNET port as indicated by the .Pa /etc/services file (see .Xr services 5 ) . The .Fl debug option may be used to start up .Nm manually, instead of through .Xr inetd 8 . If started up this way, .Ar port may be specified to run .Nm on an alternate .Tn TCP port number. .Pp The .Nm command accepts the following options: .Bl -tag -width indent .It Fl a Ar authmode This option may be used for specifying what mode should be used for authentication. Note that this option is only useful if .Nm has been compiled with support for the .Dv AUTHENTICATION option. There are several valid values for .Ar authmode : .Bl -tag -width debug .It Cm debug Turn on authentication debugging code. .It Cm user Only allow connections when the remote user can provide valid authentication information to identify the remote user, and is allowed access to the specified account without providing a password. .It Cm valid Only allow connections when the remote user can provide valid authentication information to identify the remote user. The .Xr login 1 command will provide any additional user verification needed if the remote user is not allowed automatic access to the specified account. .It Cm other Only allow connections that supply some authentication information. This option is currently not supported by any of the existing authentication mechanisms, and is thus the same as specifying .Fl a .Cm valid . .It Cm none This is the default state. Authentication information is not required. If no or insufficient authentication information is provided, then the .Xr login 1 program will provide the necessary user verification. .It Cm off Disable the authentication code. All user verification will happen through the .Xr login 1 program. .El .It Fl D Ar debugmode This option may be used for debugging purposes. This allows .Nm to print out debugging information to the connection, allowing the user to see what .Nm is doing. There are several possible values for .Ar debugmode : .Bl -tag -width exercise .It Cm options Print information about the negotiation of .Tn TELNET options. .It Cm report Print the .Cm options information, plus some additional information about what processing is going on. .It Cm netdata Display the data stream received by .Nm . .It Cm ptydata Display data written to the pty. .It Cm exercise Has not been implemented yet. .El .It Fl debug Enable debugging on each socket created by .Nm (see .Dv SO_DEBUG in .Xr socket 2 ) . .It Fl edebug If .Nm has been compiled with support for data encryption, then the .Fl edebug option may be used to enable encryption debugging code. .It Fl p Ar loginprog Specify an alternate .Xr login 1 command to run to complete the login. The alternate command must understand the same command arguments as the standard login. .It Fl h Disable the printing of host-specific information before login has been completed. .It Fl I Ar initid This option is only applicable to .Tn UNICOS systems prior to 7.0. It specifies the .Dv ID from .Pa /etc/inittab to use when init starts login sessions. The default .Dv ID is .Dv fe . .It Fl k This option is only useful if .Nm has been compiled with both linemode and kludge linemode support. If the .Fl k option is specified, then if the remote client does not support the .Dv LINEMODE option, then .Nm will operate in character at a time mode. It will still support kludge linemode, but will only go into kludge linemode if the remote client requests it. (This is done by the client sending .Dv DONT SUPPRESS-GO-AHEAD and .Dv DONT ECHO . ) The .Fl k option is most useful when there are remote clients that do not support kludge linemode, but pass the heuristic (if they respond with .Dv WILL TIMING-MARK in response to a .Dv DO TIMING-MARK ) for kludge linemode support. .It Fl l Specify line mode. Try to force clients to use line- at-a-time mode. If the .Dv LINEMODE option is not supported, it will go into kludge linemode. .It Fl n Disable .Dv TCP keep-alives. Normally .Nm enables the .Tn TCP keep-alive mechanism to probe connections that have been idle for some period of time to determine if the client is still there, so that idle connections from machines that have crashed or can no longer be reached may be cleaned up. .It Fl r Ar lowpty-highpty This option is only enabled when .Nm is compiled for .Dv UNICOS . It specifies an inclusive range of pseudo-terminal devices to use. If the system has sysconf variable .Dv _SC_CRAY_NPTY configured, the default pty search range is 0 to .Dv _SC_CRAY_NPTY ; otherwise, the default range is 0 to 128. Either .Ar lowpty or .Ar highpty may be omitted to allow changing either end of the search range. If .Ar lowpty is omitted, the - character is still required so that .Nm can differentiate .Ar highpty from .Ar lowpty . .It Fl s This option is only enabled if .Nm is compiled with support for .Tn SecurID cards. It causes the .Fl s option to be passed on to .Xr login 1 , and thus is only useful if .Xr login 1 supports the .Fl s flag to indicate that only .Tn SecurID validated logins are allowed, and is usually useful for controlling remote logins from outside of a firewall. .It Fl S Ar tos .It Fl u Ar len This option is used to specify the size of the field in the .Dv utmp structure that holds the remote host name. If the resolved host name is longer than .Ar len , the dotted decimal value will be used instead. This allows hosts with very long host names that overflow this field to still be uniquely identified. Specifying .Fl u0 indicates that only dotted decimal addresses should be put into the .Pa utmp file. .It Fl U This option causes .Nm to refuse connections from addresses that cannot be mapped back into a symbolic name via the .Xr gethostbyaddr 3 routine. .It Fl X Ar authtype This option is only valid if .Nm has been built with support for the authentication option. It disables the use of .Ar authtype authentication, and can be used to temporarily disable a specific authentication type without having to recompile .Nm . .El .Pp .Nm Telnetd operates by allocating a pseudo-terminal device (see .Xr pty 4 ) for a client, then creating a login process which has the slave side of the pseudo-terminal as .Dv stdin , .Dv stdout and .Dv stderr . .Nm Telnetd manipulates the master side of the pseudo-terminal, implementing the .Tn TELNET protocol and passing characters between the remote client and the login process. .Pp When a .Tn TELNET session is started up, .Nm sends .Tn TELNET options to the client side indicating a willingness to do the following .Tn TELNET options, which are described in more detail below: .Bd -literal -offset indent DO AUTHENTICATION WILL ENCRYPT DO TERMINAL TYPE DO TSPEED DO XDISPLOC DO NEW-ENVIRON DO ENVIRON WILL SUPPRESS GO AHEAD DO ECHO DO LINEMODE DO NAWS WILL STATUS DO LFLOW DO TIMING-MARK .Ed .Pp The pseudo-terminal allocated to the client is configured to operate in .Dq cooked mode, and with .Dv XTABS and .Dv CRMOD enabled (see .Xr tty 4 ) . .Pp .Nm Telnetd has support for enabling locally the following .Tn TELNET options: .Bl -tag -width "DO AUTHENTICATION" .It "WILL ECHO" When the .Dv LINEMODE option is enabled, a .Dv WILL ECHO or .Dv WONT ECHO will be sent to the client to indicate the current state of terminal echoing. When terminal echo is not desired, a .Dv WILL ECHO is sent to indicate that .Nm will take care of echoing any data that needs to be echoed to the terminal, and then nothing is echoed. When terminal echo is desired, a .Dv WONT ECHO is sent to indicate that .Nm will not be doing any terminal echoing, so the client should do any terminal echoing that is needed. .It "WILL BINARY" Indicate that the client is willing to send a 8 bits of data, rather than the normal 7 bits of the Network Virtual Terminal. .It "WILL SGA" Indicate that it will not be sending .Dv IAC GA , go ahead, commands. .It "WILL STATUS" Indicate a willingness to send the client, upon request, of the current status of all .Tn TELNET options. .It "WILL TIMING-MARK" Whenever a .Dv DO TIMING-MARK command is received, it is always responded to with a .Dv WILL TIMING-MARK . .It "WILL LOGOUT" When a .Dv DO LOGOUT is received, a .Dv WILL LOGOUT is sent in response, and the .Tn TELNET session is shut down. .It "WILL ENCRYPT" Only sent if .Nm is compiled with support for data encryption, and indicates a willingness to decrypt the data stream. .El .Pp .Nm Telnetd has support for enabling remotely the following .Tn TELNET options: .Bl -tag -width "DO AUTHENTICATION" .It "DO BINARY" Sent to indicate that .Nm is willing to receive an 8 bit data stream. .It "DO LFLOW" Requests that the client handle flow control characters remotely. .It "DO ECHO" -This is not really supported, but is sent to identify a 4.2BSD +This is not really supported, but is sent to identify a +.Bx 4.2 .Xr telnet 1 client, which will improperly respond with .Dv WILL ECHO . If a .Dv WILL ECHO is received, a .Dv DONT ECHO will be sent in response. .It "DO TERMINAL-TYPE" Indicate a desire to be able to request the name of the type of terminal that is attached to the client side of the connection. .It "DO SGA" Indicate that it does not need to receive .Dv IAC GA , the go ahead command. .It "DO NAWS" Requests that the client inform the server when the window (display) size changes. .It "DO TERMINAL-SPEED" Indicate a desire to be able to request information about the speed of the serial line to which the client is attached. .It "DO XDISPLOC" Indicate a desire to be able to request the name of the X Window System display that is associated with the telnet client. .It "DO NEW-ENVIRON" Indicate a desire to be able to request environment variable information, as described in RFC 1572. .It "DO ENVIRON" Indicate a desire to be able to request environment variable information, as described in RFC 1408. .It "DO LINEMODE" Only sent if .Nm is compiled with support for linemode, and requests that the client do line by line processing. .It "DO TIMING-MARK" Only sent if .Nm is compiled with support for both linemode and kludge linemode, and the client responded with .Dv WONT LINEMODE . If the client responds with .Dv WILL TM , the it is assumed that the client supports kludge linemode. Note that the .Op Fl k option can be used to disable this. .It "DO AUTHENTICATION" Only sent if .Nm is compiled with support for authentication, and indicates a willingness to receive authentication information for automatic login. .It "DO ENCRYPT" Only sent if .Nm is compiled with support for data encryption, and indicates a willingness to decrypt the data stream. .El .Sh NOTES By default .Nm will read the .Em \&he , .Em \&hn , and .Em \&im capabilities from .Pa /etc/gettytab and use that information (if present) to determine what to display before the login: prompt. You can also use a System V style .Pa /etc/issue file by using the .Em \&if capability, which will override .Em \&im . The information specified in either .Em \&im or .Em \&if will be displayed to both console and remote logins. .\" .Sh ENVIRONMENT .Sh FILES .Bl -tag -width /usr/ucb/bftp -compact .It Pa /etc/services .It Pa /etc/gettytab .It Pa /etc/inittab (UNICOS systems only) .It Pa /etc/iptos (if supported) .It Pa /usr/ucb/bftp (if supported) .El .Sh "SEE ALSO" .Xr bftp 1 , .Xr login 1 , .Xr gettytab 5 , .Xr telnet 1 (if supported) .Sh STANDARDS .Bl -tag -compact -width RFC-1572 .It Cm RFC-854 .Tn TELNET PROTOCOL SPECIFICATION .It Cm RFC-855 TELNET OPTION SPECIFICATIONS .It Cm RFC-856 TELNET BINARY TRANSMISSION .It Cm RFC-857 TELNET ECHO OPTION .It Cm RFC-858 TELNET SUPPRESS GO AHEAD OPTION .It Cm RFC-859 TELNET STATUS OPTION .It Cm RFC-860 TELNET TIMING MARK OPTION .It Cm RFC-861 TELNET EXTENDED OPTIONS - LIST OPTION .It Cm RFC-885 TELNET END OF RECORD OPTION .It Cm RFC-1073 Telnet Window Size Option .It Cm RFC-1079 Telnet Terminal Speed Option .It Cm RFC-1091 Telnet Terminal-Type Option .It Cm RFC-1096 Telnet X Display Location Option .It Cm RFC-1123 Requirements for Internet Hosts -- Application and Support .It Cm RFC-1184 Telnet Linemode Option .It Cm RFC-1372 Telnet Remote Flow Control Option .It Cm RFC-1416 Telnet Authentication Option .It Cm RFC-1411 Telnet Authentication: Kerberos Version 4 .It Cm RFC-1412 Telnet Authentication: SPX .It Cm RFC-1571 Telnet Environment Option Interoperability Issues .It Cm RFC-1572 Telnet Environment Option .El .Sh BUGS Some .Tn TELNET commands are only partially implemented. .Pp -Because of bugs in the original 4.2 BSD +Because of bugs in the original +.Bx 4.2 .Xr telnet 1 , .Nm performs some dubious protocol exchanges to try to discover if the remote -client is, in fact, a 4.2 BSD +client is, in fact, a +.Bx 4.2 .Xr telnet 1 . .Pp Binary mode has no common interpretation except between similar operating systems (Unix in this case). .Pp The terminal type name received from the remote client is converted to lower case. .Pp .Nm Telnetd never sends .Tn TELNET .Dv IAC GA (go ahead) commands. .Sh HISTORY IPv6 support was added by WIDE/KAME project. Index: head/sbin/bsdlabel/bsdlabel.8 =================================================================== --- head/sbin/bsdlabel/bsdlabel.8 (revision 81621) +++ head/sbin/bsdlabel/bsdlabel.8 (revision 81622) @@ -1,898 +1,900 @@ .\" Copyright (c) 1987, 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Symmetric Computer Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgment: .\" 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. .\" .\" @(#)disklabel.8 8.2 (Berkeley) 4/19/94 .\" $FreeBSD$ .\" .Dd July 30, 1999 .Dt DISKLABEL 8 .Os .Sh NAME .Nm disklabel .Nd read and write disk pack label .Sh SYNOPSIS .Nm .Op Fl r .Ar disk .Nm .Fl w .Op Fl r .Op Fl n .Ar disk Ar disktype/auto .Oo Ar packid Oc .Nm .Fl e .Op Fl r .Op Fl n .Ar disk .Nm .Fl R .Op Fl r .Op Fl n .Ar disk Ar protofile .Nm .Op Fl NW .Ar disk .Pp .Nm .Fl B .Oo .Fl b Ar boot1 .Fl s Ar boot2 .Oc .Ar disk .Oo Ar disktype/auto Oc .Nm .Fl w .Fl B .Op Fl n .Oo .Fl b Ar boot1 .Fl s Ar boot2 .Oc .Ar disk Ar disktype/auto .Oo Ar packid Oc .Nm .Fl R .Fl B .Op Fl n .Oo .Fl b Ar boot1 .Fl s Ar boot2 .Oc .Ar disk Ar protofile .Oo Ar disktype/auto Oc .Sh DESCRIPTION .Nm Disklabel installs, examines or modifies the label on a disk drive or pack. When writing the label, it can be used to change the drive identification, the disk partitions on the drive, or to replace a damaged label. There are several forms of the command that read (display), install or edit the label on a disk. In addition, .Nm can install bootstrap code. .Ss Raw or in-core label .Pp The disk label is resident close to or at the beginning of each disk partition. For faster access, the kernel maintains a copy in core at all times. By default, most .Nm access the in-core copy of the label. To access the raw (on-disk) copy, use the .Fl r option. This option allows a label to be installed on a disk without kernel support for a label, such as when labels are first installed on a system; it must be used when first installing a label on a disk. The specific effect of .Fl r is described under each command. .Pp .Ss Disk device name .Pp All .Nm forms require a disk device name, which should always be the raw device name representing the disk or slice. For example .Pa da0 represents the entire disk irregardless of any DOS partitioning, and .Pa da0s1 represents a slice. Some devices, most notably .Ar ccd , require that the .Dq whole-disk (or .Dq c ) partition be specified. For example .Pa ccd0c . You do not have to include the .Pa /dev/ path prefix when specifying the device. .Nm will automatically prepend it. .Ss Reading the disk label .Pp To examine or save the label on a disk drive, use .Nm without options: .Pp .Nm .Op Fl r .Ar disk .Pp .Ar disk represents the raw disk in question, and may be in the form .Pa da0 or .Pa /dev/da0c . It will display all of the parameters associated with the drive and its partition layout. Unless the .Fl r flag is given, the kernel's in-core copy of the label is displayed; if the disk has no label, or the partition types on the disk are incorrect, the kernel may have constructed or modified the label. If the .Fl r flag is given, .Nm reads the label from the raw disk and displays it. Both versions are usually identical except in the case where a label has not yet been initialized or is corrupt. .Ss Writing a standard label .Pp To write a standard label, use the form .Pp .Nm .Fl w .Op Fl r .Op Fl n .Ar disk Ar disktype/auto .Oo Ar packid Oc .Pp .Nm .Fl w .Op Fl r .Op Fl n .Ar disk auto .Pp The required arguments to .Nm are the drive to be labeled and the drive type as described in the .Xr disktab 5 file. The drive parameters and partitions are taken from that file. If different disks of the same physical type are to have different partitions, it will be necessary to have separate disktab entries describing each, or to edit the label after installation as described below. The optional argument is a pack identification string, up to 16 characters long. The pack id must be quoted if it contains blanks. .Pp If the .Fl n flag is given, no data will be written to the device, and instead the disklabel that would have been written will be printed to stdout. .Pp If the .Fl r flag is given, the disk sectors containing the label and bootstrap will be written directly. A side-effect of this is that any existing bootstrap code will be overwritten and the disk rendered unbootable. See the boot options below for a method of writing the label and the bootstrap at the same time. If .Fl r is not specified, the existing label will be updated via the in-core copy and any bootstrap code will be unaffected. If the disk does not already have a label, the .Fl r flag must be used. In either case, the kernel's in-core label is replaced. .Pp For a virgin disk that is not known to .Xr disktab 5 , .Ar disktype can be specified as .Dq auto . In this case, the driver is requested to produce a virgin label for the disk. This might or might not be successful, depending on whether the driver for the disk is able to get the required data without reading anything from the disk at all. It will likely succeed for all SCSI disks, most IDE disks, and vnode devices. Writing a label to the disk is the only supported operation, and the .Ar disk itself must be provided as the canonical name, i.e. not as a full path name. .Pp For most harddisks, a label based on percentages for most partitions (and one partition with a size of .Ql * ) will produce a reasonable configuration. .Pp PC-based systems have special requirements in order for the BIOS to properly recognize a .Fx disklabel. Older systems may require what is known as a .Dq dangerously dedicated disklabel, which creates a fake DOS partition to work around problems older BIOSes have with modern disk geometries. On newer systems you generally want to create a normal DOS slice using .Ar fdisk and then create a .Fx disklabel within that slice. This is described later on in this page. .Pp Installing a new disklabel does not in of itself allow your system to boot a kernel using that label. You must also install boot blocks, which is described later on in this manual page. .Ss Editing an existing disk label .Pp To edit an existing disk label, use the form .Pp .Nm .Fl e .Op Fl r .Op Fl n .Ar disk .Pp This command reads the label from the in-core kernel copy, or directly from the disk if the .Fl r flag is also specified. The label is written to a file in ASCII and then supplied to an editor for changes. If no editor is specified in an .Ev EDITOR environment variable, .Xr vi 1 is used. When the editor terminates, the label file is used to rewrite the disk label. Existing bootstrap code is unchanged regardless of whether .Fl r was specified. If .Fl n is specified, no data will be written to the device, and instead the disklabel that would have been written will be printed to stdout. This is useful to see how a partitioning scheme will work out for a specific disk. .Ss Restoring a disk label from a file .Pp To restore a disk label from a file, use the form .Pp .Nm .Fl R .Op Fl r .Op Fl n .Ar disk Ar protofile .Pp .Nm is capable of restoring a disk label that was previously saved in a file in ASCII format. The prototype file used to create the label should be in the same format as that produced when reading or editing a label. Comments are delimited by .Ar \&# and newline. As when writing a new label, any existing bootstrap code will be clobbered if .Fl r is specified and will be unaffected otherwise. See the boot options below for a method of restoring the label and writing the bootstrap at the same time. If .Fl n is used, no data will be written to the device, and instead the disklabel that would have been written will be printed to stdout. This is useful to see how a partitioning scheme will work out for a specific disk. .Ss Enabling and disabling writing to the disk label area .Pp By default, it is not possible to write to the disk label area at the beginning of a disk. The disk driver silently ignores any attempt to do so. If you need to write to this area (for example, to obliterate the label), use the form .Pp .Nm .Op Fl W .Ar disk .Pp To disallow writing to the label area after previously allowing it, use the command .Pp .Nm .Op Fl N .Ar disk .Ss Installing bootstraps .Pp The final three forms of .Nm are used to install bootstrap code. If you are creating a .Dq dangerously-dedicated partition for compatibility with older PC systems, you generally want to specify the raw disk name such as .Pa da0 . If you are creating a label within an existing DOS slice, you should specify the slice name such as .Pa da0s1 . Making a partition bootable can be tricky. If you are using a normal DOS slice you typically install (or leave) a standard MBR on the base disk and then install the .Fx bootblocks in the slice. .Pp .Nm .Fl B .Oo .Fl b Ar boot1 .Fl s Ar boot2 .Oc .Ar disk .Oo Ar disktype Oc .Pp This form installs the bootstrap only. It does not change the disk label. You should never use this command on a base disk unless you intend to create a .Dq dangerously-dedicated disk, such as .Ar da0 . This command is typically run on a slice such as .Ar da0s1 . .Pp .Nm .Fl w .Fl B .Op Fl n .Oo .Fl b Ar boot1 .Fl s Ar boot2 .Oc .Ar disk Ar disktype .Oo Ar packid Oc .Pp This form corresponds to the .Dq write label command described above. In addition to writing a new volume label, it also installs the bootstrap. If run on a base disk this command will create a .Dq dangerously-dedicated label. This command is normally run on a slice rather than a base disk. If .Fl n is used, no data will be written to the device, and instead the disklabel that would have been written will be printed to stdout. .Pp .Nm .Fl R .Fl B .Op Fl n .Oo .Fl b Ar boot1 .Fl s Ar boot2 .Oc .Ar disk Ar protofile .Oo Ar disktype Oc .Pp This form corresponds to the .Dq restore label command described above. In addition to restoring the volume label, it also installs the bootstrap. If run on a base disk this command will create a .Dq dangerously-dedicated label. This command is normally run on a slice rather than a base disk. .Pp The bootstrap commands always access the disk directly, so it is not necessary to specify the .Fl r flag. If .Fl n is used, no data will be written to the device, and instead the disklabel that would have been written will be printed to stdout. .Pp The bootstrap code is comprised of two boot programs. Specify the name of the boot programs to be installed in one of these ways: .Bl -enum .It Specify the names explicitly with the .Fl b and .Fl s flags. .Fl b indicates the primary boot program and .Fl s the secondary boot program. The boot programs are located in .Pa /boot . .It If the .Fl b and .Fl s flags are not specified, but .Ar disktype was specified, the names of the programs are taken from the .Dq b0 and .Dq b1 parameters of the .Xr disktab 5 entry for the disk if the disktab entry exists and includes those parameters. .It Otherwise, the default boot image names are used: .Pa /boot/boot1 and .Pa /boot/boot2 for the standard stage1 and stage2 boot images (details may vary on architectures like the Alpha, where only a single-stage boot is used). .El .Ss Initializing/Formatting a bootable disk from scratch .Pp To initialize a disk from scratch the following sequence is recommended. Please note that this will wipe everything that was previously on the disk, including any .No non- Ns Fx slices. .Bl -enum .It Use .Ar fdisk to initialize the DOS partition table, creating a real whole-disk slice to hold the .Fx disklabel, and installing a master boot record. .It Use .Ar disklabel to initialize a virgin .Fx disklabel and install .Fx boot blocks. .It Use .Ar disklabel to edit your newly created label, adding appropriate partitions. .It Finally newfs the filesystem partitions you created in the label. A typical disklabel partitioning scheme would be to have an .Dq a partition of approximately 128MB to hold the root filesystem, a .Dq b partition for swap, a .Dq d partition for /var (usually 128MB), an .Dq e partition for /var/tmp (usually 128MB), an .Dq f partition for /usr (usually around 2G), and finally a .Dq g partition for /home (usually all remaining space). Your mileage may vary. .El .Pp .Nm fdisk Fl BI Ar da0 .Pp .Nm .Fl w .Fl r .Fl B .Ar da0s1 auto .Pp .Pp .Nm .Fl e .Ar da0s1 .Sh FILES .Bl -tag -width Pa -compact .It Pa /etc/disktab .It Pa /boot/ .It Pa /boot/boot .El .Sh SAVED FILE FORMAT .Nm uses an ASCII version of the label when examining, editing or restoring a disk label. The format is: .Bd -literal -offset 4n # /dev/da1c: type: SCSI disk: da0s1 label: flags: bytes/sector: 512 sectors/track: 51 tracks/cylinder: 19 sectors/cylinder: 969 cylinders: 1211 sectors/unit: 1173930 rpm: 3600 interleave: 1 trackskew: 0 cylinderskew: 0 headswitch: 0 # milliseconds track-to-track seek: 0 # milliseconds drivedata: 0 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 81920 0 4.2BSD 1024 8192 16 # (Cyl. 0 - 84*) b: 160000 81920 swap # (Cyl. 84* - 218*) c: 1173930 0 unused 0 0 # (Cyl. 0 - 1211*) h: 962010 211920 vinum # (Cyl. 218*- 1211*) .Ed .Pp Lines starting with a # mark are comments. Most of the other specifications are no longer used. The ones which must still be set correctly are: .Pp .Bl -hang -width 20n .It Nm label is an optional label, set by the .Ar packid option when writing a label. .It Nm flags Flags may be .Ar removable , .Ar ecc or .Ar badsect . .Ar removable is set for removable media drives, but no current .Fx driver evaluates this flag. .Ar ecc is no longer supported; .Ar badsect specifies that the drive can perform bad sector remapping. .It Nm sectors/unit describes the total size of the disk. This value must be correct. .It Nm the partition table This is the .Ux partition table, not the Microsoft partition table described in .Xr fdisk 8 . .El .Pp The partition table can have up to 8 entries. It contains the following information: .Bl -hang -width 10n .It identifier The partition identifier is a single letter in the range .Dq a to .Dq h . By convention, partition .Dq c is reserved to describe the entire disk. .It size is the size of the partition in sectors, .Cm K (kilobytes - 1024), .Cm M (megabytes - 1024*1024), .Cm G (gigabytes - 1024*1024*1024), .Cm % (percentage of free space AFTER removing any fixed-size partitions other than partition .Dq c) , or .Cm * (all remaining free space AFTER fixed-size and percentage partitions). For partition .Dq c , a size of .Cm * indicates the entire disk. Lowercase versions of .Cm K , M , and .Cm G are allowed. Size and type should be specifed without any spaces between them. .Pp Example: 2097152, 1g, 1024m and 1048576k are all the same size (assuming 512-byte sectors). .It offset is the offset of the start of the partition from the beginning of the drive in sectors, or .Cm * to have .Nm calculate the correct offset to use (the end of the previous partition plus one, ignoring partition .Dq c . For partition .Dq c , .Cm * will be interpreted as an offset of 0. .It fstype describes the purpose of the partition. The example shows all currently used partition types. For UFS file systems and ccd partitions, use type .Cm 4.2BSD . For Vinum drives, use type .Cm vinum . Other common types are .Cm unused and .Cm swap . By convention, partition .Dq c represents the entire slice and should be of type .Cm unused , though .Nm does not enforce this convention. .Nm also knows about a number of other partition types, none of which are in current use. See the definitions starting with .Dv FS_UNUSED in .Pa /usr/include/sys/disklabel.h for more details. .It fsize For .Cm 4.2BSD and LFS file systems only, the fragment size. Defaults to 8192 for partitions smaller than 1 GB, 16384 for partitions 1GB or larger. .It bsize For .Cm 4.2BSD and LFS file systems only, the block size. Defaults to 1024 for partitions smaller than 1 GB, 4096 for partitions 1GB or larger. .It bps/cpg For .Cm 4.2BSD file systems, the number of cylinders in a cylinder group. For LFS file systems, the segment shift value. Defaults to 16 for partitions smaller than 1 GB, 64 for partitions 1GB or larger. .El .Pp The remainder of the line is a comment and shows the cylinder allocations based on the obsolete (but possibly correct) geometry information about the drive. The asterisk (*) indicates that the partition does not begin or end exactly on a cylinder boundary. .Sh EXAMPLES .Dl disklabel da0 .Pp Display the in-core label for .Pa da0s1 as obtained via .Pa /dev/da0s1 . When reading a label, .Fx will allow you to specify the base disk name even if the label resides on a slice. However, to be proper you should specify the base disk name only if you are using a .Dq dangerously-dedicated label. Normally you specify the slice. .Pp .Dl disklabel da0s1 > savedlabel .Pp Save the in-core label for .Pa da0s1 into the file .Pa savedlabel . This file can be used with the .Fl R flag to restore the label at a later date. .Pp .Dl disklabel -w -r /dev/da0s1 da2212 foo .Pp Create a label for .Pa da0s1 based on information for .Dq da2212 found in .Pa /etc/disktab . Any existing bootstrap code will be clobbered. .Pp .Dl disklabel -e -r da0s1 .Pp Read the on-disk label for .Pa da0s1 , edit it and reinstall in-core as well as on-disk. Existing bootstrap code is unaffected. .Pp .Dl disklabel -e -r -n da0s1 .Pp Read the on-disk label for .Pa da0s1 , edit it, and display what the new label would be (in sectors). It does NOT install the new label either in-core or on-disk. .Pp .Dl disklabel -r -w da0s1 auto .Pp Try to auto-detect the required information from .Pa da0s1 , and write a new label to the disk. Use another disklabel -e command to edit the partitioning and file system information. .Pp .Dl disklabel -R da0s1 savedlabel .Pp Restore the on-disk and in-core label for .Pa da0s1 from information in .Pa savedlabel . Existing bootstrap code is unaffected. .Pp .Dl disklabel -R -n da0s1 label_layout .Pp Display what the label would be for .Pa da0s1 using the partition layout in .Pa label_layout . This is useful for determining how much space would be alloted for various partitions with a labelling scheme using .Cm % Ns -based or .Cm * partition sizes. .Pp .Dl disklabel -B da0s1 .Pp Install a new bootstrap on .Pa da0s1 . The boot code comes from .Pa /boot/boot1 and possibly .Pa /boot/boot2 . On-disk and in-core labels are unchanged. .Pp .Dl disklabel -w -B /dev/da0s1 -b newboot1 -s newboot da2212 .Pp Install a new label and bootstrap. The label is derived from disktab information for .Dq da2212 and installed both in-core and on-disk. The bootstrap code comes from the files .Pa /boot/newboot1 and .Pa /boot/newboot2 . .Pp .Dl dd if=/dev/zero of=/dev/da0 bs=512 count=32 .Dl fdisk -BI da0 .Dl dd if=/dev/zero of=/dev/da0s1 bs=512 count=32 .Dl disklabel -w -r -B da0s1 auto .Dl disklabel -e da0s1 .Pp Completely wipe any prior information on the disk, creating a new bootable disk with a DOS partition table containing one .Dq whole-disk slice. Then initialize the slice, then edit it to your needs. The .Pa dd commands are optional, but may be necessary for some BIOSes to properly recognize the disk. .Pp This is an example disklabel that uses some of the new partition size types such as .Cm % , M , G , and .Cm * , which could be used as a source file for .Pp .Dl disklabel -R ad0s1c new_label_file .Bd -literal -offset 4n # /dev/ad0s1c: type: ESDI disk: ad0s1 label: flags: bytes/sector: 512 sectors/track: 63 tracks/cylinder: 16 sectors/cylinder: 1008 cylinders: 40633 sectors/unit: 40959009 rpm: 3600 interleave: 1 trackskew: 0 cylinderskew: 0 headswitch: 0 # milliseconds track-to-track seek: 0 # milliseconds drivedata: 0 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 400M 0 4.2BSD 4096 16384 75 # (Cyl. 0 - 812*) b: 1G * swap c: * * unused e: 204800 * 4.2BSD f: 5g * 4.2BSD g: * * 4.2BSD .Ed .Sh SEE ALSO .Xr ccd 4 , .Xr disklabel 5 , .Xr disktab 5 , .Xr boot0cfg 8 , .Xr fdisk 8 , .Xr vinum 8 .Sh DIAGNOSTICS The kernel device drivers will not allow the size of a disk partition to be decreased or the offset of a partition to be changed while it is open. Some device drivers create a label containing only a single large partition if a disk is unlabeled; thus, the label must be written to the .Dq a partition of the disk while it is open. This sometimes requires the desired label to be set in two steps, the first one creating at least one other partition, and the second setting the label on the new partition while shrinking the .Dq a partition. .Pp On some machines the bootstrap code may not fit entirely in the area allocated for it by some filesystems. As a result, it may not be possible to have filesystems on some partitions of a .Dq bootable disk. When installing bootstrap code, .Nm checks for these cases. If the installed boot code would overlap a partition of type FS_UNUSED it is marked as type FS_BOOT. The .Xr newfs 8 utility will disallow creation of filesystems on FS_BOOT partitions. Conversely, if a partition has a type other than FS_UNUSED or FS_BOOT, .Nm will not install bootstrap code that overlaps it. .Sh BUGS When a disk name is given without a full pathname, the constructed device name uses the .Dq c partition. .Pp For the i386 architecture, the primary bootstrap sector contains an embedded .Em fdisk table. .Nm Disklabel takes care to not clobber it when installing a bootstrap only .Pq Fl B , or when editing an existing label .Pq Fl e , but it unconditionally writes the primary bootstrap program onto the disk for .Fl w or .Fl R , thus replacing the .Em fdisk table by the dummy one in the bootstrap program. This is only of -concern if the disk is fully dedicated, so that the BSD disklabel +concern if the disk is fully dedicated, so that the +.Bx +disklabel starts at absolute block 0 on the disk. .Pp .Nm does not perform all possible error checking. Warning *is* given if partitions overlap; if an absolute offset does not match the expected offset; if the .Dq c partition does not start at 0 or does not cover the entire slice; if a partition runs past the end of the device; and a number of other errors; but no warning is given if space remains unused. Index: head/sbin/camcontrol/camcontrol.8 =================================================================== --- head/sbin/camcontrol/camcontrol.8 (revision 81621) +++ head/sbin/camcontrol/camcontrol.8 (revision 81622) @@ -1,747 +1,749 @@ .\" .\" Copyright (c) 1998, 1999, 2000 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 September 14, 1998 .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 start .Op device id .Op generic args .Nm .Ic stop .Op device id .Op generic args .Nm .Ic eject .Op device id .Op generic args .Nm .Ic rescan .Aq bus Ns Op :target:lun .Nm .Ic reset .Aq 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 \*(Ba 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 c Ar cmd Op args .Op Fl i Ar len Ar fmt .Bk -words .Op Fl o Ar len Ar fmt Op args .Ek .Nm .Ic debug .Op Fl I .Op Fl T .Op Fl S .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 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 w .Op Fl y .Nm .Ic help .Sh DESCRIPTION .Nm is a utility designed to provide a way for users to access and control the .Fx CAM subsystem. .Pp .Nm 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 .Nm 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". Note that character device node names (e.g. /dev/rsd0.ctl) are .Em not allowed here. .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. .Nm 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 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 eject Send the SCSI Start/Stop Unit (0x1B) command to the given device with the start bit cleared and the eject bit set. .It Ic rescan Tell the kernel to scan 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 only specify a bus to scan, or a lun. Scanning all luns on a target isn't supported. .It Ic reset Tell the kernel to reset 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 don't support the requested format, return the data in an alternate format, along with sense information indicating that the requested data format isn't supported. .Nm 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 doesn't 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 SCSI CDB to any device. The .Ic cmd function requires the .Fl c argument to specify the CDB. 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 transfered to or from the SCSI device in question, you MUST specify either .Fl i or .Fl o . .Bl -tag -width 17n .It Fl c Ar cmd Op args This specifies the SCSI CDB. CDBs may be 6, 10, 12 or 16 bytes. .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. .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 T Enable CAM_DEBUG_TRACE printfs. .It Fl S Enable CAM_DEBUG_SUBTRACE 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 don't 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. .Nm 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 don't 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 O Ar offset Set the command delay offset. .It Fl q Be quiet, don't print anything. This is generally useful when you want to set a parameter, but don't 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 doesn't 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. .Pp .Bl -tag -width 6n .It Fl q Be quiet, don't print any status messages. This option will not disable the questions, however. To disable questions, use the .Fl y argument, below. .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 Don't 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 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. .Nm 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. .Pp .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. .Nm 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. .Pp .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. .Pp .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 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. .Pp .Bd -literal -offset indent camcontrol negotiate -n da -u 4 -T disable .Ed .Pp Disable tagged queueing for da4. .Pp .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. .Sh SEE ALSO .Xr cam 3 , .Xr cam_cdbparse 3 , .Xr cam 4 , .Xr pass 4 , .Xr xpt 4 .Sh HISTORY The .Nm command 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 386BSD 0.1.2.4, and first appeared in +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 doesn't 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: head/sbin/comcontrol/comcontrol.8 =================================================================== --- head/sbin/comcontrol/comcontrol.8 (revision 81621) +++ head/sbin/comcontrol/comcontrol.8 (revision 81622) @@ -1,62 +1,63 @@ .\" $FreeBSD$ .Dd May 15, 1994 .Dt COMCONTROL 8 .Os .Sh NAME .Nm comcontrol .Nd control a special tty device .Sh SYNOPSIS .Nm .Ar special_device .Op dtrwait Ar number .Op drainwait Ar number .Sh DESCRIPTION .Nm Comcontrol is used to examine and modify some of the special characteristics of the specified tty device. If no arguments other than the device (or "-" for stdin) are specified, it prints the settings of all controllable characteristics. This usage requires only read access on the device. Only the superuser can change the settings. .Pp The following options are available: .Bl -tag -width indent .It Cm dtrwait Ar number Set the time to wait after dropping DTR to the given number. The units are hundredths of a second. The default is 300 hundredths, i.e., 3 seconds. This option needed mainly to set proper recover time after modem reset. .It Cm drainwait Ar number Set the time to wait for output drain to the given number. The units are seconds. The default is 5 minutes, 0 means waiting forever. This option needed mainly to specify upper limit of minutes to prevent modem hanging. .El .Pp The standard way to use .Nm is to put invocations of it in the .Pa /etc/rc.serial startup script. .Sh SEE ALSO .Xr stty 1 , .Xr sio 4 .Sh FILES .Bl -tag -width /dev/ttyd? -compact .It Pa /dev/ttyd? dialin devices, hardwired terminals .It Pa /dev/cuaa? dialout devices .El .Sh AUTHORS .An Christopher G. Demetriou .Sh HISTORY -Originally part of cgd's com package patches, version 0.2.1, to 386BSD 0.1. +Originally part of cgd's com package patches, version 0.2.1, to +.Bx 386 0.1 . Once controlled bidirectional capabilities. Little is left to control now that these capabilities are standard. Index: head/sbin/cxconfig/cxconfig.8 =================================================================== --- head/sbin/cxconfig/cxconfig.8 (revision 81621) +++ head/sbin/cxconfig/cxconfig.8 (revision 81622) @@ -1,324 +1,329 @@ .\" $FreeBSD$ .Dd December 2, 1994 .Dt CXCONFIG 8 .Os .Sh NAME .Nm cxconfig .Nd channel options management utility for Cronyx-Sigma adapter .Sh SYNOPSIS .Nm .Op Fl a .Op Ar Op Ar