Index: head/bin/ln/symlink.7 =================================================================== --- head/bin/ln/symlink.7 (revision 131471) +++ head/bin/ln/symlink.7 (revision 131472) @@ -1,453 +1,453 @@ .\" 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. .\" 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 file system 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 nine system calls that do not follow links, and which operate on the symbolic link itself. They are: .Xr lchflags 2 , .Xr lchmod 2 , .Xr lchown 2 , .Xr lstat 2 , .Xr lutimes 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 flags, access permissions, owner/group and modification time of an existing symbolic link can be changed by means of the .Xr lchflags 2 , .Xr lchmod 2 , .Xr lchown 2 , -and +and .Xr lutimes 2 system calls, respectively. Of these, only the flags are used by the system; the access permissions and ownership are ignored. .Pp The .Bx 4.4 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 .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 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 .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 lchflags 2 , .Xr lchmod 2 , .Xr lchown 2 , .Xr lstat 2 , .Xr lutimes 2 , .Xr readlink 2 , .Xr rename 2 , .Xr symlink 2 , .Xr unlink 2 , .Xr fts 3 , .Xr remove 3 , .Xr chown 8 Index: head/gnu/lib/libdialog/dialog.3 =================================================================== --- head/gnu/lib/libdialog/dialog.3 (revision 131471) +++ head/gnu/lib/libdialog/dialog.3 (revision 131472) @@ -1,807 +1,807 @@ .\" .\" Copyright (c) 1995, Jordan Hubbard .\" .\" All rights reserved. .\" .\" This manual page may be used, modified, copied, distributed, and .\" sold, in both source and binary form provided that the above .\" copyright and these terms are retained, verbatim, as the first .\" lines of this file. Under no circumstances is the author .\" responsible for the proper functioning of the software described herein .\" nor does the author assume any responsibility for damages incurred with .\" its use. .\" .\" $FreeBSD$ .\" .Dd January 1, 2000 .Dt DIALOG 3 .Os .Sh NAME .Nm draw_shadow , .Nm draw_box , .Nm line_edit , .Nm strheight , .Nm strwidth , .Nm dialog_create_rc , .Nm dialog_yesno , .Nm dialog_noyes , .Nm dialog_prgbox , .Nm dialog_msgbox , .Nm dialog_textbox , .Nm dialog_menu , .Nm dialog_checklist , .Nm dialog_radiolist , .Nm dialog_inputbox , .Nm dialog_clear_norefresh , .Nm dialog_clear , .Nm dialog_update , .Nm dialog_fselect , .Nm dialog_notify , .Nm dialog_mesgbox , .Nm dialog_gauge , .Nm init_dialog , .Nm end_dialog , .Nm use_helpfile , .Nm use_helpline , .Nm get_helpline , .Nm restore_helpline , .Nm dialog_ftree , .Nm dialog_tree .Nd provide a simple ncurses-based GUI interface .Sh SYNOPSIS .In dialog.h .Ft "void" .Fn draw_shadow "WINDOW *win" "int y" "int x" "int height" "int width" .Ft "void" .Fn draw_box "WINDOW *win" "int y" "int x" "int height" "int width" "chtype box" "chtype border" .Ft "int" .Fo line_edit .Fa "WINDOW *dialog" .Fa "int box_y" .Fa "int box_x" .Fa "int flen" .Fa "int box_width" .Fa "chtype attr" .Fa "int first" .Fa "unsigned char *result" .Fa "int attr_mask" .Fc .Ft "int" .Fn strheight "const char *p" .Ft "int" .Fn strwidth "const char *p" .Ft "void" .Fn dialog_create_rc "unsigned char *filename" .Ft "int" .Fn dialog_yesno "unsigned char *title" "unsigned char *prompt" "int height" "int width" .Ft "int" .Fn dialog_noyes "unsigned char *title" "unsigned char *prompt" "int height" "int width" .Ft "int" .Fn dialog_prgbox "unsigned char *title" "const unsigned char *line" "int height" "int width" "int pause" "int use_shell" .Ft "int" .Fn dialog_textbox "unsigned char *title" "unsigned char *file" "int height" "int width" .Ft "int" .Fo dialog_menu .Fa "unsigned char *title" .Fa "unsigned char *prompt" .Fa "int height" .Fa "int width" .Fa "int menu_height" .Fa "int cnt" .Fa "void *it" .Fa "unsigned char *result" .Fa "int *ch" .Fa "int *sc" .Fc .Ft "int" .Fn dialog_checklist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result" .Ft "int" .Fn dialog_radiolist "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int list_height" "int cnt" "void *it" "unsigned char *result" .Ft "int" .Fn dialog_inputbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" "unsigned char *result" .Ft "char *" .Fn dialog_fselect "char *dir" "char *fmask" .Ft "int" .Fn dialog_dselect "char *dir" "char *fmask" .Ft "void" .Fn dialog_notify "char *msg" .Ft "int" .Fn dialog_mesgbox "unsigned char *title" "unsigned char *prompt" "int height" "int width" .Ft "void" .Fn dialog_gauge "char *title" "char *prompt" "int y" "int x" "int height" "int width" "int perc" .Ft "void" .Fn use_helpfile "char *hfile" .Ft "void" .Fn use_helpline "char *hline" .Ft "char *" .Fn get_helpline "void" .Ft "void" .Fn dialog_clear_norefresh "void" .Ft "void" .Fn dialog_clear "void" .Ft "void" .Fn dialog_update "void" .Ft "void" .Fn init_dialog "void" .Ft "void" .Fn end_dialog "void" .Ft "int" .Fn dialog_ftree "unsigned char *filename" "unsigned char FS" "unsigned char *title" "unsigned char *prompt" "int height" "int width" "int menu_height" "unsigned char **result" -.Ft "int" -.Fo dialog_tree -.Fa "unsigned char **names" +.Ft "int" +.Fo dialog_tree +.Fa "unsigned char **names" .Fa "int size" -.Fa "unsigned char FS" -.Fa "unsigned char *title" +.Fa "unsigned char FS" +.Fa "unsigned char *title" .Fa "unsigned char *prompt" -.Fa "int height" -.Fa "int width" +.Fa "int height" +.Fa "int width" .Fa "int menu_height" .Fa "unsigned char **result" .Fc .Sh DESCRIPTION The dialog library attempts to provide a fairly simplistic set of fixed-presentation menus, input boxes, gauges, file requestors and other general purpose GUI (a bit of a stretch, since it uses ncurses) objects. Since the library also had its roots in a shell-script writer's utility (see the .Xr dialog 1 command), the early API was somewhat primitively based on strings being passed in or out and parsed. This API was later extended to take either the original arguments or arrays of .Va dialogMenuItem structures, giving the user much more control over the internal behavior of each control. The .Va dialogMenuItem structure internals are public: .Bd -literal -offset indent typedef struct _dmenu_item { char *prompt; char *title; int (*checked)(struct _dmenu_item *self); int (*fire)(struct _dmenu_item *self); int (*selected)(struct _dmenu_item *self, int is_selected); void *data; char lbra, mark, rbra; long aux; } dialogMenuItem; .Ed .Pp The .Dv prompt and .Dv title strings are pretty much self-explanatory, and the .Va checked and .Va fire function pointers provide optional display and action hooks (the .Dv data variable being available for the convenience of those hooks) when more tightly coupled feedback between a menu object and user code is required. The .Va selected hook also allows you to verify whether or not a given item is selected (the cursor is over it) for implementing pretty much any possible context-sensitive behavior. A number of clever tricks for simulating various kinds of item types can also be done by adjusting the values of .Va lbra (default: '['), .Va mark (default: '*' for radio menus, 'X' for check menus) and .Va rbra (default: ']') and declaring a reasonable .Va checked hook, which should return TRUE for the .Dq marked state and FALSE for .Dq unmarked . The .Va aux field is not used internally, and is available for miscellaneous usage. If an item has a .Va fire hook associated with it, it will also be called whenever the item is "toggled" in some way and should return one of the following codes: .Bd -literal -offset 4n #define DITEM_SUCCESS 0 /* Successful completion */ #define DITEM_FAILURE 1 /* Failed to "fire" */ .Ed .Pp The following flags are in the upper 16 bits of return status: .Bd -literal -offset 4n #define DITEM_LEAVE_MENU (1 << 16) #define DITEM_REDRAW (1 << 17) #define DITEM_RECREATE (1 << 18) #define DITEM_RESTORE (1 << 19) #define DITEM_CONTINUE (1 << 20) .Ed .Pp Two special globals also exist for putting a dialog at any arbitrary X,Y location (the early designers rather short-sightedly made no provisions for this). If set to zero, the default centering behavior will be in effect. .Pp Below is a short description of the various functions: .Pp The .Fn draw_shadow function draws a shadow in curses window .Va win using the dimensions of .Va x , y , width and .Va height . .Pp The .Fn draw_box function draws a bordered box using the dimensions of .Va x , y , width and .Va height . The attributes from .Va box and .Va border are used, if specified, while painting the box and border regions of the object. .Pp The .Fn line_edit function invokes a simple line editor with an edit box of dimensions .Va box_x , box_y and .Va box_width . The field length is constrained by .Va flen , starting at the .Va first character specified and optionally displayed with character attributes .Va attr . The string being edited is stored in .Va result . Returns 0 on success, 1 on Cancel, and -1 on failure or ESC. .Pp The .Fn strheight function returns the height of string in .Va p , counting newlines. .Pp The .Fn strwidth function returns the width of string in .Va p , counting newlines. .Pp The .Fn dialog_create_rc function dumps dialog library settings into .Pa filename for later retrieval as defaults. Returns 0 on success, -1 on failure. .Pp The .Fn dialog_yesno function displays a text box using .Va title and .Va prompt strings of dimensions .Va height and .Va width . Also paint a pair of .Em Yes and .Em \&No buttons at the bottom. The default selection is .Em Yes . If the .Em Yes button is chosen, return FALSE. If .Em \&No , return TRUE. .Pp The .Fn dialog_noyes function is the same as .Fn dialog_yesno , except the default selection is .Em \&No . .Pp The .Fn dialog_prgbox function displays a text box of dimensions .Va height and .Va width containing the output of command .Va line . If .Va use_shell is TRUE, .Va line is passed as an argument to .Xr sh 1 , otherwise it is simply passed to .Xr exec 3 . If .Va pause is TRUE, a final confirmation requestor will be put up when execution terminates. Returns 0 on success, -1 on failure. .Pp The .Fn dialog_textbox function displays a text box containing the contents of .Va file with dimensions of .Va height and .Va width . .Pp The .Fn dialog_menu function displays a menu of dimensions .Va height and .Va width with an optional internal menu height of .Va menu_height . The .Va cnt and .Va it arguments are of particular importance since they, together, determine which of the 2 available APIs to use. To use the older and traditional interface, .Va cnt should be a positive integer representing the number of string pointer pairs to find in .Va it (which should be of type .Ft char "**" ) , the strings are expected to be in prompt and title order for each item and the .Va result parameter is expected to point to an array where the prompt string of the item selected will be copied. To use the newer interface, .Va cnt should be a .Va negative integer representing the number of .Va dialogMenuItem structures pointed to by .Va it (which should be of type .Vt dialogMenuItem "*" ) , one structure per item. In the new interface, the .Va result variable is used as a simple boolean (not a pointer) and should be NULL if .Va it only points to menu items and the default OK and Cancel buttons are desired. If .Va result is non-NULL, then .Va it is actually expected to point 2 locations .Va past the start of the menu item list. .Va it is then expected to point to an item representing the Cancel button, from which the .Va prompt and .Va fire actions are used to override the default behavior, and .Va it to the same for the OK button. .Pp Using either API behavior, the .Va ch and .Va sc values may be passed in to preserve current item selection and scroll position values across calls. .Pp The .Fn dialog_checklist function displays a menu of dimensions .Va height and .Va width with an optional internal menu height of .Va list_height . The .Va cnt and .Va it arguments are of particular importance since they, together, determine which of the 2 available APIs to use. To use the older and traditional interface, .Va cnt should be a positive integer representing the number of string pointer tuples to find in .Va it (which should be of type .Ft "char **" ) , the strings are expected to be in prompt, title and state ("on" or "off") order for each item and the .Va result parameter is expected to point to an array where the prompt string of the item(s) selected will be copied. To use the newer interface, .Va cnt should be a .Em negative integer representing the number of .Ft dialogMenuItem structures pointed to by .Va it (which should be of type .Ft "dialogMenuItem *" ) , one structure per item. In the new interface, the .Va result variable is used as a simple boolean (not a pointer) and should be NULL if .Va it only points to menu items and the default OK and Cancel buttons are desired. If .Va result is non-NULL, then .Va it is actually expected to point 2 locations .Va past the start of the menu item list. .Va it is then expected to point to an item representing the Cancel button, from which the .Va prompt and .Va fire actions are used to override the default behavior, and .Va it to the same for the OK button. .Pp In the standard API model, the menu supports the selection of multiple items, each of which is marked with an `X' character to denote selection. When the OK button is selected, the prompt values for all items selected are concatenated into the .Va result string. .Pp In the new API model, it is not actually necessary to preserve "checklist" semantics at all since practically everything about how each item is displayed or marked as "selected" is fully configurable. You could have a single checklist menu that actually contained a group of items with "radio" behavior, "checklist" behavior and standard menu item behavior. The only reason to call .Fn dialog_checklist over .Fn dialog_radiolist in the new API model is to inherit the base behavior, you're no longer constrained by it. .Pp Returns 0 on success, 1 on Cancel, and -1 on failure or ESC. .Pp The .Fn dialog_radiolist function displays a menu of dimensions .Va height and .Va width with an optional internal menu height of .Va list_height . The .Va cnt and .Va it arguments are of particular importance since they, together, determine which of the 2 available APIs to use. To use the older and traditional interface, .Va cnt should be a positive integer representing the number of string pointer tuples to find in .Va it (which should be of type .Ft "char **" ) , the strings are expected to be in prompt, title and state ("on" or "off") order for each item and the .Va result parameter is expected to point to an array where the prompt string of the item(s) selected will be copied. To use the newer interface, .Va cnt should be a .Dv negative integer representing the number of .Ft dialogMenuItem structures pointed to by .Va it (which should be of type .Ft "dialogMenuItem *" , one structure per item. In the new interface, the .Va result variable is used as a simple boolean (not a pointer) and should be NULL if .Va it only points to menu items and the default OK and Cancel buttons are desired. If .Va result is non-NULL, then .Va it is actually expected to point 2 locations .Va past the start of the menu item list. .Va it is then expected to point to an item representing the Cancel button, from which the .Va prompt and .Va fire actions are used to override the default behavior, and .Va it does the same for the traditional OK button. .Pp In the standard API model, the menu supports the selection of only one of multiple items, the currently active item marked with an `*' character to denote selection. When the OK button is selected, the prompt value for this item is copied into the .Va result string. .Pp In the new API model, it is not actually necessary to preserve "radio button" semantics at all since practically everything about how each item is displayed or marked as "selected" is fully configurable. You could have a single radio menu that actually contained a group of items with "checklist" behavior, "radio" behavior and standard menu item behavior. The only reason to call .Fn dialog_radiolist over .Fn dialog_checklistlist in the new API model is to inherit the base behavior. .Pp Returns 0 on success, 1 on Cancel and -1 on failure or ESC. .Pp The .Fn dialog_inputbox function displays a single-line text input field in a box displaying .Va title and .Va prompt of dimensions .Va height and .Va width . The field entered is stored in .Va result . .Pp Returns 0 on success, -1 on failure or ESC. .Pp The .Fn dialog_fselect function brings up a file selector dialog starting at .Va dir and showing only those file names matching .Va fmask . .Pp Returns filename selected or NULL. .Pp The .Fn dialog_dselect function brings up a directory selector dialog starting at .Va dir and showing only those directory names matching .Va fmask . .Pp Returns directory name selected or NULL. .Pp The .Fn dialog_notify function brings up a generic "hey, you!" notifier dialog containing .Va msg . .Pp The .Fn dialog_mesgbox function displays a notifier dialog, but with more control over .Va title , .Va prompt , .Va width and .Va height . This object will also wait for user confirmation, unlike .Fn dialog_notify . .Pp Returns 0 on success, -1 on failure. .Pp The .Fn dialog_gauge function displays a horizontal bar-graph style gauge. A value of .Em 100 for .Em perc constitutes a full gauge, a value of .Em 0 an empty one. .Pp The .Fn use_helpfile function for any menu supporting context sensitive help, invokes the text box object on this file whenever the .Em F1 key is pressed. .Pp The .Fn use_helpline function displays this line of helpful text below any menu being displayed. .Pp The .Fn get_helpline function gets the current value of the helpful text line. .Pp The .Fn dialog_clear_norefresh function clears the screen back to the dialog background color, but don't refresh the contents just yet. .Pp The .Fn dialog_clear function clears the screen back to the dialog background color immediately. .Pp The .Fn dialog_update function does any pending screen refreshes now. .Pp The .Fn init_dialog function initializes the dialog library (call this routine before any other dialog API calls). .Pp The .Fn end_dialog function shuts down the dialog library (call this if you need to get back to sanity). .Pp The .Fn dialog_ftree function shows a tree described by the data from the file .Pa filename . The data in the file should look like .Xr find 1 output. For the .Xr find 1 output, the field separator .Va FS will be .Dq \&/ . If .Va height and .Va width are positive numbers, they set the absolute size of the whole .Fn dialog_ftree box. If .Va height and .Va width are negative numbers, the size of the .Fn dialog_ftree box will be calculated automatically. .Va menu_height sets the height of the tree subwindow inside the .Fn dialog_ftree -box and must be set. +box and must be set. .Va title is shown centered on the upper border of the .Fn dialog_ftree box. .Va prompt is shown inside the .Fn dialog_ftree box above the tree subwindow and can contain .Ql \e\&n to split lines. One can navigate in the tree by pressing UP/DOWN or .Sm off .So \&+ Sc \&/ So \&- Sc , .Sm on PG_UP/PG_DOWN or .Sm off .So b Sc \&/SPACE .Sm on and HOME/END or .Sm off .So g Sc \&/ So G Sc . .Sm on A leaf of the tree is selected by pressing TAB or LEFT/RIGHT the OK button and pressing ENTER. filename may contain data like .Xr find 1 output, as well as like the output of .Xr find 1 with .Fl d option. Some of the transient paths to the leaves of the tree may be absent. Such data is corrected when fed from filename. .Pp The function returns 0 and a pointer to the selected leaf (to the path to the leaf from the root of the tree) into result, if the OK button was selected. The memory allocated for the building of the tree is freed on exiting .Fn dialog_ftree . The memory for the result line should be freed later manually, if necessary. If the Cancel button was selected, the function returns 1. In case of exiting .Fn dialog_ftree on ESC, the function returns -1. .Pp The -.Fn dialog_tree +.Fn dialog_tree function returns the same results as .Fn dialog_ftree . If 0 is returned, result will contain a pointer from the array .Va names . .\" \fBdialog_tree\fR displays the tree very much like \fBdialog_ftree\fR does, .\" with some exceptions. The source data for the building of the tree is an .\" array \fBnames\fR of paths to the leaves (should be similar to \fBfind(1)\fR .\" output) of the size \fBsize\fR. However, there is no correction of data like .\" in \fBdialog_ftree\fR. Thus, to display a correct tree, the array must .\" already contain correct data. Besides, in each session every unique use of .\" \fBdialog_tree\fR is kept in memory, and later, when calling .\" \fBdialog_tree\fR with the same \fBnames\fR, \fBsize\fR, \fBFS\fR, .\" \fBheight\fR, \fBwidth\fR and \fBmenu_height\fR the position of the cursor .\" in the tree subwindow is restored. .Sh SEE ALSO .Xr dialog 1 , .Xr ncurses 3 .Sh AUTHORS The primary author would appear to be .An Savio Lam Aq lam836@cs.cuhk.hk with contributions over the years by .An Stuart Herbert Aq S.Herbert@sheffield.ac.uk , .An Marc van Kempen Aq wmbfmk@urc.tue.nl , .An Andrey Chernov Aq ache@FreeBSD.org , .An Jordan Hubbard Aq jkh@FreeBSD.org and .An Anatoly A. Orehovsky Aq tolik@mpeks.tomsk.su . .Sh HISTORY These functions appeared in .Fx 2.0 as the .Xr dialog 1 command and were soon split into a separate library and command by .An Andrey Chernov . .An Marc van Kempen implemented most of the extra controls and objects, .An Jordan Hubbard added the dialogMenuItem renovations and this man page and .An Anatoly A. Orehovsky implemented .Fn dialog_ftree and .Fn dialog_tree . .Sh BUGS Sure! Index: head/gnu/usr.bin/man/apropos/apropos.man =================================================================== --- head/gnu/usr.bin/man/apropos/apropos.man (revision 131471) +++ head/gnu/usr.bin/man/apropos/apropos.man (revision 131472) @@ -1,47 +1,47 @@ .\" Man page for apropos an whatis .\" .\" Copyright (c) 1990, 1991, John W. Eaton. .\" .\" You may distribute under the terms of the GNU General Public .\" License as specified in the README file that comes with the man 1.0 -.\" distribution. +.\" distribution. .\" .\" John W. Eaton .\" jwe@che.utexas.edu .\" Department of Chemical Engineering .\" The University of Texas at Austin .\" Austin, Texas 78712 .\" .\" $FreeBSD$ .Dd January 15, 1991 .Dt APROPOS 1 .Os .Sh NAME .Nm apropos , .Nm whatis .Nd search the whatis database .Sh SYNOPSIS .Nm apropos .Ar keyword ... .Nm whatis .Ar keyword ... .Sh DESCRIPTION .Nm searches a set of database files containing short descriptions of system commands for keywords and displays the result on the standard output. .Nm whatis -displays only complete word matches. +displays only complete word matches. .Pp .Ar keyword really is an extended regular expression, please read .Xr grep 1 manual page for more information about its format. .Sh DIAGNOSTICS -The +The .Nm utility exits 0 on success, and 1 if no keyword matched. .Sh SEE ALSO .Xr grep 1 , .Xr makewhatis 1 , .Xr man 1 Index: head/gnu/usr.bin/man/man/man.man =================================================================== --- head/gnu/usr.bin/man/man/man.man (revision 131471) +++ head/gnu/usr.bin/man/man/man.man (revision 131472) @@ -1,251 +1,251 @@ .\" Man page for man .\" .\" Copyright (c) 1990, 1991, John W. Eaton. .\" .\" You may distribute under the terms of the GNU General Public .\" License as specified in the README file that comes with the man 1.0 -.\" distribution. +.\" distribution. .\" .\" John W. Eaton .\" jwe@che.utexas.edu .\" Department of Chemical Engineering .\" The University of Texas at Austin .\" Austin, Texas 78712 .\" .\" $FreeBSD$ .\" .Dd January 5, 1991 .Dt MAN 1 .Os .Sh NAME .Nm man .Nd format and display the on-line manual pages .Sh SYNOPSIS .Nm .Op Fl adfhkotw .Op Fl m Ar machine .Op Fl p Ar string .Op Fl M Ar path .Op Fl P Ar pager .Op Fl S Ar list .Op Ar section .Ar name ... .Sh DESCRIPTION .Nm Man formats and displays the on-line manual pages. This version knows about the .Ev MANPATH and .Ev PAGER environment variables, so you can have your own set(s) of personal man pages and choose whatever program you like to display the formatted pages. If section is specified, .Nm only looks in that section of the manual. You may also specify the order to search the sections for entries and which preprocessors to run on the source files via command line options or environment variables. If enabled by the system administrator, formatted man pages will also be compressed with the `%compress%' command to save space. .Pp The options are as follows: .Bl -tag -width Fl .It Fl M Ar path Specify an alternate manpath. By default, .Nm uses .Xr manpath 1 (which is built into the .Nm binary) to determine the path to search. This option overrides the .Ev MANPATH environment variable. .It Fl P Ar pager Specify which pager to use. By default, .Nm uses .Nm %pager% . This option overrides the .Ev PAGER environment variable. .It Fl S Ar list List is a colon separated list of manual sections to search. This option overrides the .Ev MANSECT environment variable. .It Fl a By default, .Nm will exit after displaying the first manual page it finds. Using this option forces .Nm to display all the manual pages that match .Ar name , not just the first. .It Fl d Don't actually display the man pages, but do print gobs of debugging information. .It Fl f Equivalent to .Nm whatis . .It Fl h Print a help message and exit. .It Fl k Equivalent to .Nm apropos . .It Fl m Ar machine As some manual pages are intended only for specific architectures, .Nm searches any subdirectories, with the same name as the current architecture, in every directory which it searches. Machine specific areas are checked before general areas. The current machine type may be overridden using this option or by setting the environment variable .Ev MACHINE to the name of a specific architecture. This option overrides the .Ev MACHINE environment variable. .It Fl o Look for original, non-localized manpages only. .Pp By default, .Nm searches for a localized manpage in a set of locale subdirectories of each .Xr manpath 1 component. .Pp Locale name is taken from the first of three environment variables with a nonempty value: .Ev LC_ALL , LC_CTYPE , or .Ev LANG , in the specified order. .Pp If the value could not be determined, or is not a valid locale name, then only non-localized manpage will be looked up. .Pp Otherwise, .Nm will search in the following subdirectories, in the order of precedence: .Pp .Bl -item -offset indent -compact .Sm off .It .Pa _ . .It .Pa . .It .Pa en . .Sm on .El .Pp For example, for .Dq de_DE.ISO8859-1 locale, .Nm will search in the following subdirectories of the .Pa /usr/share/man manpath component: .Pp .Bl -item -offset indent -compact .It .Pa /usr/share/man/de_DE.ISO8859-1 .It .Pa /usr/share/man/de.ISO8859-1 .It .Pa /usr/share/man/en.ISO8859-1 .El .Pp Finally, if the search of localized manpage fails, it will be looked up in the default .Pa /usr/share/man directory. .It Fl p Ar string Specify the sequence of preprocessors to run before nroff or troff. Not all installations will have a full set of preprocessors. -Some of the preprocessors and the letters used to designate them are: +Some of the preprocessors and the letters used to designate them are: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). This option overrides the .Ev MANROFFSEQ environment variable. .It Fl t Use .Nm %troff% to format the manual page, passing the output to stdout. The output from .Nm %troff% may need to be passed through some filter or another before being printed. .It Fl w Don't actually display the man pages, but do print the location(s) of the files that would be formatted or displayed. .El .Sh ENVIRONMENT .Bl -tag -width MANROFFSEQ .It Ev LC_ALL , LC_CTYPE , LANG These variables specify the preferred language for manual pages. (See the .Fl o option above.) .It Ev MACHINE If .Ev MACHINE is set, its value is used to override the current machine type when searching machine specific subdirectories. .It Ev MANPATH If .Ev MANPATH is set, its value is used as the path to search for manual pages. .It Ev MANROFFSEQ If .Ev MANROFFSEQ is set, its value is used to determine the set of preprocessors run before running nroff or troff. By default, pages are passed through the table preprocessor before nroff. .It Ev MANSECT If .Ev MANSECT is set, its value is used to determine which manual sections to search. .It Ev PAGER If .Ev PAGER is set, its value is used as the name of the program to use to display the man page. By default, .Nm %pager% is used. .El .Sh EXAMPLES .Pp Normally, to look at the relevant manpage information for getopt, one would use: .Pp .Dl man getopt .Pp However, when referring to a specific section of the manual, such as .Xr getopt 3 , one would use: .Pp .Dl man 3 getopt .Sh SEE ALSO .Xr apropos 1 , .Xr groff 1 , .Xr manpath 1 , .Xr more 1 , .Xr whatis 1 , .Xr man 7 , .Xr mdoc 7 .Sh BUGS The .Fl t option only works if the .Xr troff 1 Ns -like program is installed. Index: head/gnu/usr.bin/tar/tar.1 =================================================================== --- head/gnu/usr.bin/tar/tar.1 (revision 131471) +++ head/gnu/usr.bin/tar/tar.1 (revision 131472) @@ -1,573 +1,573 @@ .\" Copyright (c) 1991, 1992, 1993 Free Software Foundation -*- nroff -*- .\" See /usr/src/gnu/COPYING for conditions of redistribution .\" .\" Written by John F. Woods .\" Updated by Robert Eckardt .\" .\" $FreeBSD$ .\" .Dd December 23, 2000 .Os .Dt TAR 1 .Sh NAME .Nm tar .Nd "tape archiver; manipulate ""tar"" archive files" .Sh SYNOPSIS .Nm .Op Oo Fl Oc Ns Ar bundled-options Ar Args .Op Ar gnu-style-flags .Op Ar filenames | Fl C Ar directory-name .Ar ... .Sh DESCRIPTION .Nm Tar -is short for +is short for .Dq tape archiver , so named for historical reasons; the .Nm program creates, adds files to, or extracts files from an archive file in .Nm format, called a .Ar tarfile . A .Ar tarfile is often a magnetic tape, but can be a floppy diskette or any regular disk file. .Pp The first argument word of the .Nm command line is usually a command word of bundled function and modifier letters, optionally preceded by a dash; it must contain exactly one function letter from the set .Cm A , .Cm c , .Cm d , .Cm r , .Cm t , .Cm u , .Cm x , for .Em append , .Em create , .Em difference , .Em replace , .Em table of contents , .Em update , and .Em extract (further described below). The command word can also contain other function modifiers described below, some of which will take arguments from the command line in the order they are specified in the command word (review the .Sx EXAMPLES section). Functions and function modifiers can also be specified with the GNU argument convention (preceded by two dashes, one function or modifier per word. Command-line arguments that specify files to add to, extract from, or list from an archive may be given as shell pattern matching strings. .Sh FUNCTIONS Exactly one of the following functions must be specified. .Pp .Bl -tag -width "--concatenate" -compact .It Fl A .It Fl -catenate .It Fl "-concatenate" Append the contents of named file, which must itself be a .Nm archive, to the end of the archive (erasing the old end-of-archive block). This has the effect of adding the files contained in the named file to the first archive, rather than adding the second archive as an element of the first. .Em Note : This option requires a rewritable .Ar tarfile , and therefore does not work on quarter-inch cartridge tapes. .It Fl c .It Fl -create Create a new archive (or truncates an old one) and writes the named files to it. .It Fl d .It Fl -diff .It Fl -compare Find differences between files in the archive and corresponding files in the file system. .It Fl -delete Delete named files from the archive. (Does not work on quarter-inch tapes). .It Fl r .It Fl -append Append files to the end of an archive. (Does not work on quarter-inch tapes). .It Fl t .It Fl -list List the contents of an archive; if .Ar filename arguments are given, only those files are listed, otherwise the entire table of contents is listed. .It Fl u .It Fl -update Append the named files if the on-disk version has a modification date more recent than their copy in the archive (if any). Does not work on quarter-inch tapes. .It Fl x .It Fl -extract .It Fl -get Extract files from an archive. The owner, modification time, and file permissions are restored, if possible. If no .Ar file arguments are given, extract all the files in the archive. If a .Ar filename argument matches the name of a directory on the tape, that directory and its contents are extracted (as well as all directories under that directory). If the archive contains multiple entries corresponding to the same file (see the .Fl -append command above), the last one extracted will overwrite all earlier versions. .El .Sh OPTIONS The other options to .Nm may be combined arbitrarily; single-letter options may be bundled in with the command word. Verbose options which take arguments will be followed by the argument; single-letter options will consume successive command line arguments (see the .Sx EXAMPLES below). .Pp .Bl -tag -width "--preserve-permissions" -compact .It Fl -help Prints a message listing and briefly describing all the command options to .Nm . .It Fl -atime-preserve Restore the access times on files which are written to tape (note that this will change the inode-change time!). .It Fl b .It Fl -block-size Ar number Sets the block size for reading or writing to .Ar number * 512-byte blocks. .It Fl B .It Fl -read-full-blocks Re-assemble short reads into full blocks (for reading .Bx 4.2 pipes). .It Fl C Ar directory .It Fl -directory Ar directory Change to .Ar directory before processing the remaining arguments. .It Fl -checkpoint Print number of buffer reads/writes while reading/writing the archive. .It Fl f Xo .Oo Ar hostname : Oc Ns Ar file .Xc .It Fl -file Xo .Oo Ar hostname : Oc Ns Ar file .Xc Read or write the specified .Ar file (default is .Pa /dev/sa0 ) . If a .Ar hostname is specified, .Nm will use .Xr rmt 8 to read or write the specified .Ar file on a remote machine. .Dq Ar - may be used as a filename, for reading or writing to/from stdin/stdout. .It Fl -force-local Archive file is local even if it has a colon. .It Fl F Ar file .It Fl -info-script Ar file .It Fl -new-volume-script Ar file Run a script at the end of each archive volume (implies .Fl M ) . .It Fl -fast-read Stop after all non-wildcard extraction targets have been found in the archive. .It Fl G .It Fl -incremental Create/list/extract old GNU-format incremental backup. .It Fl g Ar file .It Fl -listed-incremental Ar file Create/list/extract new GNU-format incremental backup. .It Fl h .It Fl -dereference Don't write symlinks as symlinks; write the data of the files they name. .It Fl i .It Fl -ignore-zeros Ignore blocks of zeroes in archive (usually means End-Of-File). .It Fl -ignore-failed-read Don't exit with non-zero status on unreadable files. .It Fl j .It Fl y .It Fl -bzip .It Fl -bzip2 .It Fl -bunzip2 Filter the archive through .Xr bzip2 1 . .It Fl k .It Fl -keep-old-files Keep files which already exist on disk; don't overwrite them from the archive. .It Fl K Ar file .It Fl -starting-file Ar file Begin at .Ar file in the archive. .It Fl l .It Fl -one-file-system Stay in local file system when creating an archive (do not cross mount points). .It Fl L Ar number .It Fl -tape-length Ar number -Change tapes after writing +Change tapes after writing .Ar number * 1024 bytes. .It Fl m .It Fl -modification-time Don't extract file modified time. .It Fl M .It Fl -multi-volume Create/list/extract multi-volume archive. .It Fl n .It Fl -norecurse Don't recurse into subdirectories when creating. .It Fl -volno-file Ar file File name with volume number to start with. .It Fl N Ar date .It Fl -after-date Ar date .It Fl -newer Ar date Only store files with creation time newer than .Ar date . .It Fl -newer-mtime Ar date Only store files with modification time newer than .Ar date . .It Fl o .It Fl -old-archive .It Fl -portability Write a V7 format archive, rather than POSIX format. .It Fl O .It Fl -to-stdout Extract files to standard output. .It Fl p .It Fl -same-permissions .It Fl -preserve-permissions Extract all protection information. .It Fl -preserve Has the effect of .Fl p s . .It Fl P .It Fl -absolute-paths Don't strip leading .Ql / from file names. .It Fl R .It Fl -record-number Show record number within archive with each message. .It Fl -remove-files Remove files after adding them to the archive. .It Fl s .It Fl -same-order .It Fl -preserve-order List of names to extract is sorted to match archive. .It Fl -show-omitted-dirs Show directories which were omitted while processing the archive. .It Fl S .It Fl -sparse Handle .Dq sparse files efficiently. .It Fl T Ar file .It Fl I Ar file .It Fl -files-from Ar file Get names of files to extract or create from .Ar file , one per line. .It Fl -null Modifies behavior of .Fl T to expect null-terminated names; disables .Fl C . .It Fl -totals Prints total bytes written with .Fl -create . .It Fl U .It Fl -unlink .It Fl -unlink-first Unlink files before creating them. .It Fl v .It Fl -verbose Lists files written to archive with .Fl -create or extracted with .Fl -extract ; lists file protection information along with file names with .Fl -list . .It Fl V Ar volume-name .It Fl -label Ar volume-name Create archive with the given .Ar volume-name . .It Fl -version Print .Nm program version number. .It Fl w .It Fl -interactive .It Fl -confirmation Ask for confirmation for every action. .It Fl W .It Fl -verify Attempt to verify the archive after writing it. .It Fl -exclude Ar pattern Exclude files matching the .Ar pattern (don't extract them, don't add them, don't list them). .It Fl X Ar file .It Fl -exclude-from Ar file Exclude files listed in .Ar file . .It Fl Z .It Fl -compress .It Fl -uncompress Filter the archive through .Xr compress 1 . .It Fl z .It Fl -gzip .It Fl -gunzip Filter the archive through .Xr gzip 1 . .It Fl -use-compress-program Ar program Filter the archive through .Ar program (which must accept .Fl d to mean .Dq decompress ) . .It Fl -block-compress Block the output of compression program for tapes or floppies (otherwise writes will be of odd length, which device drivers may reject). .It Fl Xo .Op Cm 0 Ns - Ns Cm 7 Ns .Op Cm lmh .Xc Specify tape drive and density. .El .Sh ENVIRONMENT The environment variable .Ev TAR_OPTIONS can hold a set of default options for .Nm . These options are interpreted first and can be overwritten by explicit command line parameters. .Sh EXAMPLES To create an archive on tape drive .Pa /dev/sa0 with a block size of 20 blocks, containing files named .Pa bert and .Pa ernie , you can enter .Dl "tar cfb /dev/sa0 20 bert ernie" or .Dl "tar --create --file /dev/sa0 --block-size 20 bert ernie" Note that the .Fl f and .Fl b flags both require arguments, which they take from the command line in the order they were listed in the command word. .Pp Because .Pa /dev/sa0 is the default device, and 20 is the default block size, the above example could have simply been .Dl "tar c bert ernie" .Pp To extract all the C sources and headers from an archive named .Pa backup.tar , type .Dl "tar xf backup.tar '*.[ch]'" Note that the pattern must be quoted to prevent the shell from attempting to expand it according the files in the current working directory (the shell does not have access to the list of files in the archive, of course). .Pp To move file hierarchies, use a command line like this: .Bd -literal tar -cf - -C srcdir . | tar xpf - -C destdir .Ed .Pp To create a compressed archive on diskette, using .Xr gzip 1 , use a command-line like .Dl "tar --block-compress -z -c -v -f /dev/fd1a -b 36 tar/" .Pp Note that you cannot mix bundled flags and .Fl -style flags; you can use single-letter flags in the manner above, rather than having to type .Dl "tar --block-compress --gzip --verbose --file /dev/fd1a --block-size 20 tar/" .Pp The above-created diskette can be listed with .Dl "tar tvfbz /dev/fd1a 36" .Pp To join two .Nm archives into a single archive, use .Dl "tar Af archive1.tar archive2.tar" which will add the files contained in .Pa archive2.tar onto the end of .Pa archive1.tar (note that this can't be done by simply typing .Dl "cat archive2.tar >> archive1.tar" because of the end-of-file block at the end of a .Nm archive). .Pp To archive all files from the directory .Pa srcdir , which were modified after Feb. 9th 1997, 13:00 h, use .Dl "tar -c -f backup.tar --newer-mtime 'Feb 9 13:15 1997' srcdir/" .Pp Other possible time specifications are .Sq "02/09/97 13:15" , .Sq "1997-02-09 13:15" , .Sq "13:15 9 Feb 1997" , -.Sq "9 Feb 1997 13:15" , +.Sq "9 Feb 1997 13:15" , .Sq "Feb. 9, 1997 1:15pm" , .Sq "09-Feb" , .Sq "3 weeks ago" or .Sq "May first Sunday" . To specify the correct time zone use either e.g.\& .Sq "13:15 CEST" or .Sq "13:15+200" . .Sh ENVIRONMENT The .Nm program examines the following environment variables. .Bl -tag -width "POSIXLY_CORRECT" .It Ev POSIXLY_CORRECT Normally, .Nm will process flag arguments that appear in the file list. If set in the environment, this causes .Nm to consider the first non-flag argument to terminate flag processing, as per the POSIX specification. .It Ev SHELL In interactive mode, a permissible response to the prompt is to request to spawn a subshell, which will be .Pa /bin/sh unless the .Ev SHELL variable is set. .It Ev TAPE Changes .Nm Ns 's default tape drive (which is still overridden by the .Fl f flag). .It TAR_RSH The TAR_RSH environment variable allows you to override the default shell used as the transport for .Nm . .El .Sh FILES .Bl -tag -width "/dev/sa0" .It Pa /dev/sa0 The default tape drive. .El .Sh COMPATIBILITY The .Fl y is a .Fx localism. The GNU .Nm maintainer has now chosen .Fl j as the offical .Xr bzip2 1 compression option in GNU .Nm 1.13.18 and later. The .Fl I option is for compatibility with Solaris's .Nm . .Sh SEE ALSO .Xr bzip2 1 , .Xr compress 1 , .Xr gzip 1 , .Xr pax 1 , .Xr rmt 8 .Sh HISTORY The .Nm format has a rich history, dating back to Sixth Edition .Ux . The current implementation of .Nm is the GNU implementation, which originated as the public-domain .Nm written by .An John Gilmore . .Sh AUTHORS .An -nosplit A cast of thousands, including [as listed in the .Pa ChangeLog file in the source] .An John Gilmore (author of original public domain version), .An Jay Fenlason (first GNU author), .An Joy Kendall , .An Jim Kingdon , .An David J. MacKenzie , .An Michael I Bushnell , .An Noah Friedman , and innumerable others who have contributed fixes and additions. .Pp Man page obtained by the .Fx group from the .Nx 1.0 release. .Sh BUGS The .Fl C feature does not work like historical .Nm programs, and is probably untrustworthy. .Pp -The -.Fl A +The +.Fl A command should work to join an arbitrary number of .Nm archives together, but it does not; attempting to do so leaves the end-of-archive blocks in place for the second and subsequent archives. .Pp The .Nm file format is a semi fixed width field format, and the field for device numbers were designed for 16 bit (8 major, 8 minor) and cannot absorb our 32 bit (8 major, 16+8 minor) numbers. Index: head/lib/libc/gen/time.3 =================================================================== --- head/lib/libc/gen/time.3 (revision 131471) +++ head/lib/libc/gen/time.3 (revision 131472) @@ -1,104 +1,104 @@ .\" 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 .\" the American National Standards Committee X3, on Information .\" Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. 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. .\" .\" @(#)time.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 18, 2003 .Dt TIME 3 .Os .Sh NAME .Nm time .Nd get time of day .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In time.h .Ft time_t .Fn time "time_t *tloc" .Sh DESCRIPTION The .Fn time function returns the value of time in seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If an error occurs, .Fn time returns the value .Po Vt time_t Pc Ns \-1 . .Pp -The return value is also stored in +The return value is also stored in .No \&* Ns Va tloc , provided that .Va tloc is non-null. .Sh ERRORS The .Fn time function may fail for any of the reasons described in .Xr gettimeofday 2 . .Sh SEE ALSO .Xr gettimeofday 2 , .Xr ctime 3 .Sh STANDARDS The .Nm function conforms to .St -p1003.1-2001 . .Sh BUGS Neither .St -isoC-99 nor .St -p1003.1-2001 requires .Fn time to set .Va errno on failure; thus, it is impossible for an application to distinguish the valid time value \-1 (representing the last UTC second of 1969) from the error return value. .Pp Systems conforming to earlier versions of the C and .Tn POSIX standards (including older versions of .Fx ) did not set .No \&* Ns Va tloc in the error case. .Sh HISTORY A .Fn time function appeared in .At v6 . Index: head/lib/libc/i386/sys/i386_get_ldt.2 =================================================================== --- head/lib/libc/i386/sys/i386_get_ldt.2 (revision 131471) +++ head/lib/libc/i386/sys/i386_get_ldt.2 (revision 131472) @@ -1,143 +1,143 @@ .\" Copyright (c) 1980, 1991 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: @(#)fork.2 6.5 (Berkeley) 3/10/91 .\" $FreeBSD$ .\" .Dd September 20, 1993 .Dt I386_GET_LDT 2 .Os .Sh NAME .Nm i386_get_ldt , .Nm i386_set_ldt .Nd manage i386 per-process Local Descriptor Table entries .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In machine/segments.h .In machine/sysarch.h .Ft int .Fn i386_get_ldt "int start_sel" "union descriptor *descs" "int num_sels" .Ft int .Fn i386_set_ldt "int start_sel" "union descriptor *descs" "int num_sels" .Sh DESCRIPTION The .Fn i386_get_ldt system call will return the list of i386 descriptors that the process has in its LDT. The .Fn i386_set_ldt system call will set a list of i386 descriptors for the current process in its LDT. Both routines accept a starting selector number .Fa start_sel , an array of memory that will contain the descriptors to be set or returned .Fa descs , and the number of entries to set or return .Fa num_sels . .Pp The argument .Fa descs can be either segment_descriptor or gate_descriptor and are defined in .In i386/segments.h . These structures are defined by the architecture as disjoint bit-fields, so care must be taken in constructing them. .Pp -If +If .Fa start_sel -is +is .Em LDT_AUTO_ALLOC , .Fa num_sels -is 1 and the descriptor pointed to by +is 1 and the descriptor pointed to by .Fa descs is legal, then .Fn i386_set_ldt -will allocate a descriptor and return its +will allocate a descriptor and return its selector number. .Pp -If +If .Fa num_descs is 1, .Fa start_sels -is valid, and +is valid, and .Fa descs -is NULL, then +is NULL, then .Fn i386_set_ldt will free that descriptor (making it available to be reallocated again later). .Pp -If -.Fa num_descs -is 0, +If +.Fa num_descs +is 0, .Fa start_sels is 0 and .Fa descs is NULL then, as a special case, .Fn i386_set_ldt will free all descriptors. .Sh RETURN VALUES Upon successful completion, .Fn i386_get_ldt returns the number of descriptors currently in the LDT. The .Fn i386_set_ldt system call returns the first selector set. In the case when a descriptor is allocated by the kernel, its number will be returned. Otherwise, a value of -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS The .Fn i386_get_ldt and .Fn i386_set_ldt system calls will fail if: .Bl -tag -width Er .It Bq Er EINVAL An inappropriate value was used for .Fa start_sel or .Fa num_sels . .It Bq Er EACCES The caller attempted to use a descriptor that would circumvent protection or cause a failure. .El .Sh SEE ALSO i386 Microprocessor Programmer's Reference Manual, Intel .Sh WARNING You can really hose your process using this. Index: head/lib/libc/locale/gb2312.5 =================================================================== --- head/lib/libc/locale/gb2312.5 (revision 131471) +++ head/lib/libc/locale/gb2312.5 (revision 131472) @@ -1,57 +1,57 @@ .\" Copyright (c) 2003 Tim J. Robbins .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .Dd November 7, 2003 .Dt GB2312 5 .Os .Sh NAME .Nm gb2312 .Nd "GB2312 encoding method for Chinese text" .Sh SYNOPSIS .Nm ENCODING .Qq GB2312 .Sh DESCRIPTION The .Nm GB2312 encoding implements GB\ 2312-1980, a PRC national standard -for the encoding of simplified Chinese characters. +for the encoding of simplified Chinese characters. .Pp Multibyte characters in the GB2312 encoding can be one byte or two bytes long. .No GB\ 11383-1981 ( Ns .Tn ASCII ) characters are represented by single bytes in the range 0x00 to 0x7F. Simplified Chinese characters are represented by two bytes, both in the range 0xA1-0xFE. .Sh SEE ALSO .Xr euc 5 , .Xr gb18030 5 , .Xr gbk 5 .Sh STANDARDS The .Nm GB2312 encoding is believed to be compatible with GB\ 2312-1980. This standard has been superceded by GB\ 18030-2000, but is still in wide use. Index: head/lib/libc/locale/mblen.3 =================================================================== --- head/lib/libc/locale/mblen.3 (revision 131471) +++ head/lib/libc/locale/mblen.3 (revision 131472) @@ -1,110 +1,110 @@ .\" Copyright (c) 2002-2004 Tim J. Robbins. All rights reserved. .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Donn Seeley of BSDI. .\" .\" 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 @(#)multibyte.3 8.1 (Berkeley) 6/4/93 .\" From FreeBSD: src/lib/libc/locale/multibyte.3,v 1.22 2003/11/08 03:23:11 tjr Exp .\" $FreeBSD$ .\" .Dd April 11, 2004 .Dt MBLEN 3 .Os .Sh NAME .Nm mblen .Nd get number of bytes in a character .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .Ft int .Fn mblen "const char *mbchar" "size_t nbytes" .Sh DESCRIPTION The .Fn mblen function computes the length in bytes of a multibyte character .Fa mbchar according to the current conversion state. Up to .Fa nbytes bytes are examined. .Pp A call with a null .Fa mbchar pointer returns nonzero if the current locale requires shift states, zero otherwise; if shift states are required, the shift state is reset to the initial state. .Sh RETURN VALUES If .Fa mbchar is .Dv NULL , the .Fn mblen function returns nonzero if shift states are supported, zero otherwise. .Pp Otherwise, if .Fa mbchar is not a null pointer, .Fn mblen either returns 0 if .Fa mbchar represents the null wide character, or returns the number of bytes processed in .Fa mbchar , or returns \-1 if no multibyte character could be recognized or converted. In this case, .Fn mblen Ns No 's internal conversion state is undefined. .Sh ERRORS -The +The .Fn mblen function will fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid multibyte sequence was detected. .It Bq Er EINVAL The internal conversion state is not valid. .El .Sh SEE ALSO .Xr mbrlen 3 , .Xr mbtowc 3 , .Xr multibyte 3 .Sh STANDARDS The .Fn mblen function conforms to .St -isoC-99 . Index: head/lib/libc/sys/connect.2 =================================================================== --- head/lib/libc/sys/connect.2 (revision 131471) +++ head/lib/libc/sys/connect.2 (revision 131472) @@ -1,162 +1,162 @@ .\" 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. .\" .\" @(#)connect.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd June 4, 1993 .Dt CONNECT 2 .Os .Sh NAME .Nm connect .Nd initiate a connection on a socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .Ft int .Fn connect "int s" "const struct sockaddr *name" "socklen_t namelen" .Sh DESCRIPTION The .Fa s argument is a socket. If it is of type .Dv SOCK_DGRAM , this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type .Dv SOCK_STREAM , this call attempts to make a connection to another socket. The other socket is specified by .Fa name , which is an address in the communications space of the socket. Each communications space interprets the .Fa name argument in its own way. Generally, stream sockets may successfully .Fn connect only once; datagram sockets may use .Fn connect multiple times to change their association. Datagram sockets may dissolve the association by connecting to an invalid address, such as a null address. .Sh RETURN VALUES .Rv -std connect .Sh ERRORS The .Fn connect system call fails if: .Bl -tag -width Er .It Bq Er EBADF The .Fa s argument is not a valid descriptor. .It Bq Er ENOTSOCK The .Fa s argument is a descriptor for a file, not a socket. .It Bq Er EADDRNOTAVAIL The specified address is not available on this machine. .It Bq Er EAFNOSUPPORT Addresses in the specified address family cannot be used with this socket. .It Bq Er EISCONN The socket is already connected. .It Bq Er ETIMEDOUT Connection establishment timed out without establishing a connection. .It Bq Er ECONNREFUSED The attempt to connect was forcefully rejected. .It Bq Er ENETUNREACH The network is not reachable from this host. .It Bq Er EHOSTUNREACH The remote host is not reachable from this host. .It Bq Er EADDRINUSE The address is already in use. .It Bq Er EFAULT The .Fa name argument specifies an area outside the process address space. .It Bq Er EINPROGRESS The socket is non-blocking and the connection cannot be completed immediately. It is possible to .Xr select 2 for completion by selecting the socket for writing. .It Bq Er EINTR The connection attempt was interrupted by the delivery of a signal. The connection will be established in the background, as in the case of .Er EINPROGRESS . .It Bq Er EALREADY A previous connection attempt has not yet been completed. .It Bq Er EACCES An attempt is made to connect to a broadcast address (obtained through the -.Dv INADDR_BROADCAST +.Dv INADDR_BROADCAST constant or the .Dv INADDR_NONE return value) through a socket that does not provide broadcast functionality. .El .Pp The following errors are specific to connecting names in the UNIX domain. These errors may not apply in future versions of the UNIX IPC domain. .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 ENOENT The named socket does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er EACCES Write access to the named socket is denied. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .El .Sh SEE ALSO .Xr accept 2 , .Xr getpeername 2 , .Xr getsockname 2 , .Xr select 2 , .Xr socket 2 .Sh HISTORY The .Fn connect system call appeared in .Bx 4.2 . Index: head/lib/libc/sys/ntp_gettime.2 =================================================================== --- head/lib/libc/sys/ntp_gettime.2 (revision 131471) +++ head/lib/libc/sys/ntp_gettime.2 (revision 131472) @@ -1,116 +1,116 @@ .\" .\" Copyright (c) 2003 Tom Rhodes .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 21, 2003 .Dt NTP_GETTIME 2 .Os .Sh NAME .Nm ntp_gettime .Nd NTP user application interface .Sh SYNOPSIS .In sys/timex.h .Ft int .Fn ntp_gettime "struct ntptimeval *ntv" .Sh DESCRIPTION The time returned by .Fn ntp_gettime is in a .Vt timespec structure, but may be in either microsecond (seconds and microseconds) or nanosecond (seconds and nanoseconds) format. The particular format in use is determined by the .Dv STA_NANO bit of the status word returned by the .Fn ntp_adjtime system call. .Fn ntp_gettime has as argument a pointer to the .Vt ntptimeval structure with the following members: .Bd -literal struct ntptimeval { struct timespec time; /* current time (ns) (ro) */ long maxerror; /* maximum error (us) (ro) */ long esterror; /* estimated error (us) (ro) */ long tai; /* TAI-UTC offset */ int time_state; /* time status */ }; .Ed .Pp These are understood as: .Bl -tag -width ".Va time_state" .It Va time Current time (read-only). .It Va maxerror Maximum error in microseconds (read-only). .It Va esterror Estimated error in microseconds (read-only). .It Va tai Offset in seconds between the TAI and UTC time scales. This offset is published twice a year and is an integral number of seconds between TAI (which does not have leap seconds) and UTC (which does). -.Xr ntpd 8 +.Xr ntpd 8 or some other agent maintains this value. A value of 0 means unknown. As of the date of the manual page, the offset is 32 seconds. .It Va time_state Current time status. .El .Sh RETURN VALUES .Rv -std ntp_gettime .Pp Possible states of the clock are: .Pp .Bl -tag -compact -width ".Dv TIME_ERROR" .It Dv TIME_OK Everything okay, no leap second warning. .It Dv TIME_INS Positive leap second warning. At the end of the day, an additional second will be inserted after 23:59:59. .It Dv TIME_DEL Negative leap second warning. At the end of the day, 23:59:59 is skipped. .It Dv TIME_OOP Leap second in progress. .It Dv TIME_WAIT Leap second has occurred. .It Dv TIME_ERROR Clock not synchronized. .El .Sh SEE ALSO .Xr ntp_adjtime 2 , .Xr ntpd 8 .Bl -tag -width indent .It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html .It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm .It Pa ftp://time.nist.gov/pub/leap-seconds.list .El .Sh AUTHORS This manual page was written by .An Tom Rhodes Aq trhodes@FreeBSD.org . Index: head/lib/libkiconv/kiconv.3 =================================================================== --- head/lib/libkiconv/kiconv.3 (revision 131471) +++ head/lib/libkiconv/kiconv.3 (revision 131472) @@ -1,123 +1,123 @@ .\" .\" Copyright (c) 2003 Ryuichiro Imura .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 17, 2003 .Dt KICONV 3 .Os .Sh NAME .Nm kiconv_add_xlat16_cspair , .Nm kiconv_add_xlat16_cspairs , .Nm kiconv_add_xlat16_table .Nd Kernel side iconv library .Sh LIBRARY .Lb libkiconv .Sh SYNOPSIS .In sys/iconv.h .Ft int .Fo kiconv_add_xlat16_cspair .Fa "const char *tocode" .Fa "const char *fromcode" .Fa "int flag" .Fc .Ft int .Fo kiconv_add_xlat16_cspairs .Fa "const char *foreigncode" .Fa "const char *localcode" .Fc .Ft int .Fo kiconv_add_xlat16_table .Fa "const char *tocode" .Fa "const char *fromcode" .Fa "const void *data" .Fa "int datalen" .Fc .Sh DESCRIPTION The .Xr kiconv 3 library provides multi-byte character conversion tables for kernel side iconv service. .Pp .Fn kiconv_add_xlat16_cspair defines a conversion table using .Xr iconv 3 between .Ar fromcode charset and .Ar tocode charset. You can specify .Ar flag to determine if .Xr tolower 3 / .Xr toupper 3 conversion is included in the table. The .Ar flag has following values. .Pp .Bl -tag -width "KICONV_FROM_LOWER" -compact .It Fa KICONV_LOWER .It Fa KICONV_FROM_LOWER It generates a tolower table in addition to a character conversion table. The difference between two is tolower .Ar tocode or tolower .Ar fromcode . .It Fa KICONV_UPPER .It Fa KICONV_FROM_UPPER It generates a toupper table in addition to a character conversion table. The difference between two is toupper .Ar tocode or toupper .Ar fromcode . .El .Pp A tolower/toupper conversion is limited to single-byte characters. -.Pp +.Pp .Fn kiconv_add_xlat16_cspairs defines two conversion tables which are from .Ar localcode to .Ar foreigncode and from .Ar foreigncode to .Ar localcode . This conversion tables also contain both of tolower and toupper tables. .Pp .Fn kiconv_add_xlat16_table defines a conversion table directly pointed by .Ar data whose length is .Ar datalen , not using .Xr iconv 3 . .Sh SEE ALSO .Xr iconv 3 , .Xr tolower 3 , .Xr toupper 3 , .Xr iconv 9 Index: head/lib/libsdp/sdp.3 =================================================================== --- head/lib/libsdp/sdp.3 (revision 131471) +++ head/lib/libsdp/sdp.3 (revision 131472) @@ -1,397 +1,397 @@ .\" Copyright (c) 2003 Maksim Yevmenkin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Id: sdp.3,v 1.1 2003/09/07 20:34:19 max Exp $ .\" $FreeBSD$ .\" .Dd September 7, 2003 .Dt SDP 3 .Os .Sh NAME .Nm SDP_GET8 , .Nm SDP_GET16 , .Nm SDP_GET32 , .Nm SDP_GET64 , .Nm SDP_GET128 .Nd get SDP integer .Pp .Nm SDP_PUT8 , .Nm SDP_PUT16 , .Nm SDP_PUT32 , .Nm SDP_PUT64 , .Nm SDP_PUT128 .Nd put SPD integer .Pp .Nm sdp_open , .Nm sdp_open_local , .Nm sdp_close .Nm sdp_error .Nd control SDP session .Pp .Nm sdp_search .Nd perform SDP query .Pp .Nm sdp_attr2desc , .Nm sdp_uuid2desc .Nd convert numeric SDP attribute/UUID value into human readable description .Sh LIBRARY .Lb libsdp .Sh SYNOPSIS .In bluetooth.h .In sdp.h .Fn SDP_GET8 "b" "cp" .Fn SDP_GET16 "s" "cp" .Fn SDP_GET32 "l" "cp" .Fn SDP_GET64 "l" "cp" .Fn SDP_GET128 "l" "cp" .Fn SDP_PUT8 "b" "cp" .Fn SDP_PUT16 "s" "cp" .Fn SDP_PUT32 "l" "cp" .Fn SDP_PUT64 "l" "cp" .Fn SDP_PUT128 "l" "cp" .Ft void * .Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r" .Ft void * .Fn sdp_open_local "char const *control" .Ft int32_t .Fn sdp_close "void *xs" .Ft int32_t .Fn sdp_error "void *xs" .Ft int32_t .Fn sdp_search "void *xs" "uint32_t plen" "uint16_t const *pp" "uint32_t alen" "uint32_t const *ap" "uint32_t vlen" "sdp_attr_t *vp" .Ft char const * const .Fn sdp_attr2desc "uint16_t attr" .Ft char const * const .Fn sdp_uuid2desc "uint16_t uuid" .Ft int32_t .Fn sdp_register_service "void *xss" "uint16_t uuid" "bdaddr_p const bdaddr" "uint8_t const *data" "uint32_t datalen" "uint32_t *handle" .Ft int32_t .Fn sdp_unregister_service "void *xss" "uint32_t handle" .Ft int32_t .Fn sdp_change_service "void *xss" "uint32_t handle" "uint8_t const *data" "uint32_t datalen" .Sh DESCRIPTION The .Fn SDP_GET8 , .Fn SDP_GET16 , .Fn SDP_GET32 , .Fn SDP_GET64 and .Fn SDP_GET128 macros are used to get byte, short, long, long long and 128-bit integer from the buffer pointed by .Vt cp pointer. The pointer is automatically advanced. .Pp The .Fn SDP_PUT8 , .Fn SDP_PUT16 , .Fn SDP_PUT32 , .Fn SDP_PUT64 and .Fn SDP_PUT128 macros are used to put byte, short, long, long long and 128-bit integer into the buffer pointed by .Vt cp pointer. The pointer is automatically advanced. .Pp .Fn sdp_open and .Fn sdp_open_local functions each return a pointer to an opaque object describing SDP session. The .Vt l argument passed to .Fn sdp_open function should point to a source BD_ADDR. If source BD_ADDR is .Dv NULL then source address .Dv NG_HCI_BDADDR_ANY is used. The .Vt r argument passed to .Fn sdp_open function should point to a non .Dv NULL remote BD_ADDR. Remote BD_ADDR can not be .Dv NG_HCI_BDADDR_ANY . The .Fn sdp_open_local function takes path to the control socket and opens a connection to a local SDP server. If path to the control socket is .Dv NULL then default .Pa /var/run/sdp path will be used. .Pp The .Fn sdp_close function terminates active SDP session and deletes SDP session object. The .Vt xs parameter should point to a valid SDP session object created with .Fn sdp_open or .Fn sdp_open_local . .Pp The .Fn sdp_error function returns last error that is stored inside SDP session object. The .Vt xs parameter should point to a valid SDP session object created with .Fn sdp_open or .Fn sdp_open_local . The error value returned can be converted to a human readable message by calling .Xr strerror 3 function. .Pp The .Fn sdp_search function is used to perform SDP Service Search Attribute Request. The .Vt xs parameter should point to a valid SDP session object created with .Fn sdp_open or .Fn sdp_open_local . The .Vt pp parameter is a Service Search Pattern - an array of one or more Service Class IDs. The maximum number of Service Class IDs in the array is 12. The .Vt plen parameter is the length of the Service Search pattern. The .Vt ap parameter is a Attribute ID Range List - an array of one or more SDP Attribute ID Range. Each attribute ID Range is encoded as a 32-bit unsigned integer data element, where the high order 16 bits are interpreted as the beginning attribute ID of the range and the low order 16 bits are interpreted as the ending attribute ID of the range. The attribute IDs contained in the Attribute ID Ranges List must be listed in ascending order without duplication of any attribute ID values. Note that all attributes may be requested by specifying a range of 0x0000-0xFFFF. The .Vt alen parameter is the length of the Attribute ID Ranges List. The .Fn SDP_ATTR_RANGE "lo" "hi" macro can be used to prepare Attribute ID Range. The .Vt vp parameter should be an array of .Vt sdp_attr_t structures. Each .Vt sdp_attr_t structure describes single SDP attribute and defined as follows: .Bd -literal -offset indent struct sdp_attr { uint16_t flags; #define SDP_ATTR_OK (0 << 0) #define SDP_ATTR_INVALID (1 << 0) #define SDP_ATTR_TRUNCATED (1 << 1) uint16_t attr; /* SDP_ATTR_xxx */ uint32_t vlen; /* length of the value[] in bytes */ uint8_t *value; /* base pointer */ }; typedef struct sdp_attr sdp_attr_t; typedef struct sdp_attr * sdp_attr_p; .Ed .Pp The caller of the .Fn sdp_search function is expected to prepare the array of .Vt sdp_attr structures and for each element of the array both .Vt vlen and .Vt value must be set. The .Fn sdp_search function will fill each .Vt sdp_attr_t structure with attribute and value, i.e. it will set .Vt flags , .Vt attr and .Vt vlen fields. The actual value of the attribute will be copied into .Vt value buffer. Note: attributes are returned in the order they appear in the Service Search Attribute Response. SDP server could return several attributes for the same record. -In this case the order of the attributes will be: all attributes for the first +In this case the order of the attributes will be: all attributes for the first records, then all attributes for the secord record etc. .Pp The .Fn sdp_attr2desc and .Fn sdp_uuid2desc functions each take a numeric attribute ID/UUID value and convert it to a human readable description. .Pp The .Fn sdp_register_service is used to register service with the local SDP server. The .Vt xss parameter should point to a valid SDP session object obtained from .Fn sdp_open_local . The .Vt uuid parameter is a SDP Service Class ID for the service to be registered. The .Vt bdaddr parameter should point to a valid BD_ADDR. The service will be only advertised if request was received by the local device with .Vt bdaddr . If .Vt bdaddr is set to .Dv NG_HCI_BDADDR_ANY then the service will be advertised to any remote devices that queries for it. The .Vt data and .Vt datalen parameters specify data and size of the data for the service. Upon successful return .Fn sdp_register_service will populate .Vt handle with the SDP record handle. This parameter is optional and can be set to .Dv NULL . .Pp The .Fn sdp_unregister_service is used to unregister service with the local SDP server. The .Vt xss parameter should point to a valid SDP session object obtained from .Fn sdp_open_local . The .Vt handle parameter should contain a valid SDP record handle of the service to be unregistered. .Pp The .Fn sdp_change_service function is used to change data associated with the existing service on the local SDP server. The .Vt xss parameter should point to a valid SDP session object obtained from .Fn sdp_open_local . The .Vt handle parameter should contain a valid SDP record handle of the service to be changed. The .Vt data and .Vt datalen parameters specify data and size of the data for the service. .Sh CAVEAT When registering services with the local SDP server the application must keep the SDP session open. If SDP session is closed then the local SDP server will remove all services that were registered over the session. The application is allowed to change or unregister service if it was registered over the same session. .Sh EXAMPLES The following example shows how to get .Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST attribute for the .Dv SDP_SERVICE_CLASS_SERIAL_PORT service from the remote device. .Bd -literal -offset indent bdaddr_t remote; uint8_t buffer[1024]; void *ss = NULL; uint16_t serv = SDP_SERVICE_CLASS_SERIAL_PORT; uint32_t attr = SDP_ATTR_RANGE( SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST, SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST); sdp_attr_t proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer }; /* Obtain/set remote BDADDR here */ if ((ss = sdp_open(NG_HCI_BDADDR_ANY, remote)) == NULL) /* exit ENOMEM */ if (sdp_error(ss) != 0) /* exit spd_error(ss) */ if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0) /* exit sdp_error(ss) */ if (proto.flags != SDP_ATTR_OK) /* exit see proto.flags for details */ /* If we got here then we have attribute value in proto.value */ .Ed .Sh DIAGNOSTICS Both .Fn sdp_open and .Fn sdp_open_local will return .Dv NULL if memory allocation for the new SDP session object fails. If the new SDP object was created then caller is still expected to call .Fn sdp_error to check if there was connection error. .Pp The .Fn sdp_search , .Fn sdp_register_service , .Fn sdp_unregister_service and .Fn sdp_change_service functions return non-zero value on error. The caller is expected to call .Fn sdp_error to find out more about error. .Sh SEE ALSO .Xr bluetooth 3 , .Xr strerror 3 , .Xr sdpcontrol 8 , .Xr sdpd 8 .Sh BUGS Most likely. Please report bugs if found. .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com Index: head/lib/libufs/libufs.3 =================================================================== --- head/lib/libufs/libufs.3 (revision 131471) +++ head/lib/libufs/libufs.3 (revision 131472) @@ -1,76 +1,76 @@ .\" Author: Juli Mallett .\" Date: June 04, 2003 .\" Description: .\" Manual page for libufs. .\" .\" This file is in the public domain. .\" .\" $FreeBSD$ .\" .Dd June 4, 2003 .Dt LIBUFS 3 .Os .Sh NAME .Nm libufs .Nd operate on UFS filesystems from userland .Sh LIBRARY .Lb libufs .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In ufs/ufs/ufsmount.h .In ufs/ufs/dinode.h .In ufs/ffs/fs.h .In libufs.h .Sh DESCRIPTION The .Nm library and the functions it provides are used for implementing utilities which need to access a UFS filesystem at a low level from userland. Facilities provided are used to implement utilities such as .Xr newfs 8 and .Xr dumpfs 8 . The .Nm library is designed to be simple, and to provide functions that are traditionally useful to have. .Pp A disk is represented as the type .Dq struct uufsd as defined in .Pa libufs.h . The structure is filled out, operations are performed, and the disk is closed. .Sh ERRORS Functions provided by -.Nm +.Nm return -1 in every functional error situation. They also set the .Fa d_error field of .Dq struct uufsd to a string describing the error. .Sh SEE ALSO .Xr bread 3 , .Xr bwrite 3 , .Xr cgread 3 , .Xr cgread1 3 , .Xr sbread 3 , .Xr sbwrite 3 , .Xr ufs_disk_close 3 , .Xr ufs_disk_fillout 3 , .Xr ufs_disk_fillout_blank 3 , .Xr ufs_disk_write 3 , .Xr ffs 7 . .Sh HISTORY The .Xr libufs 3 library first appeared in .Fx 5.0 . .Sh AUTHORS .An Juli Mallett Aq jmallett@FreeBSD.org .Pp Additional design, feedback, and ideas were provided by .An Poul-Henning Kamp Aq phk@FreeBSD.org . Index: head/libexec/atrun/atrun.man =================================================================== --- head/libexec/atrun/atrun.man (revision 131471) +++ head/libexec/atrun/atrun.man (revision 131472) @@ -1,69 +1,69 @@ .\" $FreeBSD$ .Dd April 12, 1995 .Dt ATRUN 8 .Os .Sh NAME .Nm atrun .Nd run jobs queued for later execution .Sh SYNOPSIS .Nm atrun .Op Fl l Ar load_avg .Op Fl d .Sh DESCRIPTION .Nm Atrun runs jobs queued by .Xr at 1 . .Pp Root's .Xr crontab 5 file .Pa /etc/crontab has to contain the line .Bd -literal */5 * * * * root /usr/libexec/atrun .Ed .Pp so that .Nm gets invoked every five minutes. .Pp -At every invocation, +At every invocation, .Nm will start all the jobs in the lowercase queues whose start time has elapsed. -In addition, if the load average over the last minute was less than -the specified limit then a maximum of one batch job (denoted by the +In addition, if the load average over the last minute was less than +the specified limit then a maximum of one batch job (denoted by the uppercase queues) is started. .Sh OPTIONS .Bl -tag -width indent .It Fl l Ar load_avg Specify a limiting load factor, over which batch jobs should not be run, instead of the compiled in default of 1.5. .It Fl d Debug; print error messages to standard error instead of using .Xr syslog 3 . .El .Sh WARNINGS For .Nm to work, you have to start up a .Xr cron 8 daemon. .Sh FILES .Bl -tag -width /var/at/spool -compact .It Pa /var/at/spool Directory containing output spool files .It Pa /var/at/jobs Directory containing job files .El .Sh SEE ALSO .Xr at 1 , .Xr crontab 1 , .Xr syslog 3 , .Xr crontab 5 , .Xr cron 8 .Sh BUGS -The functionality of +The functionality of .Nm should be merged into .Xr cron 8 . Index: head/share/examples/ses/getencstat/getencstat.0 =================================================================== --- head/share/examples/ses/getencstat/getencstat.0 (revision 131471) +++ head/share/examples/ses/getencstat/getencstat.0 (revision 131472) @@ -1,78 +1,78 @@ .\" $FreeBSD$ .\" .\" Copyright (c) 2000 Matthew Jacob .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms, with or without +.\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. +.\" derived from this software without specific prior written permission. .\" .\" Alternatively, this software may be distributed under the terms of the .\" the GNU Public License ("GPL"). .\" .\" 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 +.\" 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. .\" .\" Matthew Jacob .\" Feral Software .\" mjacob@feral.com .Dd February 21, 2000 .Dt GETENCSTAT 8 .Os .Sh NAME .Nm getencstat .Nd get SCSI Environmental Services Device enclosure status .Sh SYNOPSIS .Nm .Op Fl v .Ar device .Op Ar device ... .Sh DESCRIPTION .Nm gets summary and detailed SCSI Environmental Services (or SAF-TE) device enclosure status. The overall status is printed out. If the overall status is considered okay, nothing else is printed out (unless the .Fl v option is used). .Pp A SCSI Environmental Services device enclosure may be either in the state of being \fBOK\fR, or in one or more of the states of \fBINFORMATIONAL\fR, \fBNON-CRITICAL\fR, \fBCRITICAL\fB or \fBUNRECOVERABLE\fR states. These overall states reflect a summary of the states of each object within such a device (such as power supplies or disk drives). .Pp With the .Fl v option, the status of all objects within the device is printed, whether \fBOK\fR or not. Along with the status of each object is the object identifier. .Pp The user may then use .Xr setencstat 8 to try and clear overall device status, or may use .Xr setobjstat 8 to set specific object status. .Sh FILES .Bl -tag -width /dev/sesN -compact .It Pa /dev/ses\fIN\fR SCSI Environmental Services Devices .El .Sh SEE ALSO .Xr ses 4 , .Xr sesd 8 , .Xr setencstat 8 , .Xr setobjstat 8 .Sh BUGS Index: head/share/examples/ses/sesd/sesd.0 =================================================================== --- head/share/examples/ses/sesd/sesd.0 (revision 131471) +++ head/share/examples/ses/sesd/sesd.0 (revision 131472) @@ -1,84 +1,84 @@ .\" $FreeBSD$ .\" .\" Copyright (c) 2000 Matthew Jacob .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms, with or without +.\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. +.\" derived from this software without specific prior written permission. .\" .\" Alternatively, this software may be distributed under the terms of the .\" the GNU Public License ("GPL"). .\" .\" 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 +.\" 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. .\" .\" Matthew Jacob .\" Feral Software .\" mjacob@feral.com .Dd February 21, 2000 .Dt SESD 8 .Os .Sh NAME .Nm sesd .Nd monitor SCSI Environmental Services Devices .Sh SYNOPSIS .Nm .Op Fl d .Op Fl t Ar poll-interval .Ar device .Op Ar device ... .Sh DESCRIPTION .Nm monitors SCSI Environmental Services (or SAF-TE) devices for changes in state and logs such changes to the system error logger (see .Xr syslogd 8 ) . At least one device must be specified. -When no other options are supplied, +When no other options are supplied, .Nm detached becomes a daemon, by default waking up every 30 seconds to poll each device for a change in state. .Pp The following options may be used: .Bl -tag -width Ds .It Fl p Ar poll-interval Change the interval of polling from the default 30 seconds to the number of seconds specified. .It Fl d Instead of detaching and becoming a daemon, stay attached to the controlling terminal and log changes there as well as via the system logger. .El .Pp The user may then use .Xr getencstat 8 to get more detailed information about the state of the over enclosure device or objects within the enclosure device. .Sh FILES .Bl -tag -width /dev/sesN -compact .It Pa /dev/ses\fIN\fR SCSI Environmental Services Devices .El .Sh SEE ALSO .Xr ses 4 , -.Xr getencstat 8 , +.Xr getencstat 8 , .Xr setencstat 8 , .Xr setobjstat 8 , .Xr syslogd 8 .Sh BUGS This is something of a toy, but it is better than nothing. Index: head/share/examples/ses/setencstat/setencstat.0 =================================================================== --- head/share/examples/ses/setencstat/setencstat.0 (revision 131471) +++ head/share/examples/ses/setencstat/setencstat.0 (revision 131472) @@ -1,72 +1,72 @@ .\" $FreeBSD$ .\" .\" Copyright (c) 2000 Matthew Jacob .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms, with or without +.\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. +.\" derived from this software without specific prior written permission. .\" .\" Alternatively, this software may be distributed under the terms of the .\" the GNU Public License ("GPL"). .\" .\" 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 +.\" 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. .\" .\" Matthew Jacob .\" Feral Software .\" mjacob@feral.com .Dd February 21, 2000 .Dt SETENCSTAT 8 .Os .Sh NAME .Nm setencstat .Nd set SCSI Environmental Services Device enclosure status .Sh SYNOPSIS .Nm .Ar device enclosure_status .Sh DESCRIPTION .Nm sets summary status for a SCSI Environmental Services (or SAF-TE) device. The enclosure status argument may take on the values: .Bl -tag -width Ds .It 0 Set the status to an \fBOK\fR state. .It 1 Set the status to an \fBUNRECOVERABLE\fR state. .It 2 Set the status to an \fBCRITICAL\fR state. .It 4 Set the status to an \fBNON-CRITICAL\fR state. .It 8 Set the status to an \fBINFORMATIONAL\fR state. .El .Pp All the non-zero options may be combined. .Pp Note that devices may simply and silently ignore the setting of these values. .Sh FILES .Bl -tag -width /dev/sesN -compact .It Pa /dev/ses\fIN\fR SCSI Environmental Services Devices .El .Sh SEE ALSO .Xr ses 4 , .Xr getencstat 8 , .Xr sesd 8 , .Xr setobjstat 8 .Sh BUGS Index: head/share/examples/ses/setobjstat/setobjstat.0 =================================================================== --- head/share/examples/ses/setobjstat/setobjstat.0 (revision 131471) +++ head/share/examples/ses/setobjstat/setobjstat.0 (revision 131472) @@ -1,67 +1,67 @@ .\" $FreeBSD$ .\" .\" Copyright (c) 2000 Matthew Jacob .\" All rights reserved. .\" -.\" Redistribution and use in source and binary forms, with or without +.\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. +.\" derived from this software without specific prior written permission. .\" .\" Alternatively, this software may be distributed under the terms of the .\" the GNU Public License ("GPL"). .\" .\" 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 +.\" 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. .\" .\" Matthew Jacob .\" Feral Software .\" mjacob@feral.com .Dd February 21, 2000 .Dt SETOBJSTAT 8 .Os .Sh NAME .Nm setobjstat .Nd set SCSI Environmental Services Device object status .Sh SYNOPSIS .Nm .Ar device objectid stat0 stat1 stat2 stat3 .Sh DESCRIPTION .Nm sets the object status for a SCSI Environmental Services (or SAF-TE) device. The .Ar objectid argument may be determined by running .Xr getencstat 8 . .Pp The status fields are partially common (first byte only, which must have a value of 0x80 contained in it), but otherwise quite device specific. A complete discussion of the possible values is impractical here. Please refer to the ANSI SCSI specification (available on the FTP site ftp.t10.org). .Pp Note that devices may simply and silently ignore the setting of these values. .Sh FILES .Bl -tag -width /dev/sesN -compact .It Pa /dev/ses\fIN\fR SCSI Environmental Services Devices .El .Sh SEE ALSO .Xr ses 4 , .Xr getencstat 8 , .Xr sesd 8 , .Xr setencstat 8 .Sh BUGS Index: head/share/man/man3/pthread_switch_add_np.3 =================================================================== --- head/share/man/man3/pthread_switch_add_np.3 (revision 131471) +++ head/share/man/man3/pthread_switch_add_np.3 (revision 131472) @@ -1,87 +1,87 @@ .\" Copyright (c) 2003 Alexey Zelkin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 13, 2003 .Dt PTHREAD_SWITCH_ADD_NP 3 .Os .Sh NAME .Nm pthread_switch_add_np , .Nm pthread_switch_delete_np .Nd thread context switches debugging primitives .Sh LIBRARY .Lb libc_r .Sh SYNOPSIS .In pthread_np.h .Ft int .Fn pthread_switch_add_np "pthread_switch_routine_t routine" .Ft int .Fn pthread_switch_delete_np "pthread_switch_routine_t routine" .Sh DESCRIPTION An application is allowed to monitor the thread context switches inside the threading library. An application can install a routine that gets called every time a thread (explicitly created by an application with the .Xr pthread_create 3 function) gets the context switched. The routine is passed the thread IDs of the threads that are being switched in and out. Installation and removal of these hooks may be done using the .Fn pthread_switch_add_np and .Fn pthread_switch_delete_np functions respectively. .Sh RETURN VALUES If successful, -these functions return 0. +these functions return 0. Otherwise, an error number is returned to indicate the error. .Sh ERRORS The .Fn pthread_switch_add_np may fail if: .Bl -tag -width Er .It Bq Er EINVAL .Dv NULL pointer was passed in the .Fa routine argument. .El .Pp The .Fn pthread_switch_delete_np may fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa routine argument is different from the argument previously passed to the .Fn pthread_switch_add_np function. .El .Sh SEE ALSO .Xr pthread_create 3 .Sh AUTHORS This manual page was written by .An Alexey Zelkin Aq phantom@FreeBSD.org . Index: head/share/man/man4/cd.4 =================================================================== --- head/share/man/man4/cd.4 (revision 131471) +++ head/share/man/man4/cd.4 (revision 131472) @@ -1,514 +1,514 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 2, 2003 .Dt CD 4 .Os .Sh NAME .Nm cd .Nd SCSI CD-ROM driver .Sh SYNOPSIS .Cd device cd .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"" .Sh DESCRIPTION The .Nm driver provides support for a .Tn SCSI .Tn CD-ROM (Compact Disc-Read Only Memory) drive. In an attempt to look like a regular disk, the .Nm driver synthesizes a partition table, with one partition covering the entire .Tn CD-ROM . It is possible to modify this partition table using .Xr disklabel 8 , but it will only last until the .Tn CD-ROM is unmounted. In general the interfaces are similar to those described by .Xr ad 4 and .Xr da 4 . .Pp As the .Tn SCSI adapter is probed during boot, the .Tn SCSI bus is scanned for devices. Any devices found which answer as CDROM (type 5) or WORM (type 4) type devices will be `attached' to the .Nm driver. Prior to .Fx 2.1 , the first device found will be attached as .Li cd0 the next, .Li cd1 , etc. Beginning in .Fx 2.1 it is possible to specify what cd unit a device should come on line as; refer to .Xr scsi 4 for details on kernel configuration. .Pp The system utility .Xr disklabel 8 may be used to read the synthesized disk label structure, which will contain correct figures for the size of the .Tn CD-ROM should that information be required. .Sh KERNEL CONFIGURATION Any number of .Tn CD-ROM devices may be attached to the system regardless of system configuration as all resources are dynamically allocated. .Sh IOCTLS The following .Xr ioctl 2 calls which apply to .Tn SCSI .Tn CD-ROM drives are defined in the header files .In sys/cdio.h and .In sys/disklabel.h . .Pp .Bl -tag -width CDIOCREADSUBCHANNEL .It Dv DIOCGDINFO .It Dv DIOCSDINFO .Pq Li "struct disklabel" Read or write the in-core copy of the disklabel for the drive. The disklabel is initialized with information read from the scsi inquiry commands, and should be the same as the information printed at boot. This structure is defined in .Xr disklabel 5 . .It Dv CDIOCCAPABILITY .Pq Li "struct ioc_capability" Retrieve information from the drive on what features it supports. The information is returned in the following structure: .Bd -literal -offset indent struct ioc_capability { u_long play_function; #define CDDOPLAYTRK 0x00000001 /* Can play tracks/index */ #define CDDOPLAYMSF 0x00000002 /* Can play msf to msf */ #define CDDOPLAYBLOCKS 0x00000004 /* Can play range of blocks */ #define CDDOPAUSE 0x00000100 /* Output can be paused */ #define CDDORESUME 0x00000200 /* Output can be resumed */ #define CDDORESET 0x00000400 /* Drive can be completely reset */ #define CDDOSTART 0x00000800 /* Audio can be started */ #define CDDOSTOP 0x00001000 /* Audio can be stopped */ #define CDDOPITCH 0x00002000 /* Audio pitch can be changed */ u_long routing_function; #define CDREADVOLUME 0x00000001 /* Volume settings can be read */ #define CDSETVOLUME 0x00000002 /* Volume settings can be set */ #define CDSETMONO 0x00000100 /* Output can be set to mono */ #define CDSETSTEREO 0x00000200 /* Output can be set to stereo (def) */ #define CDSETLEFT 0x00000400 /* Output can be set to left only */ #define CDSETRIGHT 0x00000800 /* Output can be set to right only */ #define CDSETMUTE 0x00001000 /* Output can be muted */ #define CDSETPATCH 0x00008000 /* Direct routing control allowed */ u_long special_function; #define CDDOEJECT 0x00000001 /* The tray can be opened */ #define CDDOCLOSE 0x00000002 /* The tray can be closed */ #define CDDOLOCK 0x00000004 /* The tray can be locked */ #define CDREADHEADER 0x00000100 /* Can read Table of Contents */ #define CDREADENTRIES 0x00000200 /* Can read TOC Entries */ #define CDREADSUBQ 0x00000200 /* Can read Subchannel info */ #define CDREADRW 0x00000400 /* Can read subcodes R-W */ #define CDHASDEBUG 0x00004000 /* The tray has dynamic debugging */ }; .Ed .It Dv CDIOCPLAYTRACKS .Pq Li "struct ioc_play_track" Start audio playback given a track address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_track { u_char start_track; u_char start_index; u_char end_track; u_char end_index; }; .Ed .It Dv CDIOCPLAYBLOCKS .Pq Li "struct ioc_play_blocks" Start audio playback given a block address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_blocks { int blk; int len; }; .Ed .It Dv CDIOCPLAYMSF .Pq Li "struct ioc_play_msf" Start audio playback given a `minutes-seconds-frames' address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_msf { u_char start_m; u_char start_s; u_char start_f; u_char end_m; u_char end_s; u_char end_f; }; .Ed .It Dv CDIOCREADSUBCHANNEL .Pq Li "struct ioc_read_subchannel" Read information from the subchannel at the location specified by this structure: .Bd -literal -offset indent struct ioc_read_subchannel { u_char address_format; #define CD_LBA_FORMAT 1 #define CD_MSF_FORMAT 2 u_char data_format; #define CD_SUBQ_DATA 0 #define CD_CURRENT_POSITION 1 #define CD_MEDIA_CATALOG 2 #define CD_TRACK_INFO 3 u_char track; int data_len; struct cd_sub_channel_info *data; }; .Ed .It Dv CDIOREADTOCHEADER .Pq Li "struct ioc_toc_header" Return summary information about the table of contents for the mounted .Tn CD-ROM . The information is returned into the following structure: .Bd -literal -offset indent struct ioc_toc_header { u_short len; u_char starting_track; u_char ending_track; }; .Ed .It Dv CDIOREADTOCENTRYS .Pq Li "struct ioc_read_toc_entry" Return information from the table of contents entries mentioned. .Pq Yes, this command name is misspelled. The argument structure is defined as follows: .Bd -literal -offset indent struct ioc_read_toc_entry { u_char address_format; u_char starting_track; u_short data_len; struct cd_toc_entry *data; }; .Ed The requested data is written into an area of size .Li data_len and pointed to by .Li data . .It Dv CDIOCSETPATCH .Pq Li "struct ioc_patch" Attach various audio channels to various output channels. The argument structure is defined thusly: .Bd -literal -offset indent struct ioc_patch { u_char patch[4]; /* one for each channel */ }; .Ed .It Dv CDIOCGETVOL .It Dv CDIOCSETVOL .Pq Li "struct ioc_vol" Get (set) information about the volume settings of the output channels. The argument structure is as follows: .Bd -literal -offset indent struct ioc_vol { u_char vol[4]; /* one for each channel */ }; .Ed .It Dv CDIOCSETMONO Patch all output channels to all source channels. .It Dv CDIOCSETSTEREO Patch left source channel to the left output channel and the right source channel to the right output channel. .It Dv CDIOCSETMUTE Mute output without changing the volume settings. .It Dv CDIOCSETLEFT .It Dv CDIOCSETRIGHT Attach both output channels to the left (right) source channel. .It Dv CDIOCSETDEBUG .It Dv CDIOCCLRDEBUG Turn on (off) debugging for the appropriate device. .It Dv CDIOCPAUSE .It Dv CDIOCRESUME Pause (resume) audio play, without resetting the location of the read-head. .It Dv CDIOCRESET Reset the drive. .It Dv CDIOCSTART .It Dv CDIOCSTOP Tell the drive to spin-up (-down) the .Tn CD-ROM . .It Dv CDIOCALLOW .It Dv CDIOCPREVENT Tell the drive to allow (prevent) manual ejection of the .Tn CD-ROM disc. Not all drives support this feature. .It Dv CDIOCEJECT Eject the .Tn CD-ROM . .It Dv CDIOCCLOSE Tell the drive to close its door and load the media. Not all drives support this feature. .It Dv CDIOCPITCH .Pq Li "struct ioc_pitch" For drives that support it, this command instructs the drive to play the audio at a faster or slower rate than normal. Values of .Li speed between -32767 and -1 result in slower playback; a zero value indicates normal speed; and values from 1 to 32767 give faster playback. Drives with less than 16 bits of resolution will silently ignore less-significant bits. The structure is defined thusly: .Bd -literal -offset indent struct ioc_pitch { short speed; }; .Ed .El .Sh NOTES When a .Tn CD-ROM is changed in a drive controlled by the .Nm driver, then the act of changing the media will invalidate the disklabel and information held within the kernel. To stop corruption, all accesses to the device will be discarded until there are no more open file descriptors referencing the device. During this period, all new open attempts will be rejected. When no more open file descriptors reference the device, the first next open will load a new set of parameters (including disklabel) for the drive. .Pp The audio code in the .Nm driver only support .Tn SCSI-2 standard audio commands. As many .Tn CD-ROM manufacturers have not followed the standard, there are many .Tn CD-ROM drives for which audio will not work. Some work is planned to support some of the more common `broken' .Tn CD-ROM drives; however, this is not yet under way. .Pp The .Nm driver attempts to automatically determine whether the drive it is talking to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations. Many .Tn SCSI drives only support 6 byte commands, and .Tn ATAPI drives only support 10 byte commands. The .Nm driver first attempts to determine whether the protocol in use typically supports 6 byte commands by issuing a CAM Path Inquiry CCB. It will then default to 6 byte or 10 byte commands as appropriate. After that, the .Nm driver defaults to using 6 byte commands (assuming the protocol the drive speaks claims to support 6 byte commands), until one fails with a -.Tn SCSI +.Tn SCSI ILLEGAL REQUEST error. Then it tries the 10 byte version of the command to see if that works instead. Users can change the default via per-drive sysctl variables and loader tunables. The variable names are the same in both instances: .Pp .Va kern.cam.cd.%d.minimum_cmd_size .Pp -Where +Where .Dq %d is the unit number of the drive in question. Valid minimum command sizes are 6 and 10. Any value above 6 will be rounded to 10, and any value below 6 will be rounded to 6. .Sh CHANGER OPERATION This driver has built-in support for LUN-based CD changers. A LUN-based CD changer is a drive that can hold two or more CDs, but only has one CD player mechanism. Each CD in the drive shows up as a separate logical unit on the .Tn SCSI bus. The .Nm driver automatically recognizes LUN-based changers, and routes commands for changers through an internal scheduler. The scheduler prevents changer "thrashing", which is caused by sending commands to different LUNs in the changer at the same time. .Pp The scheduler honors minimum and maximum time quanta that the driver will spend on a particular LUN. The minimum time is the guaranteed minimum amount of time that the driver will spend on a given LUN, even if there is no outstanding I/O for that LUN. The maximum time is the maximum amount of time the changer will spend on a LUN if there is outstanding I/O for another LUN. If there is no outstanding I/O for another LUN, the driver will allow indefinite access to a given LUN. .Pp The minimum and maximum time quanta are configurable via kernel options and also via sysctl and kernel tunable variables. The kernel options are: .Pp .Bl -item -compact .It .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" .It .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11""" .El .Pp The sysctl/kernel tunable variables are: .Pp .Bl -item -compact .It .Va kern.cam.cd.changer.min_busy_seconds .It .Va kern.cam.cd.changer.max_busy_seconds .El .Pp It is suggested that the user try experimenting with the minimum and maximum timeouts via the sysctl variables to arrive at the proper values for your changer. Once you have settled on the proper timeouts for your changer, you can then put them in your kernel config file. .Pp If your system does have a LUN-based changer, you may notice that the probe messages for the various LUNs of the changer will continue to appear while the boot process is going on. This is normal, and is caused by the changer scheduling code. .Sh FILES .Bl -tag -width /dev/cd[0-9][a-h] -compact .It Pa /dev/cd[0-9][a-h] raw mode .Tn CD-ROM devices .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr da 4 , .Xr scsi 4 , .Xr disklabel 5 , .Xr disklabel 8 , .Xr cd 9 .Sh BUGS The names of the structures used for the third argument to .Fn ioctl were poorly chosen, and a number of spelling errors have survived in the names of the .Fn ioctl commands. .Pp There is no mechanism currently to set different minimum and maximum timeouts for different CD changers; the timeout values set by the kernel options or the sysctl variables apply to all LUN-based CD changers in the system. It is possible to implement such support, but the sysctl implementation at least would be rather inelegant, because of the current inability of the sysctl code to handle the addition of nodes after compile time. Thus, it would take one dynamically sized sysctl variable and a userland utility to get/set the timeout values. Implementation of separate timeouts for different CD devices in the kernel config file would likely require modification of .Xr config 8 to support the two timeouts when hardwiring .Nm devices. .Sh HISTORY This .Nm driver is based upon the .Nm driver written by Julian Elischer, which appeared in .Bx 386 0.1 . The CAM version of the .Nm driver was written by Kenneth Merry and first appeared in .Fx 3.0 . Index: head/share/man/man4/da.4 =================================================================== --- head/share/man/man4/da.4 (revision 131471) +++ head/share/man/man4/da.4 (revision 131472) @@ -1,321 +1,321 @@ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 2, 2003 .Dt DA 4 .Os .Sh NAME .Nm da .Nd SCSI Direct Access device driver .Sh SYNOPSIS .Cd device da .Sh DESCRIPTION The .Nm driver provides support for all .Tn SCSI devices of the direct access class that are attached to the system through a supported .Tn SCSI Host Adapter. The direct access class includes disk, magneto-optical, and solid-state devices. .Pp A .Tn SCSI Host adapter must also be separately configured into the system before a .Tn SCSI direct access device can be configured. .Sh PARTITIONING The .Nm driver allows the disk to have two levels of partitioning. One layer, called the .Dq slice layer , is used to separate the .Fx areas of the disk from areas used by other operating systems. The second layer is the native .Bx 4.4 partitioning scheme, .Xr disklabel 5 , which is used to subdivide the .Fx slices into areas for individual file systems and swap spaces. For more information, see .Xr fdisk 8 and .Xr disklabel 8 , respectively. .Pp If an uninitialized disk is opened, the slice table will be initialized with a fictitious .Fx slice spanning the entire disk. Similarly, if an uninitialized (or .No non- Ns Fx ) slice is opened, its disklabel will be initialized with parameters returned by the drive and a single .Sq Li c partition encompassing the entire slice. .Sh CACHE EFFECTS Many direct access devices are equipped with read and/or write caches. Parameters affecting the device's cache are stored in mode page 8, the caching control page. Mode pages can be examined and modified via the .Xr camcontrol 8 utility. .Pp The read cache is used to store data from device-initiated read ahead operations as well as frequently used data. The read cache is transparent to the user and can be enabled without any adverse effect. Most devices with a read cache come from the factory with it enabled. The read cache can be disabled by setting the .Tn RCD (Read Cache Disable) bit in the caching control mode page. .Pp The write cache can greatly decrease the latency of write operations and allows the device to reorganize writes to increase efficiency and performance. This performance gain comes at a price. Should the device lose power while its cache contains uncommitted write operations, these writes will be lost. The effect of a loss of write transactions on a file system is non-deterministic and can cause corruption. Most devices age write transactions to limit vulnerability to a few transactions recently reported as complete, but it is none-the-less recommended that systems with write cache enabled devices reside on an Uninterruptible Power Supply (UPS). The .Nm device driver ensures that the cache and media are synchronized upon -final close of the device or an unexpected shutdown (panic) event. +final close of the device or an unexpected shutdown (panic) event. This ensures that it is safe to disconnect power once the operating system has reported that it has halted. The write cache can be enabled by setting the .Tn WCE (Write Cache Enable) bit in the caching control mode page. .Sh TAGGED QUEUING The .Nm device driver will take full advantage of the SCSI feature known as tagged queueing. Tagged queueing allows the device to process multiple transactions concurrently, often re-ordering them to reduce the number and length of seeks. To ensure that transactions to distant portions of the media, which may be deferred indefinitely by servicing requests nearer the current head position, are completed in a timely fashion, an ordered tagged transaction is sent every 15 seconds during continuous device operation. .Sh BAD BLOCK RECOVERY Direct Access devices have the capability of mapping out portions of defective media. Media recovery parameters are located in mode page 1, the Read-Write Error Recovery mode page. The most important media remapping features are 'Auto Write Reallocation' and 'Auto Read Reallocation' which can be enabled via the AWRE and ARRE bits, respectively, of the Read-Write Error Recovery page. Many devices do not ship from the factory with these feature enabled. Mode pages can be examined and modified via the .Xr camcontrol 8 utility. .Sh KERNEL CONFIGURATION It is only necessary to explicitly configure one .Nm device; data structures are dynamically allocated as disks are found on the .Tn SCSI bus. .Sh IOCTLS The following .Xr ioctl 2 calls apply to .Tn SCSI disks as well as to other disks. They are defined in the header file .In sys/disklabel.h . .Pp .Bl -tag -width DIOCSDINFO .It Dv DIOCSBAD Usually used to set up a bad-block mapping system on the disk. .Tn SCSI drives incorporate their own bad-block mapping so this command is not implemented. .It Dv DIOCGDINFO Read, from the kernel, the in-core copy of the disklabel for the drive. This may be a fictitious disklabel if the drive has never been initialized, in which case it will contain information read from the .Tn SCSI inquiry commands. .It Dv DIOCSDINFO Give the driver a new disklabel to use. The driver .Em will not write the new disklabel to the disk. .It Dv DIOCWLABEL Enable or disable the driver's software write protect of the disklabel on the disk. .It Dv DIOCWDINFO Give the driver a new disklabel to use. The driver .Em will write the new disklabel to the disk. .El .Sh SYSCTL VARIABLES The following variables are available as both .Xr sysctl 8 variables and .Xr loader 8 tunables: .Bl -tag -width 12 .It kern.cam.da.retry_count .Pp This variable determines how many times the .Nm driver will retry a READ or WRITE command. This does not affect the number of retries used during probe time or for the .Nm driver dump routine. This value currently defaults to 4. .It kern.cam.da.default_timeout .Pp This variable determines how long the .Nm driver will wait before timing out an outstanding command. The units for this value are seconds, and the default is currently 60 seconds. .It kern.cam.da.%d.minimum_cmd_size .Pp This variable determines what the minimum READ/WRITE CDB size is for a given .Nm unit. (The %d above denotes the unit number of the .Nm driver instance, e.g. 1, 2, 4, 8, etc.) Valid minimum command size values are 6, 10, 12 and 16 bytes. The default is 6 bytes. .Pp The .Nm driver issues a CAM Path Inquiry CCB at probe time to determine whether the protocol the device in question speaks (e.g. ATAPI) typically doesn't allow 6 byte commands. If it doesn't, the .Nm driver will default to using at least 10 byte CDBs. If a 6 byte READ or WRITE fails with an ILLEGAL REQUEST error, the .Nm driver will then increase the default CDB size for the device to 10 bytes and retry the command. CDB size is always chosen as the smallest READ/WRITE CDB that will satisfy the specified minimum command size, and the LBA and length of the READ or WRITE in question. (e.g., a write to an LBA larger than 2^32 will require a 16 byte CDB.) .El .Sh NOTES If a device becomes invalidated (media is removed, device becomes unresponsive) the disklabel and information held within the kernel about the device will be invalidated. To avoid corruption of a newly inserted piece of media or a replacement device, all accesses to the device will be discarded until the last file descriptor referencing the old device is closed. During this period, all new open attempts will be rejected. .Sh FILES .Bl -tag -width /dev/rsdXXXXX -compact .Sm off .It Pa /dev/da Ar u Pa s Ar n .Sm on raw mode .Tn SCSI disk unit .Ar u , slice .Ar n , accessed as an unpartitioned device .It Pa /dev/da Ns Ar u Ns Ar p raw mode .Tn SCSI disk unit .Ar u , first .Fx slice, partition .Ar p .Sm off .It Xo .Pa /dev/da .Ar u .Pa s .Ar n .Ar p .Xc .Sm on raw mode .Tn SCSI disk unit .Ar u , .Ar n Ns th slice, partition .Ar p .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr ad 4 , .Xr disklabel 5 , .Xr disklabel 8 , .Xr fdisk 8 .Sh HISTORY The .Nm driver was written for the .Tn CAM .Tn SCSI subsystem by .An Justin T. Gibbs . Many ideas were gleaned from the .Nm sd device driver written and ported from .Tn Mach 2.5 by .An Julian Elischer . Support for slices was written by .An Bruce Evans . Index: head/share/man/man4/man4.i386/acpi_asus.4 =================================================================== --- head/share/man/man4/man4.i386/acpi_asus.4 (revision 131471) +++ head/share/man/man4/man4.i386/acpi_asus.4 (revision 131472) @@ -1,114 +1,114 @@ .\" .\" Copyright (c) 2004 Philip Paeps .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 22, 2004 .Dt ACPI_ASUS 4 i386 .Os .Sh NAME .Nm acpi_asus .Nd Asus Laptop Extras .Sh SYNOPSIS .Cd "device acpi_asus" .Sh DESCRIPTION The .Nm driver provides support for the extra ACPI-controlled gadgets, such as hotkeys and leds, found on recent Asus (and Medion) laptops. It allows one to use the .Xr sysctl 8 interface to manipulate the brightness of the LCD panel and the display output state. Hotkey events are passed to .Xr devd 8 for easy handling in userspace. .Pp Currently, the following laptops are fully supported: .Pp .Bl -tag -width ident -compact .It L2D .It L3C .It L3D .It L3H .It L8L .It M1A .It M2E .El .Pp .Sh SYSCTLS The following sysctls are currently implemented: .Bl -tag -width indent .It Va hw.acpi.asus.lcd_brightness Makes the LCD backlight brighter or dimmer (higher values are brighter). .It Va hw.acpi.asus.lcd_backlight Turns the LCD backlight on or off. .It Va hw.acpi.asus.video_output Sets the active display to use according to a bitwise OR or of the following: .Pp .Bl -tag -width indent -compact .It Li 0 No display .It Li 1 LCD .It Li 2 CRT .It Li 4 TV-Out .El .Pp Some models also support video switching via the generic .Xr acpi_video 4 driver. Most models don't, however. .El .Pp Defaults for these variables can be set in .Xr sysctl.conf 5 , which is parsed at boot-time. .Sh SEE ALSO .Xr acpi 4 , .Xr acpi_video 4 , .Xr sysctl.conf 5 , .Xr sysctl 8 .Rs .%T The Acpi4Asus Project .%O http://sourceforge.net/projects/acpi4asus/ .Re .Sh HISTORY The .Nm driver first appeared in .Fx 5.3 . .Sh AUTHORS .An -nosplit The .Nm driver and this manual page were written by .An Philip Paeps Aq philip@FreeBSD.org . .Pp -Inspiration came from the -.Em acpi4asus project +Inspiration came from the +.Em acpi4asus project started by Julien Lerouge which maintains a driver implementing this functionality in the Linux kernel. Index: head/share/man/man4/man4.i386/ct.4 =================================================================== --- head/share/man/man4/man4.i386/ct.4 (revision 131471) +++ head/share/man/man4/man4.i386/ct.4 (revision 131472) @@ -1,148 +1,148 @@ .\" Copyright (c) 2003 Noriaki MITSUNAGA. All rights reserved. .\" Copyright (c) 2003 Hideyuki KURASHINA. 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 AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 18, 2003 .Dt CT 4 .Os .Sh NAME .Nm ct .Nd "WD33C93[ABC] based CBUS SCSI host adapter driver" .Sh SYNOPSIS .Cd "device ct" .Cd "device scbus" .Pp In .Pa /boot/device.hints: .Pp For most PC-9801-55, -92 and compatibles: .Cd hint.ct.0.at="isa" .Pp For ELECOM bus-master -.Tn SCSI +.Tn SCSI adapters: .Cd hint.ct.0.at="isa" .Cd hint.ct.0.flags="0x30000" .Pp For I-O DATA SC98 adapters: .Cd hint.ct.0.at="isa" .Cd hint.ct.0.flags="0x10000" .Pp For LOGITEC adapters: .Cd hint.ct.0.at="isa" .Cd hint.ct.0.flags="0x50000" .Pp For TEXA adapters: .Cd hint.ct.0.at="isa" .Cd hint.ct.0.flags="0x20000" .Pp For adapters with SMIT transfer mode to enable SMIT transfer: .Cd hint.ct.0.at="isa" .Cd hint.ct.0.flags="0x40000" .Cd hint.ct.0.maddr="0xdc000" .Pp .Ar Flag meaning: .Bl -tag -offset indent -compact -width 0x000000 .It 0x00000 -DMA transfer mode for an NEC PC-9801-55, -92 (or -compatibles), ICM IF-2660, Midori-Denshi MDC-554NA, or +DMA transfer mode for an NEC PC-9801-55, -92 (or +compatibles), ICM IF-2660, Midori-Denshi MDC-554NA, or Logitec LHA-N151 .It 0x10000 DMA transfer mode for an I-O DATA SC-98II .It 0x20000 -bus-master transfer mode for a TEXA HA-55BS2, its +bus-master transfer mode for a TEXA HA-55BS2, its successors, or Midori-Denshi MDC-926R .It 0x30000 -bus-master transfer mode for an ELECOM bus-master SCSI +bus-master transfer mode for an ELECOM bus-master SCSI adapter .It 0x40000 SMIT transfer mode (for supported adapters only) .It 0x50000 -bus-master transfer mode for a Logitec LHA-20x series, +bus-master transfer mode for a Logitec LHA-20x series, ICM IF-2766, IF-2766ET, IF-2767 or IF-2769 .Sh DESCRIPTION The .Nm -driver provides access to the -.Tn SCSI +driver provides access to the +.Tn SCSI bus connected to a WD33C93[ABC] based host adapter. The following adapters are supported: .Pp .Bl -bullet -compact .It -NEC PC-9801-55, 92 and compatibles, +NEC PC-9801-55, 92 and compatibles, .It -ELECOM bus-master -.Tn SCSI -adapters, +ELECOM bus-master +.Tn SCSI +adapters, .It -I-O DATA SC-98II, +I-O DATA SC-98II, .It -ICM IF-2660, IF-2766, IF-2766ET, IF-2767 and IF-2769, +ICM IF-2660, IF-2766, IF-2766ET, IF-2767 and IF-2769, .It -Logitec LHA-N151 and LHA-20x series, +Logitec LHA-N151 and LHA-20x series, .It -Midori-Denshi MDC-554NA and MDC-926R, +Midori-Denshi MDC-554NA and MDC-926R, .It -TEXA HA-55BS2 and its later models, and +TEXA HA-55BS2 and its later models, and .It -SMIT transfer type -.Tn SCSI +SMIT transfer type +.Tn SCSI host adapters. .El .Sh SEE ALSO .Xr cd 4 , .Xr ch 4 , .Xr ctau 4 , .Xr da 4 , .Xr intro 4 , .Xr sa 4 , .Xr scsi 4 .Sh NOTES Historically, the driver for the Cronyx Tau WAN adapters was ct. This device name was changed to ctau to avoid conflicts with this pc98 ct driver. The network device name for ctau is 'ct'. Please see .Xr ctau 4 for the details for that device. .Sh HISTORY The .Nm device driver has been developed for NetBSD/pc98 and ported for .Fx . It first appeared in .Fx 4.4 . .Sh AUTHORS The .Nm driver was written by .An Naofumi HONDA . .Pp This manual page was written by .An -nosplit -.An Noriaki MITSUNAGA Aq non@FreeBSD.org +.An Noriaki MITSUNAGA Aq non@FreeBSD.org and .An Hideyuki KURASHINA Aq rushani@FreeBSD.org . Index: head/share/man/man4/man4.i386/ndis.4 =================================================================== --- head/share/man/man4/man4.i386/ndis.4 (revision 131471) +++ head/share/man/man4/man4.i386/ndis.4 (revision 131472) @@ -1,125 +1,125 @@ .\" Copyright (c) 2003 .\" Bill Paul . 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 Bill Paul. .\" 4. Neither the name of the author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 10, 2003 .Dt NDIS 4 i386 .Os .Sh NAME .Nm ndis .Nd NDIS miniport driver wrapper .Sh SYNOPSIS .Cd "options NDISAPI" .Cd "device ndis" .Cd "device wlan" .Sh DESCRIPTION The .Nm driver is a wrapper designed to allow binary Windows(r) NDIS miniport network drivers to be used with .Fx . The .Nm driver is provided in source code form and must be combined with the Windows(r) driver supplied with your network adapter. The .Nm driver uses the .Xr ndisapi 9 kernel subsystem to relocate and link the Windows(r) binary so that it can be used in conjunction with native code. The .Xr ndisapi 9 subsystem provides an interface between the NDIS API and the .Fx networking infrastructure. The Windows(r) driver is essentially fooled into thinking it's running on Windows(r). Note that this means the .Nm driver is only useful on x86 machines. .Pp To build a functional driver, the user must have a copy of the driver distribution media for his or her card. From this distribution, the user must extract two files: the .SYS file containing the driver binary code, and its companion .INF file, which contains the definitions for driver-specific registry keys and other installation data such as device identifiers. These two files can be converted -into a +into a .Pa ndis_driver_data.h file using the .Xr ndiscvt 8 utility. This file contains a binary image of the driver plus registry key data. When the .Nm driver loads, it will create .Xr sysctl 9 nodes for each registry key extracted from the .INF file. .Pp The .Nm driver is designed to support mainly ethernet and wireless network devices with PCI and PCMCIA bus attachments. (Cardbus devices are also supported as a subset of PCI.) It there can support many different media types and speeds. One limitation however, is that there is no consistent way to learn if an ethernet device is operating in full or half duplex mode. The NDIS API allows for a generic means for determining link state and speed, but not the duplex setting. There may be driver-specific registry keys to control the media setting which can be configured via the .Xr sysctl 8 command. .Sh DIAGNOSTICS .Bl -diag .It "ndis%d: watchdog timeout" A packet was queued for transmission and a transmit command was issued, however the device failed to acknowledge the transmission before a timeout expired. .El .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr ifconfig 8 , .Xr ndisapi 9 , .Xr ndiscvt 8 .Rs .%T "NDIS 5.1 specification" .%O http://www.microsoft.com .Re .Sh HISTORY The .Nm device driver first appeared in .Fx 5.3 . .Sh AUTHORS The .Nm driver was written by .An Bill Paul Aq wpaul@windriver.com . Index: head/share/man/man4/matcd.4 =================================================================== --- head/share/man/man4/matcd.4 (revision 131471) +++ head/share/man/man4/matcd.4 (revision 131472) @@ -1,454 +1,454 @@ .\"Matsushita(Panasonic) / Creative Compact Disc Drive Driver (matcd) .\"Authored by Frank Durda IV .\" .\"Program and Documentation are Copyright 1994, 1995, 2003, 2003 Frank Durda IV. .\"All rights reserved. .\" "FDIV" is a trademark of Frank Durda IV. .\" .\" .\"Redistribution and use in source and binary forms, with or without .\"modification, are permitted provided that the following conditions .\"are met: .\"1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\"2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\"3. Neither the name of the author nor the names of their contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\"THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\"IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\"ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\"FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\"DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\"OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\"HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\"LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\"OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\"SUCH DAMAGE. .\" .\"-------------------------------------------------------------------------- .\"Dedicated to: My family, my grandfather, .\" and Max, my Golden Retriever .\" .\" Please note any documentation updates here including your name .\" and the date. .\"<2> Text brought in sync with changes made in versions 1(17) - 1(21) .\" Frank Durda IV 4-Jul-1995 .\"<3> Text brought in sync with changes made in versions 1(22) - 1(25) .\" Frank Durda IV 24-Sep-1995 .\"<4> Overhaul of man page to match version 3(41) (FreeBSD 5.0 support) .\" and style changes noted in other 5.x era man pages. .\" Frank Durda IV 17-Apr-2003 .\"<5> Aligned with version 3(42) (FreeBSD pre5.1 support) .\" Frank Durda IV 10-May-2003 .\" .\" $FreeBSD$ .\" .Dd May 10, 2003 .Dt MATCD 4 .\"Synchronized to Version 3(42) of matcd.c .Os .Sh NAME .Nm matcd .Nd Matsushita (Panasonic) Compact Disc drive driver .Sh SYNOPSIS .Cd "device matcd" .Pp In .Pa /boot/device.hints : .Cd hint.matcd.\fI[0-3]\fP.at="isa" .Cd hint.matcd.\fI[0-3]\fP.port="\fIaddress\fP" .Sh DESCRIPTION The .Nm driver controls the CR-562 and CR-563 Compact Disc drives made by Matsushita-Kotobuki Electronics Industries, or Matsushita for short. These drives were sold under the Panasonic (which is a trade name for Matsushita), Creative Labs (omniCD) and Reveal names, and were -also included in computers that were made by Tandy, GRiD, Victor, AST, +also included in computers that were made by Tandy, GRiD, Victor, AST, Packard Bell and many other brands. .Pp The drives are compatible with the major the Compact Disc standards, including CD-DA (Red Book - Digital Audio on pressed media), CD-WO (Orange Book Part II - Write-Once media), CD-ROM (Yellow Book - Data Storage), and -the Kodak Photo-CD system. The drives have some support related to +the Kodak Photo-CD system. The drives have some support related to CD-ROM XA and CD-I (Green Book) audio and data requirements. .Pp These drives connect to the PC ISA bus through a simple (but proprietary) host interface. The host interface has been manufactured as a stand-alone adapter card, or included on a sound card or other multi-function adapter card. The .Nm driver supports up to four host interfaces with up to four drives on each interface. CD-DA (digital audio) activity may occur on all drives simultaneously. .Pp The drive hardware supports a "bus disconnect" system similar to that found in SCSI, and this allows simultaneous data read operations to be in progress on multiple drives on the same host interface, but the driver currently limits read operations to one active drive per host interface at a time. Despite this, all four drives on a given host interface are able deliver data at their full rated transfer rate for sequential blocks simultaneously, thanks to a modest read-ahead buffer in each drive. .Sh DRIVER INSTALLATION The .Nm driver can be directly linked into the .Fx -kernel, or exist -as a loadable +kernel, or exist +as a loadable .Fx kernel module. The kernel module can be loaded or unloaded at any time using the \fBkldload\fR(8)/\fBkldunload\fR(8) commands. .Pp For most configurations, the .Nm driver should be used as a loadable kernel module and need not be linked into the kernel. However, if you are attempting to do an install from a CD-ROM/CD-WO disc that is initiated from a non-FreeBSD operating system or you have a BIOS boot capability for this type of Compact Disc drive, having the driver already in the kernel can simplify the installation process. .Pp if you determine that you need to have the .Nm driver linked into the kernel, it is necessary to add an entry to the kernel -configuration file and generate a new kernel. The +configuration file and generate a new kernel. The .Fx kernel source tree comes with the file \fI/usr/src/sys/i386/conf/GENERIC\fR. You should make a copy of this file and give the copy the name of your system, such as "MYSYSTEM". You can then edit the new file to include devices you want the system to include in the basic kernel and delete the device entries for drivers that you don't want included. Eliminating drivers for hardware that you don't have can reduce the size of the finished kernel. .Pp To include the .Nm driver to the configuration file, you will need to add this entry: .Bd -literal -offset indent device matcd .Ed .Pp and after making any other adjustments, save the file. .Pp Then generate a new kernel by using the \fBconfig\fR(8) command and follow all of the instructions that are displayed. If the kernel completely builds, use the "make install" command and then reboot the system for that new kernel to become operational. .Sh DRIVER CONFIGURATION -Regardless of whether the +Regardless of whether the .Nm -driver is linked into the kernel or is used as a loadable kernel module, +driver is linked into the kernel or is used as a loadable kernel module, the number of host interfaces that the driver will expect (or search for) is dictated by the number of entries present in the file \fI/boot/device\.hints\fR. For example, in order to support two host interfaces, you would include entries like: .Bd -literal -offset indent hint.matcd.0.at="isa" hint.matcd.0.port="0x230" hint.matcd.1.at="isa" hint.matcd.1.port="0x260" .Ed Each set of entries designates a different -.Nm +.Nm host interface, and where the I/O ports on that host interface adapter are located. .Pp (If you only want a single entry, include only the \fBhint.matcd.0\fR items, while add \fBhint.matcd.2\fR and \fBhint.matcd.3\fR as needed to support three or four host interfaces.) .Pp Note that the two \fBhint.matcd.0\fR entries in the \fI/boot/device\.hints\fR file are all that you need to support up to four drives on a single host interface. .Pp If the \fIaddress\fR parameter of a \fBhint.matcd.\fIn\fR.port="\fIaddress\fP"\fR entry -in \fI/boot/device\.hints\fR file is set to "\fB-1\fR", the +in \fI/boot/device\.hints\fR file is set to "\fB-1\fR", the .Nm driver searches for the host interface adapters by using a table of known I/O ports on Creative host adapters contained in the driver itself -(see \fI/usr/src/sys/dev/matcd/options.h\fR). +(see \fI/usr/src/sys/dev/matcd/options.h\fR). .Pp -Although the multiple port scan allows the +Although the multiple port scan allows the .Nm driver to work with many different types of host adapters without adjustments, using this mechanism has the potential to cause problems when your system has other devices that are located at the I/O ports that the driver will check for potential .Nm host interfaces. The automatic search also significantly increases the amount of time it takes to boot or to load the kernel module. .Pp If you are having problems with the .Nm driver interfering with other adapters while it is probing for hardware, or you don't like the additional amount of time it takes for the entire search of I/O ports to complete, you can solve this by explicitly specifying where all the .Nm host interfaces are located. .Pp Traditionally, Creative Labs SoundBlaster cards have the Matsushita Compact Disc drive host interface located at I/O port 0x230, which is always 0x10 above where the first I/O port for the audio section of the card (0x220). .Pp If you have determined exactly where the Matsushita I/O ports start on your system, specify the port by setting the \fBhint.matcd.\fIn\fR.port="\fIaddress\fP"\fR entry at the kernel boot -prompt, or by editing the entry in the \fI/boot/device\.hints\fR file. +prompt, or by editing the entry in the \fI/boot/device\.hints\fR file. .Pp If you make a change to the \fI/boot/device\.hints\fR configuration file while the system is running, it is currently necessary to reboot the system before the updated values take effect. .Sh SUPPORTED HARDWARE At this time, there are only two known drive models that work with the .Nm driver: .Bl -item -width CR-123-X -compact -offset indent .It Matsushita CR-562-x .It Matsushita CR-563-x .El Most resellers leave these original markings on the drives since the label also has the FCC, VDE, CSA and RU certification marks. .Pp Both of these drive models have motorized trays. There is also a custom version of these drives that does not have the volume control or headphone jack (seen on some Tandy computers), but this drive also works with .Nm . On drives that lack a front headphone jack, audio from discs can still be obtained at line level via a connector on the rear of the drive. .Pp The Matsushita CR-522-x and CR-523-x Compact Disc drives are not usable with .Nm . The CR-522 and CR-523 models can also be identified from the front as they both require a CD-caddy. .Pp Later versions of Matsushita and "Creative" Compact Disc drives use a basic IDE interface, so these other drives must use an IDE driver, such as \fBata\fR(4). .Pp -The TEAC CD-55 4X Compact Disc drive also uses the same Creative/Panasonic +The TEAC CD-55 4X Compact Disc drive also uses the same Creative/Panasonic electrical interface, but the TEAC drive is not command set compatible with the Matsushita CR-56x drives. The TEAC drive cannot be used with .Nm . .Pp The most common source of host interface adapters for the Panasonic drives was found in products from Creative Labs, including SoundBlaster sound cards. There are numerous models of SoundBlaster sound cards, and most of the newer cards provide the appropriate interface, sometimes labeled as the "Creative/Panasonic" interface. .Pp The following host interface adapters are known to work with the .Nm driver: .Bl -tag -width LONGNAME -compact -offset indent .It Creative Sound Blaster Pro (SBPRO) (CT1330A) .It Creative Sound Blaster 16 (CT1730) .It Creative Sound Blaster 16 - cost-reduced (CT1740) .It Creative OmniCD upgrade kit adapter card - stand-alone CD (CT1810) .It Creative Sound Blaster 16 - 2-layer, cost-reduced (CT2230) .It Creative Sound Blaster 16 (Vibra16) - 2-layer, single-chip (CT2260) .It Creative Sound Blaster 16 Value (SB16) - 2-layer, cost-reduced (CT2770) .It Creative PhoneBlaster SB16 + Sierra 14.4K Voice/FAX/Data/Speakerphone modem combo (CT3100) .It Reveal (SC400) .El .Pp Caution: Some of these sound boards can be optionally manufactured to not include the Panasonic/Creative interface connector and electronics, so check the board visually to verify that the "Creative" or "Panasonic" drive connector is actually there before buying the card solely based on model number. .Pp This is by no means a complete list as Creative Labs and other vendors that produce sound cards with an identical Creative/Panasonic drive interface released many versions of compatible adapters. .Pp In addition to Creative Labs adapters, adapters that are compatible with Media Vision, IBM and Lasermate adapters are also supported. However, these adapters use a wide range of I/O port addresses, so the driver must be reconfigured to locate these adapters, at least initially. .Pp .Sh SUPPORTED OPERATIONS The .Nm driver supports block and character access. Partition "a" returns 2048-byte User Data blocks from data CDs. Partition "c" returns the full 2352-byte Frames from any type of CD, including audio CDs. (Partition "c" cannot be "mounted" with cd9660 or other standard file system emulators.) No other partitions are supported. .Pp The .Nm matcdl devices work the same as the normal .Nm devices except that the drive trays are locked and remain locked until all of the devs on that drive are closed. .Pp .Nm Matcd accepts numerous .Fn ioctl commands, including functions related to Compact Disc audio and drive tray control features. The commands are: .Pp .Bl -tag -width CDIOCREADSUBCHANNELXXX -compact -offset indent .It DIOCGDINFO get disklabel. .It CDIOCREADSUBCHANNEL report the current optical pick-up position and sub channel data. .It CDIOCREADTOCHEADER reads table of contents summary from the disc. .It CDIOCREADTOCENTRYS reads length/size and other control information for an individual track. .It CDIOCPLAYTRACKS plays audio starting at a track/index and stopping at a track/index. .It CDIOCPLAYBLOCKS plays audio starting at a block and stopping at a block. .It CDIOCPLAYMSF plays audio starting at a particular time offset. .It CDIOCPAUSE pauses a playing disc. .It CDIOCRESUME resumes playing a previously paused disc. Ignored if the drive is already playing. .It CDIOCSTOP stops playing a disc. .It CDIOCEJECT opens the disc tray. .It CDIOCCLOSE closes the disc tray. .It CDIOCPREVENT blocks further attempts to open the drive door until all devices close or a CDIOCALLOW ioctl is issued. .It CDIOCALLOW unlocks the drive door if it was locked. This ioctl is rejected if any locking devices are open, so it must be issued via a non-locking device. .It CDIOCGETVOL returns the current volume settings of the drive. .It CDIOCSETVOL sets the volume settings of the drive. .It CDIOCSETSTEREO the left channel audio is sent to the left channel output and the right channel audio is sent to the right channel output. This is the default state. (Note that the drive does not have a documented "Mono" mode, where L combined with R audio from the disc is sent to both the left and right output channels.) .It CDIOCSETMUTE the audio output is to be turned off. The drive continues to read the audio on the disc and that audio is discarded until the audio routing is turned back on. .It CDIOCSETLEFT the left channel audio is to be sent to the left and right channel outputs. The right channel audio signal is discarded. .It CDIOCSETRIGHT the right channel audio is to be sent to the left and right channel outputs. The left channel audio signal is discarded. .It CDIOCSETPATCH the audio is to be routed as specified in the provided bit maps. .It CDIOCSETPITCH the playback speed of the audio is increased or decreased (for Karaoke "off-key" applications). Speed can be adjusted +/-13%. .It CDIOCCAPABILITY report the capabilities of the drive and driver. Results are returned as shown in \fI/usr/include/sys/cdio.h\fR. .El .Pp The .Fn ioctl commands defined above are the only ones that the .Nm driver supports. .Sh FILES .Bl -tag -width /usr/src/sys/dev/matcd/options.h -compact .It Pa /dev/matcd[0-15]a Used to access 2048-byte blocks of data on a Compact Disc that is recorded in the Mode 1 Form 1 format. .It Pa /dev/matcd[0-15]la Used to access 2048-byte blocks of data on a Compact Disc that is recorded in the Mode 1 Form 1 format and disables the disc eject controls. .It Pa /dev/matcd[0-15]c Used to access 2352-byte frames on a Compact Disc recorded in any format. .It Pa /dev/matcd[0-15]lc Used to access 2352-byte frames on a Compact Disc recorded in any format and disables the disc eject controls. .It Pa /boot/devices.hints Specify the number of host interfaces and host adapter I/O port locations -that -.Nm +that +.Nm should examine. .It Pa /usr/src/sys/dev/matcd/* Source code for .Nm . .It Pa /usr/src/sys/dev/matcd/options.h Contains all of the compilation options for .Nm . .El .Sh NOTES The various Creative/Panasonic host interface adapters do not use interrupts or DMA although the drives themselves are equipped to allow both to be used. .Pp If the disc tray is opened while one or more partitions are open, further I/O to all partitions on the drive will be rejected until all partitions are closed. This prevents a disc change from going undetected by higher levels of the operating system. .Pp There must be a drive on each host interface that is addressed as physical drive 0. (Jumpers on the back of the drive control this setting.) If there is no physical drive 0, the .Nm driver will be unable to detect that host interface or any of the drives connected to that host interface. .Pp It is not necessary to have four drives attached to the first host interface before being able to activate a second host interface, but each interface must have at least one drive jumpered to be drive 0. .Pp Drives on a second host interface are considered logical drive numbers 4 through 7, drives 8 through 11 are on the third interface and 12 through 15 are on the fourth. The first drive on the second host interface is always logical drive 4 regardless of how many drives are -present on the first host interface. +present on the first host interface. .Pp Host interfaces are numbered as specified in the \fI/boot/devices.hints\fR file. .Sh SEE ALSO .Xr /usr/include/sys/cdio.h , .Xr kldload 8 , .Xr kldunload 8 .Sh AUTHORS The driver and documentation was written by .An Frank Durda IV . .Pp Program and Documentation are Copyright 1994, 1995, 2002, 2003, All rights reserved. .Sh HISTORY The .Nm driver originally appeared in -.Fx 2.0.5 . The +.Fx 2.0.5 . The .Fx 5.1.x compatible implementation described here appeared in .Fx 5.2.0. Index: head/share/man/man4/multicast.4 =================================================================== --- head/share/man/man4/multicast.4 (revision 131471) +++ head/share/man/man4/multicast.4 (revision 131472) @@ -1,917 +1,917 @@ .\" Copyright (c) 2001-2003 International Computer Science Institute .\" .\" Permission is hereby granted, free of charge, to any person obtaining a .\" copy of this software and associated documentation files (the "Software"), .\" to deal in the Software without restriction, including without limitation .\" the rights to use, copy, modify, merge, publish, distribute, sublicense, .\" and/or sell copies of the Software, and to permit persons to whom the .\" Software is furnished to do so, subject to the following conditions: .\" .\" The above copyright notice and this permission notice shall be included in .\" all copies or substantial portions of the Software. .\" .\" The names and trademarks of copyright holders may not be used in .\" advertising or publicity pertaining to the software without specific .\" prior permission. Title to copyright in this software and any associated .\" documentation will at all times remain with the copyright holders. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE .\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER .\" DEALINGS IN THE SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd September 4, 2003 .Dt MULTICAST 4 .Os .\" .Sh NAME .Nm multicast .Nd Multicast Routing .\" .Sh SYNOPSIS .Cd "options MROUTING" .Pp .In sys/types.h .In sys/socket.h .In netinet/in.h .In netinet/ip_mroute.h .In netinet6/ip6_mroute.h .Ft int .Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen" .Ft int .Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen" .Sh DESCRIPTION .Tn "Multicast routing" is used to efficiently propagate data packets to a set of multicast listeners in multipoint networks. If unicast is used to replicate the data to all listeners, then some of the network links may carry multiple copies of the same data packets. With multicast routing, the overhead is reduced to one copy (at most) per network link. .Pp All multicast-capable routers must run a common multicast routing protocol. The Distance Vector Multicast Routing Protocol (DVMRP) was the first developed multicast routing protocol. Later, other protocols such as Multicast Extensions to OSPF (MOSPF), Core Based Trees (CBT), Protocol Independent Multicast - Sparse Mode (PIM-SM), and Protocol Independent Multicast - Dense Mode (PIM-DM) were developed as well. .Pp To start multicast routing, the user must enable multicast forwarding in the kernel (see .Sx SYNOPSIS about the kernel configuration options), and must run a multicast routing capable user-level process. From developer's point of view, the programming guide described in the .Sx "Programming Guide" section should be used to control the multicast forwarding in the kernel. .\" .Ss Programming Guide This section provides information about the basic multicast routing API. The so-called .Dq advanced multicast API is described in the .Sx "Advanced Multicast API Programming Guide" section. .Pp First, a multicast routing socket must be open. That socket would be used to control the multicast forwarding in the kernel. Note that most operations below require certain privilege (i.e., root privilege): .Pp .Bd -literal /* IPv4 */ int mrouter_s4; mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP); .Ed .Pp .Bd -literal int mrouter_s6; mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6); .Ed .Pp Note that if the router needs to open an IGMP or ICMPv6 socket (in case of IPv4 and IPv6 respectively) for sending or receiving of IGMP or MLD multicast group membership messages, then the same mrouter_s4 or mrouter_s6 sockets should be used for sending and receiving respectively IGMP or MLD messages. In case of BSD-derived kernel, it may be possible to open separate sockets for IGMP or MLD messages only. However, some other kernels (e.g., Linux) require that the multicast routing socket must be used for sending and receiving of IGMP or MLD messages. Therefore, for portability reason the multicast routing socket should be reused for IGMP and MLD messages as well. .Pp After the multicast routing socket is open, it can be used to enable or disable multicast forwarding in the kernel: .Bd -literal /* IPv4 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v)); .Ed .Pp .Bd -literal /* IPv6 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v)); \&... /* If necessary, filter all ICMPv6 messages */ struct icmp6_filter filter; ICMP6_FILTER_SETBLOCKALL(&filter); setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter, sizeof(filter)); .Ed .Pp After multicast forwarding is enabled, the multicast routing socket can be used to enable PIM processing in the kernel if we are running PIM-SM or PIM-DM (see .Xr pim 4 ) . .Pp For each network interface (e.g., physical or a virtual tunnel) that would be used for multicast forwarding, a corresponding multicast interface must be added to the kernel: .Bd -literal /* IPv4 */ struct vifctl vc; memset(&vc, 0, sizeof(vc)); /* Assign all vifctl fields as appropriate */ vc.vifc_vifi = vif_index; vc.vifc_flags = vif_flags; vc.vifc_threshold = min_ttl_threshold; vc.vifc_rate_limit = max_rate_limit; memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr)); if (vc.vifc_flags & VIFF_TUNNEL) memcpy(&vc.vifc_rmt_addr, &vif_remote_address, sizeof(vc.vifc_rmt_addr)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc, sizeof(vc)); .Ed .Pp The .Dq vif_index must be unique per vif. The .Dq vif_flags contains the .Dq VIFF_* flags as defined in . The .Dq min_ttl_threshold contains the minimum TTL a multicast data packet must have to be forwarded on that vif. Typically, it would have value of 1. The .Dq max_rate_limit contains the maximum rate (in bits/s) of the multicast data packets forwarded on that vif. Value of 0 means no limit. -The +The .Dq vif_local_address contains the local IP address of the corresponding local interface. The .Dq vif_remote_address contains the remote IP address in case of DVMRP multicast tunnels. .Pp .Bd -literal /* IPv6 */ struct mif6ctl mc; memset(&mc, 0, sizeof(mc)); /* Assign all mif6ctl fields as appropriate */ mc.mif6c_mifi = mif_index; mc.mif6c_flags = mif_flags; mc.mif6c_pifi = pif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc, sizeof(mc)); .Ed .Pp The .Dq mif_index must be unique per vif. The .Dq mif_flags contains the .Dq MIFF_* flags as defined in . The .Dq pif_index is the physical interface index of the corresponding local interface. .Pp A multicast interface is deleted by: .Bd -literal /* IPv4 */ vifi_t vifi = vif_index; setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi, sizeof(vifi)); .Ed .Pp .Bd -literal /* IPv6 */ mifi_t mifi = mif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi, sizeof(mifi)); .Ed .Pp After the multicast forwarding is enabled, and the multicast virtual interfaces are added, the kernel may deliver upcall messages (also called signals later in this text) on the multicast routing socket that was open earlier with .Dq MRT_INIT or .Dq MRT6_INIT . The IPv4 upcalls have .Dq struct igmpmsg header (see ) with field .Dq im_mbz set to zero. Note that this header follows the structure of .Dq struct ip with the protocol field .Dq ip_p set to zero. The IPv6 upcalls have .Dq struct mrt6msg header (see ) with field .Dq im6_mbz set to zero. Note that this header follows the structure of .Dq struct ip6_hdr with the next header field .Dq ip6_nxt set to zero. .Pp The upcall header contains field .Dq im_msgtype and .Dq im6_msgtype with the type of the upcall .Dq IGMPMSG_* and .Dq MRT6MSG_* for IPv4 and IPv6 respectively. The values of the rest of the upcall header fields and the body of the upcall message depend on the particular upcall type. .Pp If the upcall message type is .Dq IGMPMSG_NOCACHE or .Dq MRT6MSG_NOCACHE , this is an indication that a multicast packet has reached the multicast router, but the router has no forwarding state for that packet. Typically, the upcall would be a signal for the multicast routing user-level process to install the appropriate Multicast Forwarding Cache (MFC) entry in the kernel. .Pp A MFC entry is added by: .Bd -literal /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); mc.mfcc_parent = iif_index; for (i = 0; i < maxvifs; i++) mc.mfcc_ttls[i] = oifs_ttl[i]; setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp .Bd -literal /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); mc.mf6cc_parent = iif_index; for (i = 0; i < maxvifs; i++) if (oifs_ttl[i] > 0) IF_SET(i, &mc.mf6cc_ifset); setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_ADD_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp The .Dq source_addr and .Dq group_addr are the source and group address of the multicast packet (as set in the upcall message). The .Dq iif_index is the virtual interface index of the multicast interface the multicast packets for this specific source and group address should be received on. The .Dq oifs_ttl[] array contains the minimum TTL (per interface) a multicast packet should have to be forwarded on an outgoing interface. If the TTL value is zero, the corresponding interface is not included in the set of outgoing interfaces. Note that in case of IPv6 only the set of outgoing interfaces can be specified. .Pp A MFC entry is deleted by: .Bd -literal /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp .Bd -literal /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_DEL_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp The following method can be used to get various statistics per installed MFC entry in the kernel (e.g., the number of forwarded packets per source and group address): .Bd -literal /* IPv4 */ struct sioc_sg_req sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq); .Ed .Pp .Bd -literal /* IPv6 */ struct sioc_sg_req6 sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq); .Ed .Pp The following method can be used to get various statistics per multicast virtual interface in the kernel (e.g., the number of forwarded packets per interface): .Bd -literal /* IPv4 */ struct sioc_vif_req vreq; memset(&vreq, 0, sizeof(vreq)); vreq.vifi = vif_index; ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq); .Ed .Pp .Bd -literal /* IPv6 */ struct sioc_mif_req6 mreq; memset(&mreq, 0, sizeof(mreq)); mreq.mifi = vif_index; ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq); .Ed .Pp .Ss Advanced Multicast API Programming Guide If we want to add new features in the kernel, it becomes difficult to preserve backward compatibility (binary and API), and at the same time to allow user-level processes to take advantage of the new features (if the kernel supports them). .Pp -One of the mechanisms that allows us to preserve the backward +One of the mechanisms that allows us to preserve the backward compatibility is a sort of negotiation between the user-level process and the kernel: .Bl -enum .It The user-level process tries to enable in the kernel the set of new features (and the corresponding API) it would like to use. .It The kernel returns the (sub)set of features it knows about and is willing to be enabled. .It The user-level process uses only that set of features the kernel has agreed on. .El .\" .Pp To support backward compatibility, if the user-level process doesn't ask for any new features, the kernel defaults to the basic multicast API (see the .Sx "Programming Guide" section). .\" XXX: edit as appropriate after the advanced multicast API is .\" supported under IPv6 Currently, the advanced multicast API exists only for IPv4; in the future there will be IPv6 support as well. .Pp Below is a summary of the expandable API solution. Note that all new options and structures are defined in and , unless stated otherwise. .Pp The user-level process uses new get/setsockopt() options to perform the API features negotiation with the kernel. This negotiation must be performed right after the multicast routing socket is open. The set of desired/allowed features is stored in a bitset (currently, in uint32_t; i.e., maximum of 32 new features). The new get/setsockopt() options are .Dq MRT_API_SUPPORT and .Dq MRT_API_CONFIG . Example: .Bd -literal uint32_t v; getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v)); .Ed .Pp would set in .Dq v the pre-defined bits that the kernel API supports. The eight least significant bits in uint32_t are same as the eight possible flags .Dq MRT_MFC_FLAGS_* that can be used in .Dq mfcc_flags as part of the new definition of .Dq struct mfcctl (see below about those flags), which leaves 24 flags for other new features. The value returned by getsockopt(MRT_API_SUPPORT) is read-only; in other words, setsockopt(MRT_API_SUPPORT) would fail. .Pp To modify the API, and to set some specific feature in the kernel, then: .Bd -literal uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF; if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)) != 0) { return (ERROR); } if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF) return (OK); /* Success */ else return (ERROR); .Ed .Pp In other words, when setsockopt(MRT_API_CONFIG) is called, the argument to it specifies the desired set of features to be enabled in the API and the kernel. The return value in .Dq v is the actual (sub)set of features that were enabled in the kernel. To obtain later the same set of features that were enabled, then: .Bd -literal getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)); .Ed .Pp The set of enabled features is global. In other words, setsockopt(MRT_API_CONFIG) should be called right after setsockopt(MRT_INIT). .Pp Currently, the following set of new features is defined: .Bd -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ #define MRT_MFC_RP (1 << 8) /* enable RP address */ #define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */ .Ed .\" .Pp .\" In the future there might be: .\" .Bd -literal .\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */ .\" .Ed .\" .Pp .\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel. .\" For now this is left-out until it is clear whether .\" (*,G) MFC support is the preferred solution instead of something more generic .\" solution for example. .\" .\" 2. The newly defined struct mfcctl2. .\" .Pp The advanced multicast API uses a newly defined .Dq struct mfcctl2 instead of the traditional .Dq struct mfcctl . The original .Dq struct mfcctl is kept as is. The new .Dq struct mfcctl2 is: .Bd -literal /* * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays * and extends the old struct mfcctl. */ struct mfcctl2 { /* the mfcctl fields */ struct in_addr mfcc_origin; /* ip origin of mcasts */ struct in_addr mfcc_mcastgrp; /* multicast group associated*/ vifi_t mfcc_parent; /* incoming vif */ u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */ /* extension fields */ uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/ struct in_addr mfcc_rp; /* the RP address */ }; .Ed .Pp The new fields are .Dq mfcc_flags[MAXVIFS] and .Dq mfcc_rp . Note that for compatibility reasons they are added at the end. .Pp The .Dq mfcc_flags[MAXVIFS] field is used to set various flags per interface per (S,G) entry. Currently, the defined flags are: .Bd -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ .Ed .Pp The .Dq MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is used to explicitly disable the .Dq IGMPMSG_WRONGVIF kernel signal at the (S,G) granularity if a multicast data packet arrives on the wrong interface. Usually, this signal is used to complete the shortest-path switch in case of PIM-SM multicast routing, or to trigger a PIM assert message. However, it should not be delivered for interfaces that are not in the outgoing interface set, and that are not expecting to become an incoming interface. Hence, if the .Dq MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is set for some of the interfaces, then a data packet that arrives on that interface for that MFC entry will NOT trigger a WRONGVIF signal. If that flag is not set, then a signal is triggered (the default action). .Pp The .Dq MRT_MFC_FLAGS_BORDER_VIF flag is used to specify whether the Border-bit in PIM Register messages should be set (in case when the Register encapsulation is performed inside the kernel). If it is set for the special PIM Register kernel virtual interface (see .Xr pim 4 ) , the Border-bit in the Register messages sent to the RP will be set. .Pp The remaining six bits are reserved for future usage. .Pp The .Dq mfcc_rp field is used to specify the RP address (in case of PIM-SM multicast routing) for a multicast group G if we want to perform kernel-level PIM Register encapsulation. The .Dq mfcc_rp field is used only if the .Dq MRT_MFC_RP advanced API flag/capability has been successfully set by setsockopt(MRT_API_CONFIG). .Pp .\" .\" 3. Kernel-level PIM Register encapsulation .\" If the .Dq MRT_MFC_RP flag was successfully set by setsockopt(MRT_API_CONFIG), then the kernel will attempt to perform the PIM Register encapsulation itself instead of sending the multicast data packets to user level (inside IGMPMSG_WHOLEPKT upcalls) for user-level encapsulation. The RP address would be taken from the .Dq mfcc_rp field inside the new .Dq struct mfcctl2 . However, even if the .Dq MRT_MFC_RP flag was successfully set, if the .Dq mfcc_rp field was set to .Dq INADDR_ANY , then the kernel will still deliver an IGMPMSG_WHOLEPKT upcall with the multicast data packet to the user-level process. .Pp In addition, if the multicast data packet is too large to fit within a single IP packet after the PIM Register encapsulation (e.g., if its size was on the order of 65500 bytes), the data packet will be fragmented, and then each of the fragments will be encapsulated separately. Note that typically a multicast data packet can be that large only if it was originated locally from the same hosts that performs the encapsulation; otherwise the transmission of the multicast data packet over Ethernet for example would have fragmented it into much smaller pieces. .\" .\" Note that if this code is ported to IPv6, we may need the kernel to .\" perform MTU discovery to the RP, and keep those discoveries inside .\" the kernel so the encapsulating router may send back ICMP .\" Fragmentation Required if the size of the multicast data packet is .\" too large (see "Encapsulating data packets in the Register Tunnel" .\" in Section 4.4.1 in the PIM-SM spec .\" draft-ietf-pim-sm-v2-new-05.{txt,ps}). .\" For IPv4 we may be able to get away without it, but for IPv6 we need .\" that. .\" .\" 4. Mechanism for "multicast bandwidth monitoring and upcalls". .\" .Pp Typically, a multicast routing user-level process would need to know the forwarding bandwidth for some data flow. For example, the multicast routing process may want to timeout idle MFC entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if the bandwidth rate is above a threshold for example. .Pp The original solution for measuring the bandwidth of a dataflow was that a user-level process would periodically query the kernel about the number of forwarded packets/bytes per (S,G), and then based on those numbers it would estimate whether a source has been idle, or whether the source's transmission bandwidth is above a threshold. That solution is far from being scalable, hence the need for a new mechanism for bandwidth monitoring. .Pp Below is a description of the bandwidth monitoring mechanism. .Bl -bullet .It If the bandwidth of a data flow satisfies some pre-defined filter, the kernel delivers an upcall on the multicast routing socket to the multicast routing process that has installed that filter. .It The bandwidth-upcall filters are installed per (S,G). There can be more than one filter per (S,G). .It Instead of supporting all possible comparison operations (i.e., < <= == != > >= ), there is support only for the <= and >= operations, because this makes the kernel-level implementation simpler, and because practically we need only those two. Further, the missing operations can be simulated by secondary user-level filtering of those <= and >= filters. For example, to simulate !=, then we need to install filter .Dq bw <= 0xffffffff , and after an upcall is received, we need to check whether .Dq measured_bw != expected_bw . .It The bandwidth-upcall mechanism is enabled by setsockopt(MRT_API_CONFIG) for the MRT_MFC_BW_UPCALL flag. .It The bandwidth-upcall filters are added/deleted by the new setsockopt(MRT_ADD_BW_UPCALL) and setsockopt(MRT_DEL_BW_UPCALL) respectively (with the appropriate .Dq struct bw_upcall argument of course). .El .Pp From application point of view, a developer needs to know about the following: .Bd -literal /* * Structure for installing or delivering an upcall if the * measured bandwidth is above or below a threshold. * * User programs (e.g. daemons) may have a need to know when the * bandwidth used by some data flow is above or below some threshold. * This interface allows the userland to specify the threshold (in * bytes and/or packets) and the measurement interval. Flows are * all packet with the same source and destination IP address. * At the moment the code is only used for multicast destinations * but there is nothing that prevents its use for unicast. * * The measurement interval cannot be shorter than some Tmin (currently, 3s). * The threshold is set in packets and/or bytes per_interval. * * Measurement works as follows: * - * For >= measurements: + * For >= measurements: * The first packet marks the start of a measurement interval. * During an interval we count packets and bytes, and when we * pass the threshold we deliver an upcall and we are done. * The first packet after the end of the interval resets the * count and restarts the measurement. * * For <= measurement: * We start a timer to fire at the end of the interval, and * then for each incoming packet we count packets and bytes. * When the timer fires, we compare the value with the threshold, * schedule an upcall if we are below, and restart the measurement * (reschedule timer and zero counters). */ struct bw_data { struct timeval b_time; uint64_t b_packets; uint64_t b_bytes; }; struct bw_upcall { struct in_addr bu_src; /* source address */ struct in_addr bu_dst; /* destination address */ uint32_t bu_flags; /* misc flags (see below) */ #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */ #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */ #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */ #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */ #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/ struct bw_data bu_threshold; /* the bw threshold */ struct bw_data bu_measured; /* the measured bw */ }; /* max. number of upcalls to deliver together */ #define BW_UPCALLS_MAX 128 /* min. threshold time interval for bandwidth measurement */ #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0 .Ed .Pp The .Dq bw_upcall structure is used as an argument to setsockopt(MRT_ADD_BW_UPCALL) and setsockopt(MRT_DEL_BW_UPCALL). Each setsockopt(MRT_ADD_BW_UPCALL) installs a filter in the kernel for the source and destination address in the .Dq bw_upcall argument, and that filter will trigger an upcall according to the following pseudo-algorithm: .Bd -literal if (bw_upcall_oper IS ">=") { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets >= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes >= threshold_bytes))) SEND_UPCALL("measured bandwidth is >= threshold"); } if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets <= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes <= threshold_bytes))) SEND_UPCALL("measured bandwidth is <= threshold"); } .Ed .Pp In the same .Dq bw_upcall the unit can be specified in both BYTES and PACKETS. However, the GEQ and LEQ flags are mutually exclusive. .Pp Basically, an upcall is delivered if the measured bandwidth is >= or <= the threshold bandwidth (within the specified measurement interval). For practical reasons, the smallest value for the measurement interval is 3 seconds. If smaller values are allowed, then the bandwidth estimation may be less accurate, or the potentially very high frequency of the generated upcalls may introduce too much overhead. For the >= operation, the answer may be known before the end of .Dq threshold_interval , therefore the upcall may be delivered earlier. For the <= operation however, we must wait until the threshold interval has expired to know the answer. .Pp Example of usage: .Bd -literal struct bw_upcall bw_upcall; /* Assign all bw_upcall fields as appropriate */ memset(&bw_upcall, 0, sizeof(bw_upcall)); memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src)); memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst)); bw_upcall.bu_threshold.b_data = threshold_interval; bw_upcall.bu_threshold.b_packets = threshold_packets; bw_upcall.bu_threshold.b_bytes = threshold_bytes; if (is_threshold_in_packets) bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS; if (is_threshold_in_bytes) bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES; do { if (is_geq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_GEQ; break; } if (is_leq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_LEQ; break; } return (ERROR); } while (0); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL, (void *)&bw_upcall, sizeof(bw_upcall)); .Ed .Pp To delete a single filter, then use MRT_DEL_BW_UPCALL, and the fields of bw_upcall must be set exactly same as when MRT_ADD_BW_UPCALL was called. .Pp To delete all bandwidth filters for a given (S,G), then only the .Dq bu_src and .Dq bu_dst fields in .Dq struct bw_upcall need to be set, and then just set only the .Dq BW_UPCALL_DELETE_ALL flag inside field .Dq bw_upcall.bu_flags . .Pp The bandwidth upcalls are received by aggregating them in the new upcall message: .Bd -literal #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */ .Ed .Pp This message is an array of .Dq struct bw_upcall elements (up to BW_UPCALLS_MAX = 128). The upcalls are delivered when there are 128 pending upcalls, or when 1 second has expired since the previous upcall (whichever comes first). In an .Dq struct upcall element, the .Dq bu_measured field is filled-in to indicate the particular measured values. However, because of the way the particular intervals are measured, the user should be careful how bu_measured.b_time is used. -For example, if the +For example, if the filter is installed to trigger an upcall if the number of packets is >= 1, then .Dq bu_measured may have a value of zero in the upcalls after the first one, because the measured interval for >= filters is .Dq clocked by the forwarded packets. Hence, this upcall mechanism should not be used for measuring the exact value of the bandwidth of the forwarded data. To measure the exact bandwidth, the user would need to get the forwarded packets statistics with the ioctl(SIOCGETSGCNT) mechanism (see the .Sx Programming Guide section) . .Pp Note that the upcalls for a filter are delivered until the specific filter is deleted, but no more frequently than once per .Dq bu_threshold.b_time . For example, if the filter is specified to deliver a signal if bw >= 1 packet, the first packet will trigger a signal, but the next upcall will be triggered no earlier than .Dq bu_threshold.b_time after the previous upcall. .Pp .\" .Sh SEE ALSO .Xr getsockopt 2 , .Xr recvfrom 2 , .Xr recvmsg 2 , .Xr setsockopt 2 , .Xr socket 2 , .Xr icmp6 4 , .Xr inet 4 , .Xr inet6 4 , .Xr intro 4 , .Xr ip 4 , .Xr ip6 4 , .Xr pim 4 .\" .Pp .Sh AUTHORS The original multicast code was written by David Waitzman (BBN Labs), and later modified by the following individuals: Steve Deering (Stanford), Mark J. Steiglitz (Stanford), Van Jacobson (LBL), Ajit Thyagarajan (PARC), Bill Fenner (PARC). The IPv6 multicast support was implemented by the KAME project (http://www.kame.net), and was based on the IPv4 multicast code. The advanced multicast API and the multicast bandwidth monitoring were implemented by Pavlin Radoslavov (ICSI) in collaboration with Chris Brown (NextHop). .Pp This manual page was written by Pavlin Radoslavov (ICSI). Index: head/share/man/man4/ng_atmpif.4 =================================================================== --- head/share/man/man4/ng_atmpif.4 (revision 131471) +++ head/share/man/man4/ng_atmpif.4 (revision 131472) @@ -1,150 +1,150 @@ .\" .\" Copyright (c) 2001-2003 .\" Harti Brandt. .\" Vincent Jardin. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" Author: Hartmut Brandt .\" Author: Vincent Jardin .\" .\" $FreeBSD$ .\" .\" ng_atmpif(4) man page .\" .Dd August 7, 2003 .Dt NG_ATMPIF 4 .Os FreeBSD .Sh NAME .Nm ng_atmpif .Nd netgraph HARP/ATM Virtual Physical Interface .Sh SYNOPSIS .Fd #include .Fd #include .Sh DESCIPTION The .Nm netgraph node type allows the emulation of .Xr atm 8 -(netatm/HARP) Physical devices (PIF) to be connected to the +(netatm/HARP) Physical devices (PIF) to be connected to the .Xr netgraph 4 networking subsystem. Moreover it includes protection of the PDU against duplication and desequencement. It supports up to 65535 VCs and up to 255 VPs. AAL0, AAL3/4 and AAL5 emulation are provided. In order to optimize CPU, this node does not emulate the SAR layer. .Pp The purpose of this node is to help in debugging and testing the HARP stack when one does not have an ATM board or when the available boards do not have enough features. .Pp When a node .Nm is created, a PIF is created automatically. It is named hvaX. It has the same features as any other HARP devices. The PIF is removed when the node is removed. .Sh HOOKS There is only one hook: link. This hook can be connected to any other Netgraph node. For example, in order to test the HARP stack over UDP, it can be connected on a .Xr ksocket 4 node. .Sh CONTROL MESSAGES This node type supports the generic messages plus the following: .Bl -tag -width xxx .It Dv NGM_ATMPIF_SET_CONFIG Ta setconfig Configures the debugging features of the node and a virtual Peak Cell Rate (PCR). It uses the same structure as NGM_ATMPIF_GET_CONFIG. .It Dv NGM_ATMPIF_GET_CONFIG Ta getconfig Returns a structure defining the configuration of the interface: .Bd -literal struct ng_vatmpif_config { uint8_t debug; /* debug bit field (see below) */ uint32_t pcr; /* peak cell rate */ Mac_addr macaddr; /* Mac Address */ }; .Ed Note that the following debugging flags can be used: .Bl -column ATM_PH_LLCSNAP -offset indent .It Dv VATMPIF_DEBUG_NONE Ta disable debugging .It Dv VATMPIF_DEBUG_PACKET Ta enable debugging .El .Pp .It Dv NGM_ATMPIF_GET_LINK_STATUS Ta getlinkstatus Returns the last received sequence number, the last sent sequence number and the current total PCR that is reserved among all the VCCs of the interface. .Bd -literal struct ng_atmpif_link_status { uint32_t InSeq; /* last received sequence number + 1 */ uint32_t OutSeq; /* last sent sequence number */ uint32_t cur_pcr; /* slot's reserved PCR */ }; .Ed .Pp .It Dv NGM_ATMPIF_GET_STATS Ta getstats .It Dv NGM_ATMPIF_CLR_STATS Ta clrstats .It Dv NGM_ATMPIF_GETCLR_STATS Ta getclrstats It returns the node's statistics, it clears them or it returns and reset their values to 0. The following stats are provided. .Bd -literal struct hva_stats_ng { uint32_t ng_errseq; /* Duplicate or out of order */ uint32_t ng_lostpdu; /* PDU lost detected */ uint32_t ng_badpdu; /* Unknown PDU type */ uint32_t ng_rx_novcc; /* Draining PDU on closed VCC */ uint32_t ng_rx_iqfull; /* PDU drops no room in atm_intrq */ uint32_t ng_tx_rawcell; /* PDU raw cells transmitted */ uint32_t ng_rx_rawcell; /* PDU raw cells received */ uint64_t ng_tx_pdu; /* PDU transmitted */ uint64_t ng_rx_pdu; /* PDU received */ }; struct hva_stats_atm { uint64_t atm_xmit; /* Cells transmitted */ uint64_t atm_rcvd; /* Cells received */ }; struct hva_stats_aal5 { uint64_t aal5_xmit; /* Cells transmitted */ uint64_t aal5_rcvd; /* Cells received */ uint32_t aal5_crc_len; /* Cells with CRC/length errors */ uint32_t aal5_drops; /* Cell drops */ uint64_t aal5_pdu_xmit; /* CS PDUs transmitted */ uint64_t aal5_pdu_rcvd; /* CS PDUs received */ uint32_t aal5_pdu_crc; /* CS PDUs with CRC errors */ uint32_t aal5_pdu_errs; /* CS layer protocol errors */ uint32_t aal5_pdu_drops; /* CS PDUs dropped */ }; .Ed .El .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ksocket 4 , .Xr natm 4 , .Xr ngctl 8 .Sh AUTHORS .An Harti Brandt Aq harti@freebsd.org .An Vincent Jardin Aq vjardin@wanadoo.fr Index: head/share/man/man4/ng_sppp.4 =================================================================== --- head/share/man/man4/ng_sppp.4 (revision 131471) +++ head/share/man/man4/ng_sppp.4 (revision 131472) @@ -1,151 +1,151 @@ .\" Copyright (C) 2003-2004 Cronyx Engineering. .\" Copyright (C) 2003-2004 Roman Kurakin .\" .\" This software is distributed with NO WARRANTIES, not even the implied .\" warranties for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .\" .\" Authors grant any other persons or organisations a permission to use, .\" modify and redistribute this software in source and binary forms, .\" as long as this message is kept with the software, all derivative .\" works or modified versions. .\" .\" Cronyx Id: ng_sppp.4,v 1.1.2.3 2004/03/30 14:28:34 rik Exp $ .\" $FreeBSD$ .\" .Dd March 29, 2004 .Dt NG_SPPP 4 .Os .Sh NAME .Nm ng_sppp .Nd sppp netgraph node type .Sh SYNOPSIS .In netgraph/ng_sppp.h .Sh DESCRIPTION An .Nm ng_sppp node is a .Xr netgraph 4 interface to the original .Xr sppp 4 network module for synchronous lines. Currently .Xr sppp 4 supports PPP and Cisco HDLC protocol. An .Nm ng_sppp node could be considered as an alternative kernel mode ppp implementation to .Xr mpd ports + .Xr ng_ppp 4 and as an alternative to .Xr ng_cisco 4 node. While having less features than mpd + .Xr ng_ppp 4 , it is significantly easier to use in the majority of simple configurations and allows the administrator to not install the mpd port. With .Nm ng_sppp you don't need any other nodes, not even an .Xr ng_iface 4 node. When an .Nm ng_sppp node is created, a new interface appears which is accessible via .Xr ifconfig 8 . .Nm ng_sppp node interfaces are named .Dv sppp0 , .Dv sppp1 , etc. When a node is shutdown, the corresponding interface is removed and the interface name becomes available for reuse by future .Nm ng_sppp nodes. New nodes always take the first unused interface. The node itself is assigned the same name as its interface, unless the name already exists, in which case the node remains unnamed. The .Nm ng_sppp node allows drivers written to the old sppp interface to be rewritten using the newer more powerful .Xr netgraph 4 interface and still behave in a compatible manner without supporting both network modules. .Pp An .Nm ng_sppp node has a single hook named downstream. Usually it is connected directly to a device driver hook. .Pp .Nm ng_sppp nodes support the Berkeley Packet Filter (BPF). .Sh HOOKS This node type supports the following hooks: .Pp .Bl -tag -width abcdefghijklmnop .It Dv downstream The connection to the synchronous line. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_IFACE_GET_IFNAME Returns the name of the interface corresponding to this node in a .Dv "struct ng_iface_ifname" : .Bd -literal -offset 4n struct ng_iface_ifname { char ngif_name[NG_SPPP_IFACE_NAME_MAX + 1]; }; .Ed .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message. The associated interface is removed and becomes available for use by future .Nm ng_sppp nodes. .Pp Unlike most other node types and like .Xr ng_iface 4 does, an .Nm ng_sppp node does .Em not go away when all hooks have been disconnected; rather, and explicit .Dv NGM_SHUTDOWN control message is required. .Sh EXAMPLES For example, if you have .Xr cx 4 device, you could run PPP over it with just one command: .Pp ngctl mkpeer cx0: sppp rawdata downstream .Pp Now you have sppp0 interface (if this is a first sppp node) which can be managed via .Xr ifconfig 4 as a usual network interface, or via .Xr spppcontrol 8 as a sppp interface. .Sh SEE ALSO .Xr cx 4 , .Xr bpf 4 , .Xr sppp 4 , .Xr netgraph 4 , .Xr ng_cisco 4 , .Xr ng_iface 4 , .Xr ng_ppp 4 , .Xr ifconfig 8 , .Xr ngctl 8, .Xr spppcontrol 8 .Pp For complex networking topologies you may want to look at .Xr mpd ports . .Sh HISTORY The .Nm ng_sppp node type was implemented for .Fx 5.0 . It was included to the system since -.Fx 5.3 . +.Fx 5.3 . .Sh AUTHOR .An Copyright (C) 2003-2004 Roman Kurakin Aq rik@cronyx.ru Index: head/share/man/man4/ng_sscop.4 =================================================================== --- head/share/man/man4/ng_sscop.4 (revision 131471) +++ head/share/man/man4/ng_sscop.4 (revision 131472) @@ -1,355 +1,355 @@ .\" .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" Author: Hartmut Brandt .\" .\" $FreeBSD$ .\" .\" ng_sscop(4) man page .\" .Dd October 24, 2003 .Dt NG_SSCOP 4 .Os FreeBSD .Sh NAME .Nm ng_sscop .Nd netgraph SSCOP node type .Sh SYNOPSIS .Fd #include .Fd #include .Sh DESCIPTION The .Nm netgraph node implements the ITU-T standard Q.2110. This standard describes the so called Service Specific Connection Oriented Protocol (SSCOP) that is used to carry signalling messages over the private and public UNIs and the public NNI. This protocol is a transport protocol with selective acknowledgements and can be tailored to the environment. This implementation is a full implementation of that standard. .Pp After creation of the node, the SSCOP instance must be created by sending an enable message to the node. If the node is enabled, the SSCOP parameters can be retrieved and modified and the protocol can be started. .Pp The node is shutdown either by a .Dv NGM_SHUTDOWN message or when all hooks are disconnected. .Sh HOOKS Each .Nm node has three hooks with fixed names: .Bl -tag -width manage .It Dv lower This hook is the hook that must be connected to a node that ensures transport of packets to and from the remote peer node. Normally this is a .Xr ng_atm 4 node with an AAL5 hook, but the .Nm node is able to work on any packet-transporting layer, like, for example, IP or UDP. The node handles flow control messages received on this hook: if it receives a .Dv NGM_HIGH_WATER_PASSED message it declares the .Ql lower layer busy state. If a .Dv NGM_LOW_WATER_PASSED message is received the busy state is cleared. Note, that the node does not look at the message contents of these flow control messages. .It Dv upper This is the interface to the SSCOP user. This interface uses the following message format: .Bd -literal struct sscop_arg { uint32_t sig; uint32_t arg; /* opt. sequence number or clear-buff */ u_char data[]; }; .Ed .Pp .Fa sig is one of the signals defined in the standard: .Bd -literal enum sscop_aasig { SSCOP_ESTABLISH_request, /* <- UU, BR */ SSCOP_ESTABLISH_indication, /* -> UU */ SSCOP_ESTABLISH_response, /* <- UU, BR */ SSCOP_ESTABLISH_confirm, /* -> UU */ SSCOP_RELEASE_request, /* <- UU */ SSCOP_RELEASE_indication, /* -> UU, SRC */ SSCOP_RELEASE_confirm, /* -> */ SSCOP_DATA_request, /* <- MU */ SSCOP_DATA_indication, /* -> MU, SN */ SSCOP_UDATA_request, /* <- MU */ SSCOP_UDATA_indication, /* -> MU */ SSCOP_RECOVER_indication, /* -> */ SSCOP_RECOVER_response, /* <- */ SSCOP_RESYNC_request, /* <- UU */ SSCOP_RESYNC_indication, /* -> UU */ SSCOP_RESYNC_response, /* <- */ SSCOP_RESYNC_confirm, /* -> */ SSCOP_RETRIEVE_request, /* <- RN */ SSCOP_RETRIEVE_indication, /* -> MU */ SSCOP_RETRIEVE_COMPL_indication,/* -> */ }; .Ed .Pp The arrows in the comment show the direction of the signal whether it is a signal that comes out of the node .Ql -> or is sent by the node user to the node .Ql <- . The .Fa arg field contains the argument to some of the signals: it is either a PDU sequence number or the .Dv CLEAR-BUFFER flag. There are a number of special sequence numbers for some operations: .Bl -column SSCOP_RETRIEVE_UNKNOWN -offset indent .It Dv SSCOP_MAXSEQNO Ta maximum legal sequence number .It Dv SSCOP_RETRIEVE_UNKNOWN Ta retrieve transmission queue .It Dv SSCOP_RETRIEVE_TOTAL Ta retrieve transmission buffer and queue .El .Pp For signals that carry user data (as, for example, .Dv SSCOP_DATA_request ) these two fields are followed by the variable sized user data. .Pp If the upper hook is disconnected and the SSCOP instance is not in the idle state and the lower hook is still connected, an .Dv SSCOP_RELEASE_request is executed to release the SSCOP connection. .It Dv manage -This is the management interface defined in the standard. +This is the management interface defined in the standard. The data structure used here is: .Bd -literal struct sscop_marg { uint32_t sig; u_char data[]; }; .Ed .Pp Here .Dv sig is one of .Bd -literal enum sscop_maasig { SSCOP_MDATA_request, /* <- MU */ SSCOP_MDATA_indication, /* -> MU */ SSCOP_MERROR_indication, /* -> CODE, CNT */ }; .Ed .Pp The .Dv SSCOP_MDATA signals are followed by the actual management data, where the .Dv SSCOP_MERROR signal has the form: .Bd -literal struct sscop_merr { uint32_t sig; uint32_t err; /* error code */ uint32_t cnt; /* error count */ }; .Ed .Sh CONTROL MESSAGES The .Nm node understands the generic messages plus the following: .Bl -tag -width xxx -.It Dv NGM_SSCOP_SETPARAM +.It Dv NGM_SSCOP_SETPARAM Set operational parameters of the SSCOP instance and takes the following structure: .Bd -literal struct ng_sscop_setparam { uint32_t mask; struct sscop_param param; }; .Ed .Pp The sub-structure .Dv param contains the parameters to set and the .Dv mask field contains a bit mask, telling which of the parameters to set and which to ignore. If a bit is set, the corresponding parameter is set. The parameters are: .Bd -literal struct sscop_param { uint32_t timer_cc; /* timer_cc in msec */ uint32_t timer_poll; /* timer_poll im msec */ uint32_t timer_keep_alive;/* timer_keep_alive in msec */ uint32_t timer_no_response;/*timer_no_response in msec */ uint32_t timer_idle; /* timer_idle in msec */ uint32_t maxk; /* maximum user data in bytes */ uint32_t maxj; /* maximum u-u info in bytes */ uint32_t maxcc; /* max. retransmissions for control packets */ uint32_t maxpd; /* max. vt(pd) before sending poll */ uint32_t maxstat; /* max. number of elements in stat list */ uint32_t mr; /* initial window */ uint32_t flags; /* flags */ }; .Ed .Pp The .Dv flags field contains the following flags influencing SSCOP operation: .Bl -column SSCOP_POLLREX -offset indent .It Dv SSCOP_ROBUST Ta enable atmf/97-0216 robustness enhancement .It Dv SSCOP_POLLREX Ta send POLL after each retransmission .El .Pp The bitmap has the following bits: .Bl -column SSCOP_POLLREXx -offset indent .It Dv SSCOP_SET_TCC Ta set Dv timer_cc .It Dv SSCOP_SET_TPOLL Ta set Dv timer_poll .It Dv SSCOP_SET_TKA Ta set Dv timer_keep_alive .It Dv SSCOP_SET_TNR Ta set Dv timer_no_response .It Dv SSCOP_SET_TIDLE Ta set Dv timer_idle .It Dv SSCOP_SET_MAXK Ta set Dv maxk .It Dv SSCOP_SET_MAXJ Ta set Dv maxj .It Dv SSCOP_SET_MAXCC Ta set Dv maxcc .It Dv SSCOP_SET_MAXPD Ta set Dv maxpd .It Dv SSCOP_SET_MAXSTAT Ta set Dv maxstat .It Dv SSCOP_SET_MR Ta set the initial window .It Dv SSCOP_SET_ROBUST Ta set or clear Dv SSCOP_ROBUST .It Dv SSCOP_SET_POLLREX Ta set or clear Dv SSCOP_POLLREX .El .Pp The node responds to the .Dv NGM_SSCOP_SETPARAM message with the following response: .Bd -literal struct ng_sscop_setparam_resp { uint32_t mask; int32_t error; }; .Ed .Pp Here .Dv mask contains the a bitmask of the parameters that the user requested to set, but that could not be set and .Dv error is an .Xr errno 3 code describing why the parameter could not be set. -.It Dv NGM_SSCOP_GETPARAM +.It Dv NGM_SSCOP_GETPARAM This message returns the current operational parameters of the SSCOP instance in a .Fa sscop_param structure. -.It Dv NGM_SSCOP_ENABLE +.It Dv NGM_SSCOP_ENABLE This message creates the actual SSCOP instance and initializes it. Until this is done, parameters may neither be retrieved not set and all message received on any hook are discarded. -.It Dv NGM_SSCOP_DISABLE +.It Dv NGM_SSCOP_DISABLE Destroy the SSCOP instance. After this all messages on any hooks are discarded. .It Dv NGM_SSCOP_SETDEBUG Set debugging flags. The argument is an .Vt uint32_t . .It Dv NGM_SSCOP_GETDEBUG Retrieve the actual debugging flags. Needs no arguments and responds with an .Vt uint32_t . .It Dv NGM_SSCOP_GETSTATE Responds with the current state of the SSCOP instance in an .Vt uint32_t . If the node is not enabled the retrieved state is 0. .El .Sh FLOW CONTROL Flow control works on the upper and on the lower layer interface. At the lower layer interface the two messages .Dv NGM_HIGH_WATER_PASSED and .Dv NGM_LOW_WATER_PASSED are used to declare or clear the .Ql lower layer busy state of the protocol. .Pp At the upper layer interface the .Nm node handles three types of flow control messages: .Bl -tag -width xxx .It Dv NGM_HIGH_WATER_PASSED If this message is received the SSCOP stops moving the receive window. Each time a data message is handed over to the upper layer the receive window is moved by one message. Stopping these updates means that the window will start to close and if the peer has sent all messages allowed by the current window, it stops transmission. This means, that the upper layer must be able to receive still a full window amount of messages. .It Dv NGM_LOW_WATER_PASSED This will re-enable the automatic window updates and if the space indicated in the message is larger than the current window, the window will be opened by that amount. The space is computed as the difference of the .Fa max_queuelen_packets and .Fa current -members of the +members of the .Fa ngm_queue_state structure. .It Dv NGM_SYNC_QUEUE_STATE If the upper layer buffer filling state as indicated by .Fa current is equal too or higher than .Fa high_watermark than the message is ignored. If this is not the case the amount of receiver space is computed as the difference of .Fa max_queuelen_packets and .Fa current , if automatic window updates are currently allowed and as the difference of .Fa high_water_mark and .Fa current , if window updates are disabled. If the resulting value is larger than the current window, the current window is opened up to this value. Automatic window updates are enabled, if they were disabled. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_atm 4 , .Xr ng_sscfu 4 , .Xr ngctl 8 .Sh AUTHORS .An Harti Brandt Aq harti@freebsd.org Index: head/share/man/man4/stg.4 =================================================================== --- head/share/man/man4/stg.4 (revision 131471) +++ head/share/man/man4/stg.4 (revision 131472) @@ -1,85 +1,85 @@ .\" .\" Copyright (c) 2003 Bob Bishop .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 16, 2003 .Dt STG 4 .Os .Sh NAME .Nm stg .Nd driver for Future Domain based SCSI controllers .Sh SYNOPSIS .Cd "device stg" .Pp In .Pa /boot/device.hints (for ISA controllers): .Cd hint.stg.0.at="isa" .Sh DESCRIPTION The .Nm driver provides support for ISA, PCCARD and PCI controllers based on Future Domain SCSI controller chips including the TMC-16C30, 16C50 and 32C60. Supported controllers include: .Bl -dash -offset indent -compact .It Adaptec 2920/A .It Future Domain SCSI2GO .It Future Domain TMC-18XX/3260 .It IBM SCSI PCMCIA Card .It ICM PSC-2401 SCSI .It MELCO IFC-SC .It RATOC REX-5536, REX-5536AM, REX-5536M, REX-9836A .El .Pp -Note that the Adaptec 2920C is supported by the +Note that the Adaptec 2920C is supported by the .Sy ahc driver. .Sh SEE ALSO .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr intro 4 , .Xr sa 4 , .Xr scsi 4 .Sh HISTORY The .Nm device driver has been developed for NetBSD/pc98 and ported for .Fx . It first appeared in .Fx 2.2 with PAO and merged in .Fx 4.2 . .Sh AUTHORS The .Nm driver was written by .An Naofumi HONDA . Index: head/share/man/man7/development.7 =================================================================== --- head/share/man/man7/development.7 (revision 131471) +++ head/share/man/man7/development.7 (revision 131472) @@ -1,484 +1,484 @@ .\" Copyright (c) 1998, Matthew Dillon. Terms and conditions are those of .\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in .\" the FreeBSD source tree. .\" .\" $FreeBSD$ .\" .Dd December 21, 2002 .Dt DEVELOPMENT 7 .Os .Sh NAME .Nm development .Nd introduction to development with the FreeBSD codebase .Sh DESCRIPTION This manual page describes how an ordinary sysop, .Ux admin, or developer can, without any special permission, obtain, maintain, and modify the .Fx codebase as well as how to maintaining a master build which can then be exported to other machines in your network. This manual page is targeted to system operators, programmers, and developers. .Pp Please note that what is being described here is based on a complete FreeBSD environment, not just the FreeBSD kernel. The methods described here are as applicable to production installations as it is to development environments. You need a good 12-17GB of disk space on one machine to make this work conveniently. .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER Your master server should always run a stable, production version of the .Fx operating system. This does not prevent you from doing -CURRENT builds or development. The last thing you want to do is to run an unstable environment on your master server which could lead to a situation where you lose the environment and/or cannot recover from a mistake. .Pp Create a huge partition called /FreeBSD. 8-12GB is recommended. This partition will contain nearly all the development environment, including the CVS tree, broken-out source, and possibly even object files. You are going to export this partition to your other machines via a READ-ONLY NFS export so do not mix it with other more security-sensitive partitions. .Pp You have to make a choice in regards to .Pa /usr/obj . You can put .Pa /usr/obj in .Pa /FreeBSD or you can make .Pa /usr/obj its own partition. I recommend making it a separate partition for several reasons. First, as a safety measure since this partition is written to a great deal. Second, because you typically do not have to back it up. Third, because it makes it far easier to mix and match the development environments which are described later in this document. I recommend a .Pa /usr/obj partition of at least 5GB. .Pp On the master server, use cvsup to automatically pull down and maintain the .Fx CVS archive once a day. The first pull will take a long time, it is several gigabytes, but once you have it the daily syncs will be quite small. .Bd -literal -offset 4n mkdir /FreeBSD/FreeBSD-CVS rm -rf /home/ncvs ln -s /FreeBSD/FreeBSD-CVS /home/ncvs .Ed .Pp The cron job should look something like this (please randomize the time of day!). Note that you can use the cvsup file example directly from /usr/share/examples without modification by supplying appropriate arguments to cvsup. .Bd -literal -offset 4n 33 6 * * * /usr/local/bin/cvsup -g -r 20 -L 2 -h cvsup.freebsd.org /usr/share/examples/cvsup/cvs-supfile .Ed .Pp Run the cvsup manually the first time to pull down the archive. It could take all day depending on how fast your connection is! You will run all cvsup and cvs operations as root and you need to set up a ~/.cvsrc (/root/.cvsrc) file, as shown below, for proper cvs operation. Using ~/.cvsrc to specify cvs defaults is an excellent way to "file and forget", but you should never forget that you put them in there. .Bd -literal -offset 4n # cvs -q diff -u update -Pd checkout -P .Ed .Pp Now use cvs to checkout a -STABLE source tree and a -CURRENT source tree, as well as ports and docs, to create your initial source environment. Keeping the broken-out source and ports in /FreeBSD allows you to export it to other machines via read-only NFS. This also means you only need to edit/maintain files in one place and all your clients automatically pick up the changes. .Bd -literal -offset 4n mkdir /FreeBSD/FreeBSD-4.x mkdir /FreeBSD/FreeBSD-current cd /FreeBSD/FreeBSD-4.x cvs -d /home/ncvs checkout -rRELENG_4 src cd /FreeBSD/FreeBSD-current cvs -d /home/ncvs checkout src cvs -d /home/ncvs checkout ports cvs -d /home/ncvs checkout doc .Ed .Pp Now create a softlink for /usr/src and /usr/src2. On the main server I always point /usr/src at -STABLE and /usr/src2 at -CURRENT. On client machines I usually do not have a /usr/src2 and I make /usr/src point at whatever version of FreeBSD the client box is intended to run. .Bd -literal -offset 4n cd /usr rm -rf src src2 ln -s /FreeBSD/FreeBSD-4.x/src src (could be -CURRENT on a client) ln -s /FreeBSD/FreeBSD-current/src src2 (MASTER SERVER ONLY) .Ed .Pp Now you have to make a choice for /usr/obj. Well, hopefully you made it already and chose the partition method. If you chose poorly you probably intend to put it in /FreeBSD and, if so, this is what you want to do: .Bd -literal -offset 4n (ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /FreeBSD!) mkdir /FreeBSD/obj cd /usr rm -rf obj ln -s /FreeBSD/obj obj .Ed .Pp Alternatively you may chose simply to leave /usr/obj in /usr. If your /usr is large enough this will work, but I do not recommend it for safety reasons (/usr/obj is constantly being modified, /usr is not). .Pp Note that exporting /usr/obj via read-only NFS to your other boxes will allow you to build on your main server and install from your other boxes. If you also want to do builds on some or all of the clients you can simply have /usr/obj be a local directory on those clients. You should never export /usr/obj read-write, it will lead to all sorts of problems and issues down the line and presents a security problem as well. It is far easier to do builds on the master server and then only do installs on the clients. .Pp I usually maintain my ports tree via CVS. It is sitting right there in the master CVS archive and I've even told you to check it out (see above). With some fancy softlinks you can make the ports tree available both on your master server and on all of your other machines. Note that the ports tree exists only on the HEAD cvs branch, so its always -CURRENT even on a -STABLE box. This is what you do: .Bd -literal -offset 4n (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS) cd /usr rm -rf ports ln -s /FreeBSD/FreeBSD-current/ports ports cd /usr/ports (this pushes into the softlink) rm -rf distfiles (ON MASTER SERVER ONLY) ln -s /usr/ports.distfiles distfiles (ON MASTER SERVER ONLY) mkdir /usr/ports.distfiles mkdir /usr/ports.workdir .Ed .Pp Since /usr/ports is softlinked into what will be read-only on all of your clients, you have to tell the ports system to use a different working directory to hold ports builds. You want to add a line to your /etc/make.conf file on the master server and on all your clients: .Bd -literal -offset 4n WRKDIRPREFIX=/usr/ports.workdir .Ed .Pp You should try to make the directory you use for the ports working directory as well as the directory used to hold distfiles consistent across all of your machines. If there isn't enough room in /usr/ports.distfiles and /usr/ports.workdir I usually make those softlinks (since this is on /usr these are per-machine) to where the distfiles and working space really are. .Sh EXPORTING VIA NFS FROM THE MASTER SERVER The master server needs to export /FreeBSD and /usr/obj via NFS so all the rest of your machines can get at them. I strongly recommend using a read-only export for both security and safety. The environment I am describing in this manual page is designed primarily around read-only NFS exports. Your exports file on the master server should contain the following lines: .Bd -literal -offset 4n /FreeBSD -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK .Ed .Pp Of course, NFS server operations must also be configured on that machine. This is typically done via your /etc/rc.conf: .Bd -literal -offset 4n nfs_server_enable="YES" nfs_server_flags="-u -t -n 4" .Ed .Sh THE CLIENT ENVIRONMENT All of your client machines can import the development/build environment directory simply by NFS mounting /FreeBSD and /usr/obj from the master server. A typical /etc/fstab entry on your client machines will be something like this: .Bd -literal -offset 4n masterserver:/FreeBSD /FreeBSD nfs ro,bg 0 0 masterserver:/usr/obj /usr/obj nfs ro,bg 0 0 .Ed .Pp And, of course, you should configure the client for NFS client operations via /etc/rc.conf. In particular, this will turn on nfsiod which will improve client-side NFS performance: .Bd -literal -offset 4n nfs_client_enable="YES" .Ed .Pp Each client should create softlinks for /usr/ports and /usr/src that point into the NFS-mounted environment. If a particular client is running -CURRENT, /usr/src should be a softlink to /FreeBSD/FreeBSD-current/src. If it is running -STABLE, /usr/src should be a softlink to /FreeBSD/FreeBSD-4.x/src. I do not usually create a /usr/src2 softlink on clients, that is used as a convenient shortcut when working on the source code on the master server only and could create massive confusion (of the human variety) on a client. .Bd -literal -offset 4n (ON EACH CLIENT) cd /usr rm -rf ports src ln -s /FreeBSD/FreeBSD-current/ports ports ln -s /FreeBSD/FreeBSD-XXX/src src .Ed .Pp Don't forget to create the working directories so you can build ports, as previously described. If these are not good locations, make them softlinks to the correct location. Remember that /usr/ports/distfiles is exported by the master server and is therefore going to point to the same place (typically /usr/ports.distfiles) on every machine. .Bd -literal -offset 4n mkdir /usr/ports.distfiles mkdir /usr/ports.workdir .Ed .Sh BUILDING KERNELS Here is how you build a -STABLE kernel (on your main development box). If you want to create a custom kernel, cp GENERIC to YOURKERNEL and then edit it before configuring and building. The kernel configuration file lives in /usr/src/sys/i386/conf/KERNELNAME. .Bd -literal -offset 4n cd /usr/src make buildkernel KERNCONF=KERNELNAME .Ed .Pp .Sy WARNING! If you are familiar with the old config/cd/make method of building a -STABLE kernel, note that the config method will put the build environment in /usr/src/sys/compile/KERNELNAME instead of in /usr/obj. .Pp Building a -CURRENT kernel .Bd -literal -offset 4n cd /usr/src2 (on the master server) make buildkernel KERNCONF=KERNELNAME .Ed .Sh INSTALLING KERNELS Installing a -STABLE kernel (typically done on a client. Only do this on your main development server if you want to install a new kernel for your main development server): .Bd -literal -offset 4n cd /usr/src make installkernel KERNCONF=KERNELNAME .Ed .Pp If you are using the older config/cd/make build mechanism for stable, you would install using: .Bd -literal -offset 4n cd /usr/src/sys/compile/KERNELNAME make install .Ed .Pp Installing a -CURRENT kernel (typically done only on a client) .Bd -literal -offset 4n (remember /usr/src is pointing to the client's specific environment) cd /usr/src make installkernel KERNCONF=KERNELNAME .Ed .Pp .Sh BUILDING THE WORLD This environment is designed such that you do all builds on the master server, and then install from each client. You can do builds on a client only if /usr/obj is local to that client. Building the world is easy: .Bd -literal -offset 4n cd /usr/src make buildworld .Ed .Pp If you are on the master server you are running in a -STABLE environment, but that does not prevent you from building the -CURRENT world. Just cd into the appropriate source directory and you are set. Do not accidentally install it on your master server though! .Bd -literal -offset 4n cd /usr/src2 make buildworld .Ed .Sh INSTALLING THE WORLD You can build on your main development server and install on clients. The main development server must export /FreeBSD and /usr/obj via read-only NFS to the clients. .Pp .Em NOTE!!! If /usr/obj is a softlink on the master server, it must also be the EXACT SAME softlink on each client. If /usr/obj is a directory in /usr or a mount point on the master server, then it must be (interchangeably) a directory in /usr or a mount point on each client. This is because the absolute paths are expected to be the same when building the world as when installing it, and you generally build it on your main development box and install it from a client. If you do not setup /usr/obj properly you will not be able to build on machine and install on another. .Bd -literal -offset 4n (ON THE CLIENT) (remember /usr/src is pointing to the client's specific environment) cd /usr/src make installworld .Ed .Pp .Sy WARNING! If builds work on the master server but installs do not work from the clients, for example you try to install and the client complains that the install tried to write into the read-only /usr/obj, then it is likely that the /etc/make.conf file on the client does not match the one on the master server closely enough and the install is trying to install something that was not built. .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING) Developers often want to run buildkernel's or buildworld's on client boxes simply to life-test the box. You do this in the same manner that you buildkernel and buildworld on your master server. All you have to do is make sure that /usr/obj is pointing to local storage. If you followed my advise and made /usr/obj its own partition on the master server, then it is typically going to be an NFS mount on the client. Simply unmounting /usr/obj will leave you with a /usr/obj that is a subdirectory in /usr which is typically local to the client. You can then do builds to your heart's content! .Sh MAINTAINING A LOCAL BRANCH I have described how to maintain two versions of the source tree, a stable version in /FreeBSD/FreeBSD-4.x and a current version in /FreeBSD/FreeBSD-current. There is absolutely nothing preventing you from breaking out other versions of the source tree into /FreeBSD/XXX. In fact, my /FreeBSD partition also contains .Ox , .Nx , and various flavors of Linux. You may not necessarily be able to build non-FreeBSD operating systems on your master server, but being able to collect and manage source distributions from a central server is a very useful thing to be able to do and you can certainly export to machines which can build those other operating systems. .Pp Many developers choose to maintain a local branch of .Fx to test patches or build a custom distribution. This can be done with CVS or another source code management system (SubVersion, Perforce, BitKeeper) with its own repository. -Since the main +Since the main .Fx tree is based on CVS, the former is convenient. .Pp First, you need to modify your cvsup environment to avoid it modifying the local changes you have committed to the repository. It is important to remove the "delete" keyword from your supfile and to add the CVSROOT subdirectory to your refuse file. For more information, see .Xr cvsup 1 . .Pp The .Fx version of CVS examines a custom environmental variable, CVS_LOCAL_BRANCH_NUM, which specifies an integer to use when doing a cvs tag/rtag. Set this number to something high (say 1000) to avoid colliding with potential future branches of the main repository. For example, branching a file with version 1.4 produces 1.4.1000. Future commits to this branch will produce revisions 1.4.1000.1, 1.4.1000.2, etc. .Pp To fork your local branch, do: .Bd -literal -offset 4n cvs rtag -r RELENG_4 -b LOCAL_RELENG_4 src .Ed .Pp After this, you can check out a copy from your local repository using the new tag and begin making changes and committing them. For more information on using cvs, see .Xr cvs 1 . .Pp .Sy WARNING! The cvsup utility may blow away changes made on a local branch in some situations. This has been reported to occur when the master CVS repository is directly manipulated or an RCS file is changed. At this point, cvsup notices that the client and server have entirely different RCS files, so it does a full replace instead of trying to send just deltas. Ideally this situation should never arise, but in the real world it happens all the time. .Pp While this is the only scenario where the problem should crop up, there have been some suspicious-sounding reports of CVS_LOCAL_BRANCH_NUM lossage that can't be explained by this alone. Bottom line is, if you value your local branch then you should back it up before every update. .Sh UPDATING VIA CVS The advantage of using cvsup to maintain an updated copy of the CVS repository instead of using it to maintain source trees directly is that you can then pick and choose when you bring your source tree (or pieces of your source tree) up to date. By using a cron job to maintain an updated CVS repository, you can update your source tree at any time without any network cost as follows: .Bd -literal -offset 4n (on the main development server) cd /usr/src cvs -d /home/ncvs update cd /usr/src2 cvs -d /home/ncvs update cd /usr/ports cvs -d /home/ncvs update .Ed .Pp It is that simple, and since you are exporting the whole lot to your clients, your clients have immediately visibility into the updated source. This is a good time to also remind you that most of the cvs operations you do will be done as root, and that certain options are required for CVS to operate properly on the .Fx repository. For example, .Fl Pd is necessary when running "cvs update". These options are typically placed in your ~/.cvsrc (as already described) so you do not have to respecify them every time you run a CVS command. Maintaining the CVS repository also gives you far more flexibility in regards to breaking out multiple versions of the source tree. It is a good idea to give your /FreeBSD partition a lot of space (I recommend 8-12GB) precisely for that reason. If you can make it 15GB I would do it. .Pp I generally do not cvs update via a cron job. This is because I generally want the source to not change out from under me when I am developing code. Instead I manually update the source every so often... when I feel it is a good time. My recommendation is to only keep the cvs repository synchronized via cron. .Sh SEE ALSO .Xr crontab 1 , .Xr crontab 5 , .Xr build 7 , .Xr firewall 7 , .Xr release 7 , .Xr tuning 7 , .Xr diskless 8 .Sh HISTORY The .Nm manual page was originally written by .An Matthew Dillon Aq dillon@FreeBSD.org and first appeared in .Fx 5.0 , December 2002. Index: head/share/man/man9/taskqueue.9 =================================================================== --- head/share/man/man9/taskqueue.9 (revision 131471) +++ head/share/man/man9/taskqueue.9 (revision 131472) @@ -1,229 +1,229 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2000 Doug Rabson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 12, 2000 .Dt TASKQUEUE 9 .Os .Sh NAME .Nm taskqueue .Nd asynchronous task execution .Sh SYNOPSIS .In sys/param.h .In sys/kernel.h .In sys/malloc.h .In sys/queue.h .In sys/taskqueue.h .Bd -literal typedef void (*task_fn)(void *context, int pending); typedef void (*taskqueue_enqueue_fn)(void *context); struct task { STAILQ_ENTRY(task) ta_link; /* link for queue */ int ta_pending; /* count times queued */ int ta_priority; /* priority of task in queue */ task_fn ta_func; /* task handler */ void *ta_context; /* argument for handler */ }; .Ed .Ft struct taskqueue * .Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" .Ft void .Fn taskqueue_free "struct taskqueue *queue" .Ft struct taskqueue * .Fn taskqueue_find "const char *name" .Ft int .Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task" .Ft int .Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task" .Ft void .Fn taskqueue_run "struct taskqueue *queue" .Fn TASK_INIT "struct task *task" "int priority" "task_fn_t *func" "void *context" .Fn TASKQUEUE_DECLARE "name" .Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" .Sh DESCRIPTION These functions provide a simple interface for asynchronous execution of code. .Pp The function .Fn taskqueue_create is used to create new queues. The arguments to .Fn taskqueue_create include a name which should be unique, a set of .Xr malloc 9 flags which specify whether the call to .Fn malloc is allowed to sleep and a function which is called from .Fn taskqueue_enqueue when a task is added to the queue .\" XXX The rest of the sentence gets lots in relation to the first part. to allow the queue to arrange to be run later (for instance by scheduling a software interrupt or waking a kernel thread). .Pp The function .Fn taskqueue_free should be used to remove the queue from the global list of queues and free the memory used by the queue. Any tasks which are on the queue will be executed at this time. .Pp The system maintains a list of all queues which can be searched using .Fn taskqueue_find . The first queue whose name matches is returned, otherwise .Dv NULL . .Pp To add a task to the list of tasks queued on a taskqueue, call .Fn taskqueue_enqueue with pointers to the queue and task. If the task's .Va ta_pending field is non-zero, then it is simply incremented to reflect the number of times the task was enqueued. Otherwise, the task is added to the list before the first task which has a lower .Va ta_priority value or at the end of the list if no tasks have a lower priority. Enqueueing a task does not perform any memory allocation which makes it suitable for calling from an interrupt handler. This function will return .Er EPIPE if the queue is being freed. .Pp The function .Fn taskqueue_enqueue_fast should be used in place of .Fn taskqueue_enqueue when the enqueuing must happen from a fast interrupt handler. This method uses spin locks to avoid the possibility of sleeping in the fast interrupt context. .Pp To execute all the tasks on a queue, call .Fn taskqueue_run . When a task is executed, first it is removed from the queue, the value of .Va ta_pending is recorded and then the field is zeroed. The function .Va ta_func from the task structure is called with the value of the field .Va ta_context as its first argument and the value of .Va ta_pending as its second argument. .Pp A convenience macro, .Fn TASK_INIT "task" "priority" "func" "context" is provided to initialise a .Va task structure. The values of .Va priority , .Va func , and .Va context are simply copied into the task structure fields and the .Va ta_pending field is cleared. .Pp Two macros .Fn TASKQUEUE_DECLARE "name" and .Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" are used to declare a reference to a global queue and to define the implementation of the queue. The .Fn TASKQUEUE_DEFINE macro arranges to call .Fn taskqueue_create with the values of its .Va name , .Va enqueue and .Va context arguments during system initialisation. After calling .Fn taskqueue_create , the .Va init argument to the macro is executed as a C statement, allowing any further initialisation to be performed (such as registering an interrupt handler etc.) .Pp The system provides three global taskqueues, .Va taskqueue_swi , .Va taskqueue_swi_giant , -and +and .Va taskqueue_thread . The swi taskqueues are run via a software interrupt mechanism. The taskqueue_swi queue runs without the protection of the Giant kernel lock, and the taskqueue_swi_giant queue runs with the protection of the Giant kernel lock. The thread taskqueue runs in a kernel thread context, and tasks run from this thread do not run under the Giant kernel lock. If the caller wants to run under Giant, he should explicitly acquire and release Giant in his taskqueue handler routine. .Pp To use these queues, call .Fn taskqueue_enqueue with the value of the global taskqueue variable for the queue you wish to use ( .Va taskqueue_swi , .Va taskqueue_swi_giant , or .Va taskqueue_thread ). .Pp The software interrupt queues can be used, for instance, for implementing interrupt handlers which must perform a significant amount of processing in the handler. The hardware interrupt handler would perform minimal processing of the interrupt and then enqueue a task to finish the work. This reduces to a minimum the amount of time spent with interrupts disabled. .Pp The thread queue can be used, for instance, by interrupt level routines that need to call kernel functions that do things that can only be done from a thread context. (e.g., call malloc with the M_WAITOK flag.) .Sh HISTORY This interface first appeared in .Fx 5.0 . There is a similar facility called tqueue in the Linux kernel. .Sh AUTHORS This man page was written by .An Doug Rabson . Index: head/share/man/man9/watchdog.9 =================================================================== --- head/share/man/man9/watchdog.9 (revision 131471) +++ head/share/man/man9/watchdog.9 (revision 131472) @@ -1,66 +1,66 @@ .\" .\" Copyright (c) 2004 Poul-Henning Kamp . Berlin. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .Dd April 26, 1996 .Dt MAKEWHATIS.LOCAL 8 .Os .Sh NAME .Nm makewhatis.local , catman.local .Nd start makewhatis or catman for local file systems .Sh SYNOPSIS .Nm /usr/libexec/makewhatis.local .Op options .Ar directories ... .Nm /usr/libexec/catman.local .Op options .Ar directories ... -.Sh DESCRIPTION +.Sh DESCRIPTION The .Nm utility starts .Xr makewhatis 1 only for file systems physically mounted on the system -where the +where the .Nm is being executed. Running makewhatis -by +by .Pa periodic weekly for rw nfs-mounted /usr may kill your NFS server -- all NFS clients start makewhatis at the same time! -So use this wrapper for +So use this wrapper for .Xr cron 8 instead of calling makewhatis directly. The .Nm catman.local utility is using for same purposes as .Nm but for .Xr catman 1 . .Sh FILES .Bl -tag -width /etc/periodic/weekly/320.whatis.XXX -compact .It Pa /etc/periodic/weekly/320.whatis run .Nm every week .It Pa /etc/periodic/weekly/330.catman run .Nm catman.local every week .El .Sh SEE ALSO .Xr catman 1 , .Xr find 1 , .Xr makewhatis 1 , .Xr cron 8 , .Xr periodic 8 .Sh HISTORY The .Nm utility appeared in .Fx 2.2 . Index: head/usr.bin/sed/sed.1 =================================================================== --- head/usr.bin/sed/sed.1 (revision 131471) +++ head/usr.bin/sed/sed.1 (revision 131472) @@ -1,543 +1,543 @@ .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the Institute of Electrical and Electronics Engineers, Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 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. .\" .\" @(#)sed.1 8.2 (Berkeley) 12/30/93 .\" $FreeBSD$ .\" .Dd May 7, 2002 .Dt SED 1 .Os .Sh NAME .Nm sed .Nd stream editor .Sh SYNOPSIS .Nm .Op Fl Ean .Ar command .Op Ar .Nm .Op Fl Ean .Op Fl e Ar command .Op Fl f Ar command_file .Op Fl i Ar extension .Op Ar .Sh DESCRIPTION The .Nm utility reads the specified files, or the standard input if no files are specified, modifying the input as specified by a list of commands. The input is then written to the standard output. .Pp A single command may be specified as the first argument to .Nm . Multiple commands may be specified by using the .Fl e or .Fl f options. All commands are applied to the input in the order they are specified regardless of their origin. .Pp The following options are available: .Bl -tag -width indent .It Fl E Interpret regular expressions as extended (modern) regular expressions rather than basic regular expressions (BRE's). The .Xr re_format 7 manual page fully describes both formats. .It Fl a The files listed as parameters for the .Dq w functions are created (or truncated) before any processing begins, by default. The .Fl a option causes .Nm to delay opening each file until a command containing the related .Dq w function is applied to a line of input. .It Fl e Ar command Append the editing commands specified by the .Ar command argument to the list of commands. .It Fl f Ar command_file Append the editing commands found in the file .Ar command_file to the list of commands. The editing commands should each be listed on a separate line. .It Fl i Ar extension Edit files in-place, saving backups with the specified .Ar extension . If a zero-length .Ar extension is given, no backup will be saved. It is not recommended to give a zero-length .Ar extension when in-place editing files, as you risk corruption or partial content in situations where disk space is exhausted, etc. .It Fl n By default, each line of input is echoed to the standard output after all of the commands have been applied to it. The .Fl n option suppresses this behavior. .El .Pp The form of a .Nm command is as follows: .Pp .Dl [address[,address]]function[arguments] .Pp Whitespace may be inserted before the first address and the function portions of the command. .Pp Normally, .Nm cyclically copies a line of input, not including its terminating newline character, into a .Em "pattern space" , (unless there is something left after a .Dq D function), applies all of the commands with addresses that select that pattern space, copies the pattern space to the standard output, appending a newline, and deletes the pattern space. .Pp Some of the functions use a .Em "hold space" to save all or part of the pattern space for subsequent retrieval. .Sh "Sed Addresses" An address is not required, but if specified must be a number (that counts input lines cumulatively across input files), a dollar .Pq Dq $ character that addresses the last line of input, or a context address (which consists of a regular expression preceded and followed by a delimiter). .Pp A command line with no addresses selects every pattern space. .Pp A command line with one address selects all of the pattern spaces that match the address. .Pp A command line with two addresses selects an inclusive range. This range starts with the first pattern space that matches the first address. The end of the range is the next following pattern space that matches the second address. If the second address is a number less than or equal to the line number first selected, only that line is selected. In the case when the second address is a context -address, +address, .Nm does not re-match the second address against the pattern space that matched the first address. Starting at the first line following the selected range, .Nm starts looking again for the first address. .Pp Editing commands can be applied to non-selected pattern spaces by use of the exclamation character .Pq Dq \&! function. .Sh "Sed Regular Expressions" The regular expressions used in .Nm , by default, are basic regular expressions (BREs, see .Xr re_format 7 for more information), but extended (modern) regular expressions can be used instead if the .Fl E flag is given. In addition, .Nm has the following two additions to regular expressions: .Pp .Bl -enum -compact .It In a context address, any character other than a backslash .Pq Dq \e or newline character may be used to delimit the regular expression. Also, putting a backslash character before the delimiting character causes the character to be treated literally. For example, in the context address \exabc\exdefx, the RE delimiter is an .Dq x and the second .Dq x stands for itself, so that the regular expression is .Dq abcxdef . .Pp .It The escape sequence \en matches a newline character embedded in the pattern space. You can't, however, use a literal newline character in an address or in the substitute command. .El .Pp One special feature of .Nm regular expressions is that they can default to the last regular expression used. If a regular expression is empty, i.e. just the delimiter characters are specified, the last regular expression encountered is used instead. The last regular expression is defined as the last regular expression used as part of an address or substitute command, and at run-time, not compile-time. For example, the command .Dq /abc/s//XXX/ will substitute .Dq XXX for the pattern .Dq abc . .Sh "Sed Functions" In the following list of commands, the maximum number of permissible addresses for each command is indicated by [0addr], [1addr], or [2addr], representing zero, one, or two addresses. .Pp The argument .Em text consists of one or more lines. To embed a newline in the text, precede it with a backslash. Other backslashes in text are deleted and the following character taken literally. .Pp The .Dq r and .Dq w functions take an optional file parameter, which should be separated from the function letter by white space. Each file given as an argument to .Nm is created (or its contents truncated) before any input processing begins. .Pp The .Dq b , .Dq r , .Dq s , .Dq t , .Dq w , .Dq y , .Dq \&! , and .Dq \&: functions all accept additional arguments. The following synopses indicate which arguments have to be separated from the function letters by white space characters. .Pp Two of the functions take a function-list. This is a list of .Nm functions separated by newlines, as follows: .Bd -literal -offset indent { function function ... function } .Ed .Pp The .Dq { can be preceded by white space and can be followed by white space. The function can be preceded by white space. The terminating .Dq } must be preceded by a newline or optional white space. .Pp .Bl -tag -width "XXXXXX" -compact .It [2addr] function-list Execute function-list only when the pattern space is selected. .Pp .It [1addr]a\e .It text Write .Em text to standard output immediately before each attempt to read a line of input, whether by executing the .Dq N function or by beginning a new cycle. .Pp .It [2addr]b[label] Branch to the .Dq \&: function with the specified label. If the label is not specified, branch to the end of the script. .Pp .It [2addr]c\e .It text Delete the pattern space. With 0 or 1 address or at the end of a 2-address range, .Em text is written to the standard output. .Pp .It [2addr]d Delete the pattern space and start the next cycle. .Pp .It [2addr]D Delete the initial segment of the pattern space through the first newline character and start the next cycle. .Pp .It [2addr]g Replace the contents of the pattern space with the contents of the hold space. .Pp .It [2addr]G Append a newline character followed by the contents of the hold space to the pattern space. .Pp .It [2addr]h Replace the contents of the hold space with the contents of the pattern space. .Pp .It [2addr]H Append a newline character followed by the contents of the pattern space to the hold space. .Pp .It [1addr]i\e .It text Write .Em text to the standard output. .Pp .It [2addr]l (The letter ell.) Write the pattern space to the standard output in a visually unambiguous form. This form is as follows: .Pp .Bl -tag -width "carriage-returnXX" -offset indent -compact .It backslash \e\e .It alert \ea .It form-feed \ef .It carriage-return \er .It tab \et .It vertical tab \ev .El .Pp Nonprintable characters are written as three-digit octal numbers (with a preceding backslash) for each byte in the character (most significant byte first). Long lines are folded, with the point of folding indicated by displaying a backslash followed by a newline. The end of each line is marked with a .Dq $ . .Pp .It [2addr]n Write the pattern space to the standard output if the default output has not been suppressed, and replace the pattern space with the next line of input. .Pp .It [2addr]N Append the next line of input to the pattern space, using an embedded newline character to separate the appended material from the original contents. Note that the current line number changes. .Pp .It [2addr]p Write the pattern space to standard output. .Pp .It [2addr]P Write the pattern space, up to the first newline character to the standard output. .Pp .It [1addr]q Branch to the end of the script and quit without starting a new cycle. .Pp .It [1addr]r file Copy the contents of .Em file to the standard output immediately before the next attempt to read a line of input. If .Em file cannot be read for any reason, it is silently ignored and no error condition is set. .Pp .It [2addr]s/regular expression/replacement/flags Substitute the replacement string for the first instance of the regular expression in the pattern space. Any character other than backslash or newline can be used instead of a slash to delimit the RE and the replacement. Within the RE and the replacement, the RE delimiter itself can be used as a literal character if it is preceded by a backslash. .Pp An ampersand .Pq Dq & appearing in the replacement is replaced by the string matching the RE. The special meaning of .Dq & in this context can be suppressed by preceding it by a backslash. The string .Dq \e# , where .Dq # is a digit, is replaced by the text matched by the corresponding backreference expression (see .Xr re_format 7 ) . .Pp A line can be split by substituting a newline character into it. To specify a newline character in the replacement string, precede it with a backslash. .Pp The value of .Em flags in the substitute function is zero or more of the following: .Bl -tag -width "XXXXXX" -offset indent .It Ar N Make the substitution only for the .Ar N Ns 'th occurrence of the regular expression in the pattern space. .It g Make the substitution for all non-overlapping matches of the regular expression, not just the first one. .It p Write the pattern space to standard output if a replacement was made. If the replacement string is identical to that which it replaces, it is still considered to have been a replacement. .It w Em file Append the pattern space to .Em file if a replacement was made. If the replacement string is identical to that which it replaces, it is still considered to have been a replacement. .El .Pp .It [2addr]t [label] Branch to the .Dq \&: function bearing the label if any substitutions have been made since the most recent reading of an input line or execution of a .Dq t function. If no label is specified, branch to the end of the script. .Pp .It [2addr]w Em file Append the pattern space to the .Em file . .Pp .It [2addr]x Swap the contents of the pattern and hold spaces. .Pp .It [2addr]y/string1/string2/ Replace all occurrences of characters in .Em string1 in the pattern space with the corresponding characters from .Em string2 . Any character other than a backslash or newline can be used instead of a slash to delimit the strings. Within .Em string1 and .Em string2 , a backslash followed by any character other than a newline is that literal character, and a backslash followed by an ``n'' is replaced by a newline character. .Pp .It [2addr]!function .It [2addr]!function-list Apply the function or function-list only to the lines that are .Em not selected by the address(es). .Pp .It [0addr]:label This function does nothing; it bears a label to which the .Dq b and .Dq t commands may branch. .Pp .It [1addr]= Write the line number to the standard output followed by a newline character. .Pp .It [0addr] Empty lines are ignored. .Pp .It [0addr]# The .Dq # and the remainder of the line are ignored (treated as a comment), with the single exception that if the first two characters in the file are .Dq #n , the default output is suppressed. This is the same as specifying the .Fl n option on the command line. .El .Sh ENVIRONMENT The .Ev COLUMNS , LANG , LC_ALL , LC_CTYPE and .Ev LC_COLLATE environment variables affect the execution of .Nm as described in .Xr environ 7 . .Sh DIAGNOSTICS .Ex -std .Sh SEE ALSO .Xr awk 1 , .Xr ed 1 , .Xr grep 1 , .Xr regex 3 , .Xr re_format 7 .Sh STANDARDS The .Nm utility is expected to be a superset of the .St -p1003.2 specification. .Pp The .Fl i option is a non-standard .Fx extension and may not be available on other operating systems. .Sh HISTORY A .Nm command, written by L. E. McMahon, appeared in .At v7 . .Sh AUTHORS .An "Diomidis D. Spinellis" Aq dds@FreeBSD.org Index: head/usr.bin/systat/systat.1 =================================================================== --- head/usr.bin/systat/systat.1 (revision 131471) +++ head/usr.bin/systat/systat.1 (revision 131472) @@ -1,585 +1,585 @@ .\" Copyright (c) 1985, 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. .\" .\" @(#)systat.1 8.2 (Berkeley) 12/30/93 .\" $FreeBSD$ .\" .Dd September 9, 1997 .Dt SYSTAT 1 .Os .Sh NAME .Nm systat .Nd display system statistics on a crt .Sh SYNOPSIS .Nm .Op Fl display .Op Ar refresh-interval .Sh DESCRIPTION The .Nm utility displays various system statistics in a screen oriented fashion using the curses screen display library, .Xr ncurses 3 . .Pp While .Nm is running the screen is usually divided into two windows (an exception is the vmstat display which uses the entire screen). The upper window depicts the current system load average. The information displayed in the lower window may vary, depending on user commands. The last line on the screen is reserved for user input and error messages. .Pp By default .Nm displays the processes getting the largest percentage of the processor in the lower window. Other displays show swap space usage, disk .Tn I/O statistics (a la .Xr iostat 8 ) , virtual memory statistics (a la .Xr vmstat 8 ) , network ``mbuf'' utilization, .Tn TCP/IP statistics, and network connections (a la .Xr netstat 1 ) . .Pp Input is interpreted at two different levels. A ``global'' command interpreter processes all keyboard input. If this command interpreter fails to recognize a command, the input line is passed to a per-display command interpreter. This allows each display to have certain display-specific commands. .Pp Command line options: .Bl -tag -width "refresh_interval" .It Fl Ns Ar display The .Fl flag expects .Ar display to be one of: .Ic icmp , .Ic icmp6 , .Ic ifstat , .Ic iostat , .Ic ip , .Ic ip6 , .Ic mbufs , .Ic netstat , .Ic pigs , .Ic swap , .Ic tcp , or .Ic vmstat . These displays can also be requested interactively (without the .Dq Fl ) and are described in full detail below. .It Ar refresh-interval The .Ar refresh-value specifies the screen refresh time interval in seconds. .El .Pp Certain characters cause immediate action by .Nm . These are .Bl -tag -width Fl .It Ic \&^L Refresh the screen. .It Ic \&^G Print the name of the current ``display'' being shown in the lower window and the refresh interval. .It Ic \&: Move the cursor to the command line and interpret the input line typed as a command. While entering a command the current character erase, word erase, and line kill characters may be used. .El .Pp The following commands are interpreted by the ``global'' command interpreter. .Bl -tag -width Fl .It Ic help Print the names of the available displays on the command line. .It Ic load Print the load average over the past 1, 5, and 15 minutes on the command line. .It Ic stop Stop refreshing the screen. .It Xo .Op Ic start .Op Ar number .Xc Start (continue) refreshing the screen. If a second, numeric, argument is provided it is interpreted as a refresh interval (in seconds). Supplying only a number will set the refresh interval to this value. .It Ic quit Exit .Nm . (This may be abbreviated to .Ic q . ) .El .Pp The available displays are: .Bl -tag -width Ic .It Ic pigs Display, in the lower window, those processes resident in main memory and getting the largest portion of the processor (the default display). When less than 100% of the processor is scheduled to user processes, the remaining time is accounted to the ``idle'' process. .It Ic icmp Display, in the lower window, statistics about messages received and transmitted by the Internet Control Message Protocol .Pq Dq Tn ICMP . The left half of the screen displays information about received packets, and the right half displays information regarding transmitted packets. .Pp The .Ic icmp display understands two commands: .Ic mode and .Ic reset . The .Ic mode command is used to select one of four display modes, given as its argument: .Bl -tag -width absoluteXX -compact .It Ic rate : show the rate of change of each value in packets (the default) per second .It Ic delta : show the rate of change of each value in packets per refresh interval .It Ic since : show the total change of each value since the display was last reset .It Ic absolute : show the absolute value of each statistic .El .Pp The .Ic reset command resets the baseline for .Ic since mode. The .Ic mode command with no argument will display the current mode in the command line. .It Ic icmp6 This display is like the .Ic icmp display, but displays statistics for IPv6 ICMP. .It Ic ip Otherwise identical to the .Ic icmp display, except that it displays .Tn IP and .Tn UDP statistics. .It Ic ip6 Like the .Ic ip display, except that it displays .Tn IPv6 statics. -It does not display +It does not display .Tn UDP statistics. .It Ic tcp Like .Ic icmp , but with .Tn TCP statistics. .It Ic iostat Display, in the lower window, statistics about processor use and disk throughput. Statistics on processor use appear as bar graphs of the amount of time executing in user mode (``user''), in user mode running low priority processes (``nice''), in system mode (``system''), in interrupt mode (``interrupt''), and idle (``idle''). Statistics on disk throughput show, for each drive, megabytes per second, average number of disk transactions per second, and average kilobytes of data per transaction. This information may be displayed as bar graphs or as rows of numbers which scroll downward. Bar graphs are shown by default. .Pp The following commands are specific to the .Ic iostat display; the minimum unambiguous prefix may be supplied. .Pp .Bl -tag -width Fl -compact .It Cm numbers Show the disk .Tn I/O statistics in numeric form. Values are displayed in numeric columns which scroll downward. .It Cm bars Show the disk .Tn I/O statistics in bar graph form (default). .It Cm kbpt Toggle the display of kilobytes per transaction. (the default is to not display kilobytes per transaction). .El .It Ic swap Show information about swap space usage on all the swap areas compiled into the kernel. The first column is the device name of the partition. The next column is the total space available in the partition. The .Ar Used column indicates the total blocks used so far; the graph shows the percentage of space in use on each partition. If there are more than one swap partition in use, a total line is also shown. Areas known to the kernel, but not in use are shown as not available. .It Ic mbufs Display, in the lower window, the number of mbufs allocated for particular uses, i.e. data, socket structures, etc. .It Ic vmstat Take over the entire display and show a (rather crowded) compendium of statistics related to virtual memory usage, process scheduling, device interrupts, system name translation cacheing, disk .Tn I/O etc. .Pp The upper left quadrant of the screen shows the number of users logged in and the load average over the last one, five, and fifteen minute intervals. Below this line are statistics on memory utilization. The first row of the table reports memory usage only among active processes, that is processes that have run in the previous twenty seconds. The second row reports on memory usage of all processes. The first column reports on the number of physical pages claimed by processes. The second column reports the number of physical pages that are devoted to read only text pages. The third and fourth columns report the same two figures for virtual pages, that is the number of pages that would be needed if all processes had all of their pages. Finally the last column shows the number of physical pages on the free list. .Pp Below the memory display is a list of the average number of processes (over the last refresh interval) that are runnable (`r'), in page wait (`p'), in disk wait other than paging (`d'), sleeping (`s'), and swapped out but desiring to run (`w'). The row also shows the average number of context switches (`Csw'), traps (`Trp'; includes page faults), system calls (`Sys'), interrupts (`Int'), network software interrupts (`Sof'), and page faults (`Flt'). .Pp Below the process queue length listing is a numerical listing and a bar graph showing the amount of system (shown as `='), interrupt (shown as `+'), user (shown as `>'), nice (shown as `-'), and idle time (shown as ` '). .Pp Below the process display are statistics on name translations. It lists the number of names translated in the previous interval, the number and percentage of the translations that were handled by the system wide name translation cache, and the number and percentage of the translations that were handled by the per process name translation cache. .Pp At the bottom left is the disk usage display. It reports the number of kilobytes per transaction, transactions per second, megabytes per second and the percentage of the time the disk was busy averaged over the refresh period of the display (by default, five seconds). The system keeps statistics on most every storage device. In general, up to seven devices are displayed. The devices displayed by default are the first devices in the kernel's device list. See .Xr devstat 3 and .Xr devstat 9 for details on the devstat system. .Pp Under the date in the upper right hand quadrant are statistics on paging and swapping activity. The first two columns report the average number of pages brought in and out per second over the last refresh interval due to page faults and the paging daemon. The third and fourth columns report the average number of pages brought in and out per second over the last refresh interval due to swap requests initiated by the scheduler. The first row of the display shows the average number of disk transfers per second over the last refresh interval; the second row of the display shows the average number of pages transferred per second over the last refresh interval. .Pp Below the paging statistics is a column of lines regarding the virtual memory system which list the average number of pages copied on write (`cow'), pages zero filled on demand (`zfod'), slow (on-the-fly) zero fills percentage (`%slo-z'), pages wired down (`wire'), active pages (`act'), inactive pages (`inact'), pages on the buffer cache queue (`cache'), number of free pages (`free'), pages freed by the page daemon (`daefr'), pages freed by exiting processes (`prcfr'), pages reactivated from the free list (`react'), times the page daemon was awakened (`pdwak'), pages analyzed by the page daemon (`pdpgs'), and intransit blocking page faults (`intrn') per second over the refresh interval. .Pp At the bottom of this column are lines showing the amount of memory, in kilobytes, used for the buffer cache (`buf'), the number of dirty buffers in the buffer cache (`dirtybuf'), desired maximum size of vnode cache (`desiredvnodes') (mostly unused, except to size the name cache), number of vnodes actually allocated (`numvnodes'), and number of allocated vnodes that are free (`freevnodes'). .Pp Running down the right hand side of the display is a breakdown of the interrupts being handled by the system. At the top of the list is the total interrupts per second over the time interval. The rest of the column breaks down the total on a device by device basis. Only devices that have interrupted at least once since boot time are shown. .Pp The following commands are specific to the .Ic vmstat display; the minimum unambiguous prefix may be supplied. .Pp .Bl -tag -width Ar -compact .It Cm boot Display cumulative statistics since the system was booted. .It Cm run Display statistics as a running total from the point this command is given. .It Cm time Display statistics averaged over the refresh interval (the default). .It Cm want_fd Toggle the display of fd devices in the disk usage display. .It Cm zero Reset running statistics to zero. .El .It Ic netstat Display, in the lower window, network connections. By default, network servers awaiting requests are not displayed. Each address is displayed in the format ``host.port'', with each shown symbolically, when possible. It is possible to have addresses displayed numerically, limit the display to a set of ports, hosts, and/or protocols (the minimum unambiguous prefix may be supplied): .Pp .Bl -tag -width Ar -compact .It Cm all Toggle the displaying of server processes awaiting requests (this is the equivalent of the .Fl a flag to .Xr netstat 1 ) . .It Cm numbers Display network addresses numerically. .It Cm names Display network addresses symbolically. .It Cm proto Ar protocol Display only network connections using the indicated .Ar protocol . Supported protocols are ``tcp'', ``udp'', and ``all''. .It Cm ignore Op Ar items Do not display information about connections associated with the specified hosts or ports. Hosts and ports may be specified by name (``vangogh'', ``ftp''), or numerically. Host addresses use the Internet dot notation (``128.32.0.9''). Multiple items may be specified with a single command by separating them with spaces. .It Cm display Op Ar items Display information about the connections associated with the specified hosts or ports. As for .Ar ignore , .Op Ar items may be names or numbers. .It Cm show Op Ar ports\&|hosts Show, on the command line, the currently selected protocols, hosts, and ports. Hosts and ports which are being ignored are prefixed with a `!'. If .Ar ports or .Ar hosts is supplied as an argument to .Cm show , then only the requested information will be displayed. .It Cm reset Reset the port, host, and protocol matching mechanisms to the default (any protocol, port, or host). .El .It Ic ifstat Display the network traffic going through active interfaces on the system. Idle interfaces will not be displayed until they receive some traffic. .Pp For each interface being displayed, the current, peak and total statistics are displayed for incoming and outgoing traffic. By default, the .Ic ifstat display will automatically scale the units being used so that they are in a human-readable format. The scaling units used for the current and peak traffic columns can be altered by the .Ic scale command. .Bl -tag -width ".Cm scale Op Ar units" .It Cm scale Op Ar units Modify the scale used to display the current and peak traffic over all interfaces. The following units are recognised: kbit, kbyte, mbit, mbyte, gbit, gbyte and auto. .El .El .Pp Commands to switch between displays may be abbreviated to the minimum unambiguous prefix; for example, ``io'' for ``iostat''. Certain information may be discarded when the screen size is insufficient for display. For example, on a machine with 10 drives the .Ic iostat bar graph displays only 3 drives on a 24 line terminal. When a bar graph would overflow the allotted screen space it is truncated and the actual value is printed ``over top'' of the bar. .Pp The following commands are common to each display which shows information about disk drives. These commands are used to select a set of drives to report on, should your system have more drives configured than can normally be displayed on the screen. .Pp .Bl -tag -width Ar -compact .It Cm ignore Op Ar drives Do not display information about the drives indicated. Multiple drives may be specified, separated by spaces. .It Cm display Op Ar drives Display information about the drives indicated. Multiple drives may be specified, separated by spaces. .It Cm only Op Ar drives Display only the specified drives. Multiple drives may be specified, separated by spaces. .It Cm drives Display a list of available devices. .It Cm match Xo .Ar type , Ns Ar if , Ns Ar pass .Op | Ar ... .Xc Display devices matching the given pattern. The basic matching expressions are the same as those used in .Xr iostat 8 with one difference. Instead of specifying multiple .Fl t arguments which are then ORed together, the user instead specifies multiple matching expressions joined by the pipe .Pq Ql \&| character. The comma separated arguments within each matching expression are ANDed together, and then the pipe separated matching expressions are ORed together. Any device matching the combined expression will be displayed, if there is room to display it. For example: .Pp .Dl match da,scsi | cd,ide .Pp This will display all SCSI Direct Access devices and all IDE CDROM devices. .Pp .Dl match da | sa | cd,pass .Pp This will display all Direct Access devices, all Sequential Access devices, and all passthrough devices that provide access to CDROM drives. .El .Sh SEE ALSO .Xr netstat 1 , .Xr kvm 3 , .Xr icmp 4 , .Xr icmp6 4 , .Xr ip 4 , .Xr ip6 4 , .Xr tcp 4 , .Xr udp 4 , .Xr iostat 8 , .Xr vmstat 8 .Sh FILES .Bl -tag -width /boot/kernel/kernel -compact .It Pa /boot/kernel/kernel For the namelist. .It Pa /dev/kmem For information in main memory. .It Pa /etc/hosts For host names. .It Pa /etc/networks For network names. .It Pa /etc/services For port names. .El .Sh HISTORY The .Nm program appeared in .Bx 4.3 . The .Ic icmp , .Ic ip , and .Ic tcp displays appeared in .Fx 3.0 ; the notion of having different display modes for the .Tn ICMP , .Tn IP , .Tn TCP , and .Tn UDP statistics was stolen from the .Fl C option to .Xr netstat 1 in Silicon Graphics' .Tn IRIX system. .Sh BUGS Certain displays presume a minimum of 80 characters per line. The .Ic vmstat display looks out of place because it is (it was added in as a separate display rather than created as a new program). Index: head/usr.sbin/acpi/acpidump/acpidump.8 =================================================================== --- head/usr.sbin/acpi/acpidump/acpidump.8 (revision 131471) +++ head/usr.sbin/acpi/acpidump/acpidump.8 (revision 131472) @@ -1,190 +1,190 @@ .\" ACPI (ACPI Package) .\" .\" Copyright (c) 1999 Doug Rabson .\" Copyright (c) 2000 Mitsuru IWASAKI .\" Copyright (c) 2000 Yasuo YOKOYAMA .\" Copyright (c) 2000 Hiroki Sato .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 31, 2000 .Dt ACPIDUMP 8 .Os .Sh NAME .Nm acpidump .Nd dump ACPI tables and ASL .Sh SYNOPSIS .Nm .Op Fl d .Op Fl t .Op Fl h .Op Fl v .Op Fl f Ar dsdt_input .Op Fl o Ar dsdt_output .Sh DESCRIPTION The .Nm utility analyzes ACPI tables in physical memory and can dump them to a file. In addition, .Nm can call .Xr iasl 8 to disassemble AML (ACPI Machine Language) found in these tables and dump them as ASL (ACPI Source Language) to stdout. .Pp ACPI tables have an essential data block (the DSDT, Differentiated System Description Table) that includes information used on the kernel side such as detailed information about PnP hardware, procedures for controlling power management support, and so on. The .Nm utility can extract the DSDT data block from physical memory and store it into a DSDT output file and optionally also disassemble it. .Pp When .Nm is invoked without the .Fl f option, it will read ACPI tables from physical memory via .Pa /dev/mem . First it searches for the RSDP (Root System Description Pointer), which has the signature .Qq RSD PTR\ \& , and then gets the RSDT (Root System Description Table), which includes a list of pointers to physical memory addresses for other tables. The RSDT itself and all other tables linked from RSDT are generically called SDTs (System Description Tables) and their header has a common format which consists of items such as Signature, Length, Revision, Checksum, OEMID, OEM Table ID, OEM Revision, Creator ID and Creator Revision. When invoked with the .Fl t flag, the .Nm utility dumps contents of the following tables: .Pp .Bl -tag -offset indent -width 12345 -compact .It DSDT .It FADT .It HPET .It MADT .It RSD PTR .It RSDT .El .Pp The RSDT contains a pointer to the physical memory address of the FACP (Fixed ACPI Description Table). The FACP defines static system information about power management support (ACPI Hardware Register Implementation) such as interrupt mode (INT_MODEL), SCI interrupt number, SMI command port (SMI_CMD) and the location of ACPI registers. The FACP also has a pointer to a physical memory address for the DSDT. While the other tables are fixed format, the DSDT consists of free-formatted AML data. .Sh OPTIONS The following options are supported by .Nm : .Bl -tag -width indent .It Fl d Disassemble the DSDT into ASL using .Xr iasl 8 and print the results to stdout. .It Fl t Dump the contents of the various fixed tables listed above. .It Fl h Displays usage and exit. .It Fl v Enable verbose messages. .It Fl f Ar dsdt_input Load the DSDT from the specified file instead of physical memory. Since only the DSDT is stored in the file, the .Fl t flag may not be used with this option. .It Fl o Ar dsdt_output Store the DSDT data block from physical memory into the specified file. .El .Sh EXAMPLES This example dumps the DSDT from physical memory to foo.dsdt. It also prints the contents of various system tables and disassembles the AML contained in the DSDT to stdout, redirecting the output to foo.asl. .Bd -literal -offset indent # acpidump -t -d -o foo.dsdt > foo.asl .Ed .Pp This example reads a DSDT file and disassembles it to stdout. Verbose messages are enabled. .Bd -literal -offset indent # acpidump -v -d -f foo.dsdt .Ed .Sh BUGS In the current implementation, .Nm does not dump the -Secondary System Descriptor Table (SSDT), -Embedded Controller Descriptor Table (ECDT), +Secondary System Descriptor Table (SSDT), +Embedded Controller Descriptor Table (ECDT), or BOOT structures. .Sh FILES .Bl -tag -width /dev/mem .It Pa /dev/mem .El .Sh SEE ALSO .Xr acpi 4 , .Xr mem 4 , .Xr acpiconf 8 , .Xr acpidb 8 , .Xr iasl 8 .Sh AUTHORS .An Doug Rabson Aq dfr@FreeBSD.org .An Mitsuru IWASAKI Aq iwasaki@FreeBSD.org .An Yasuo YOKOYAMA Aq yokoyama@jp.FreeBSD.org .Pp .An -nosplit Some contributions made by .An Chitoshi Ohsawa Aq ohsawa@catv1.ccn-net.ne.jp , .An Takayasu IWANASHI Aq takayasu@wendy.a.perfect-liberty.or.jp , .An Yoshihiko SARUMARU Aq mistral@imasy.or.jp , .An Hiroki Sato Aq hrs@FreeBSD.org , .An Michael Lucas Aq mwlucas@blackhelicopters.org and .An Michael Smith Aq msmith@FreeBSD.org . .Sh HISTORY The .Nm utility first appeared in .Fx 5.0 and was rewritten to use .Xr iasl 8 for .Fx 5.2 . Index: head/usr.sbin/mixer/mixer.8 =================================================================== --- head/usr.sbin/mixer/mixer.8 (revision 131471) +++ head/usr.sbin/mixer/mixer.8 (revision 131472) @@ -1,172 +1,172 @@ .\" Copyright (c) 1997 .\" Mike Pritchard . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the author nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY MIKE PRITCHARD AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 9, 1997 .Dt MIXER 8 .Os .Sh NAME .Nm mixer .Nd set/display soundcard mixer values .Sh SYNOPSIS .Nm .Op Fl f Ar device .Op Fl s .Oo .Ar dev .Sm off .Oo .Op Cm + | - .Ar lvol .Op : Oo Cm + | - Oc Ar rvol .Oc .Oc .Sm on .Ar ... .Nm .Op Fl f Ar device .Op Fl s .Cm recsrc .Ar ... .Nm .Op Fl f Ar device .Op Fl s .Sm off .Bro .Cm ^ | + | - | = .Brc .Cm rec .Sm on .Ar rdev ... .Sh DESCRIPTION The .Nm utility is used to set and display soundcard mixer device levels. It may also be used to start and stop recording from the soundcard. The list of mixer devices that may be modified are: .Pp .Bd -ragged -offset indent vol, bass, treble, synth, pcm, speaker, mic, cd, mix, pcm2, rec, igain, ogain, line1, line2, and line3. .Ed .Pp Not all mixer devices are available. .Pp Without any arguments, .Nm displays the current settings for all supported devices, followed by information about the current recording input devices. If the .Ar dev -argument is specified, +argument is specified, .Nm displays only the value for that .Ar dev . .Pp To modify the mixer value .Ar dev , the optional left and right channel settings of .Ar lvol Ns Op : Ns Ar rvol may be specified. The .Ar lvol and .Ar rvol arguments may be from 0 - 100. Omitting .Ar dev and including only the channel settings will change the main volume level. .Pp If the left or right channel settings are prefixed with .Cm + or .Cm - , the value following will be used as a relative adjustment, modifying the current settings by the amount specified. .Pp If the .Fl s flag is used, the current mixer values will be displayed in a format suitable for use as the command-line arguments to a future invocation of .Nm (as above). .Pp To change the recording device you use one of: .Bl -tag -width =rec -offset indent .It Cm ^rec toggles .Ar rdev of possible recording devices .It Cm +rec adds .Ar rdev to possible recording devices .It Cm -rec removes .Ar rdev from possible recording devices .It Cm =rec sets the recording device to .Ar rdev .El .Pp The above commands work on an internal mask. After all the options have been parsed, it will set then read the mask from the sound card. This will let you see EXACTLY what the soundcard is using for the recording device(s). .Pp The option recsrc will display the current recording devices. .Pp The option .Fl f .Ar device will open .Ar device as the mixer device. .Sh FILES .Bl -tag -width /dev/mixer -compact .It Pa /dev/mixer the default mixer device .El .Sh SEE ALSO .Xr cdcontrol 1 .Sh HISTORY The .Nm utility first appeared in .Fx 2.0.5 . .Sh AUTHORS .An -nosplit Original source by .An Craig Metz Aq cmetz@thor.tjhsst.edu and .An Hannu Savolainen . Mostly rewritten by .An John-Mark Gurney Aq jmg@FreeBSD.org . This manual page was written by .An Mike Pritchard Aq mpp@FreeBSD.org .