From 52d13c5a78cc91537684ac9b3544e5634b031fd4 Mon Sep 17 00:00:00 2001 From: charnier Date: Sat, 6 Jul 2002 19:35:14 +0000 Subject: [PATCH] The .Nm utility. --- sbin/reboot/reboot.8 | 2 +- sbin/restore/restore.8 | 33 +++++++++++++++++------------- sbin/route/route.8 | 12 ++++++----- sbin/routed/routed.8 | 12 ++++++----- sbin/routed/rtquery/rtquery.8 | 15 ++++++++------ sbin/savecore/savecore.8 | 2 +- sbin/shutdown/shutdown.8 | 7 ++++--- sbin/slattach/slattach.8 | 16 +++++++++------ sbin/swapon/swapon.8 | 7 ++++--- sbin/sysctl/sysctl.8 | 14 ++++++++----- sbin/tunefs/tunefs.8 | 7 ++++--- sbin/umount/umount.8 | 5 ++--- sbin/vinum/vinum.8 | 38 ++++++++++++++++++++++++----------- 13 files changed, 103 insertions(+), 67 deletions(-) diff --git a/sbin/reboot/reboot.8 b/sbin/reboot/reboot.8 index 4f0000200d23..2778814219ea 100644 --- a/sbin/reboot/reboot.8 +++ b/sbin/reboot/reboot.8 @@ -142,5 +142,5 @@ specific programs. .Sh HISTORY A .Nm -command appeared in +utility appeared in .At v6 . diff --git a/sbin/restore/restore.8 b/sbin/restore/restore.8 index 21db2681e12b..d551f28a2818 100644 --- a/sbin/restore/restore.8 +++ b/sbin/restore/restore.8 @@ -85,15 +85,16 @@ is not documented here.) .Sh DESCRIPTION The .Nm -command performs the inverse function of +utility performs the inverse function of .Xr dump 8 . A full backup of a filesystem may be restored and subsequent incremental backups layered on top of it. Single files and directory subtrees may be restored from full or partial backups. -.Nm Restore -works across a network; +The +.Nm +utility works across a network; to do this see the .Fl f flag described below. @@ -144,8 +145,9 @@ those files that are not needed. .It Ic extract All the files that are on the extraction list are extracted from the dump. -.Nm Restore -will ask which volume the user wishes to mount. +The +.Nm +utility will ask which volume the user wishes to mount. The fastest way to extract a few files is to start with the last volume, and work towards the first volume. .It Ic help @@ -159,7 +161,7 @@ flag is set the inode number of each entry is also listed. .It Ic pwd Print the full pathname of the current working directory. .It Ic quit -Restore immediately exits, +Exit immediately, even if the extraction list is not empty. .It Ic setmodes All the directories that have been added to the extraction list @@ -177,13 +179,12 @@ It also causes .Nm to print out information about each file as it is extracted. .It Ic what -Displays dump header information, which includes: date, +Display dump header information, which includes: date, level, label, and the filesystem and host dump was made from. .El .It Fl R -.Nm Restore -requests a particular tape of a multi volume set on which to restart +Request a particular tape of a multi volume set on which to restart a full restore (see the .Fl r @@ -224,7 +225,9 @@ restore passes. This file should be removed when the last incremental has been restored. .Pp -.Nm Restore , +The +.Nm +utility , in conjunction with .Xr newfs 8 and @@ -353,8 +356,9 @@ Do not ask the user whether to abort the restore in the event of an error. Always try to skip over the bad block(s) and continue. .El .Sh DIAGNOSTICS +The .Nm -complains if it gets a read error. +utility complains if it gets a read error. If .Fl y has been specified, or the user responds @@ -439,8 +443,9 @@ information passed between incremental restores. .Xr newfs 8 , .Xr rmt 8 .Sh BUGS -.Nm Restore -can get confused when doing incremental restores from +The +.Nm +utility can get confused when doing incremental restores from dumps that were made on active filesystems. .Pp A level zero dump must be done after a full restore. @@ -479,5 +484,5 @@ operations shouldn't conflict with each other. .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.2 . diff --git a/sbin/route/route.8 b/sbin/route/route.8 index 069c8d9675a5..95026ea884c1 100644 --- a/sbin/route/route.8 +++ b/sbin/route/route.8 @@ -47,8 +47,9 @@ .Ar args .Oc .Sh DESCRIPTION -.Nm Route -is a utility used to manually manipulate the network +The +.Nm +utility is used to manually manipulate the network routing tables. It normally is not needed, as a system routing table management daemon such as .Xr routed 8 , @@ -337,8 +338,9 @@ If this lookup fails, .Xr getnetbyname 3 is then used to interpret the name as that of a network. .Pp -.Nm Route -uses a routing socket and the new message types +The +.Nm +utility uses a routing socket and the new message types .Dv RTM_ADD , RTM_DELETE , RTM_GET , and .Dv RTM_CHANGE . @@ -394,7 +396,7 @@ The next-hop gateway should be reachable through a different route. .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.2 . .Sh BUGS The first paragraph may have slightly exaggerated diff --git a/sbin/routed/routed.8 b/sbin/routed/routed.8 index 496d4f55ad57..dc51e9ab21dc 100644 --- a/sbin/routed/routed.8 +++ b/sbin/routed/routed.8 @@ -49,8 +49,9 @@ .Oc .Op Fl P Ar parms .Sh DESCRIPTION -.Nm Routed -is a daemon invoked at boot time to manage the network +The +.Nm +utility is a daemon invoked at boot time to manage the network routing tables. It uses Routing Information Protocol, RIPv1 (RFC\ 1058), RIPv2 (RFC\ 1723), @@ -364,8 +365,9 @@ It is better to use instead of appending the name of the trace file to the command. .Pp -.Nm Routed -also supports the notion of +The +.Nm +utility also supports the notion of "distant" .Em passive or @@ -679,5 +681,5 @@ for example, when the output side fails. .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.2 . diff --git a/sbin/routed/rtquery/rtquery.8 b/sbin/routed/rtquery/rtquery.8 index ffdba8b28617..44478fa3a10b 100644 --- a/sbin/routed/rtquery/rtquery.8 +++ b/sbin/routed/rtquery/rtquery.8 @@ -18,8 +18,9 @@ .Op Fl t Ar op .Ar host ... .Sh DESCRIPTION -.Nm Rtquery -is used to query a RIP network routing daemon, +The +.Nm +utility is used to query a RIP network routing daemon, .Xr routed 8 or .Xr gated 8 , @@ -32,8 +33,9 @@ The routing information in any routing .Em response packets returned is displayed numerically and symbolically. .Pp -.Nm Rtquery -by default uses the +The +.Nm +utility by default uses the .Em request command. When the @@ -64,8 +66,9 @@ coming from .Nm and so answers completely. .Pp -.Nm Rtquery -is also used to turn tracing on or off in +The +.Nm +utility is also used to turn tracing on or off in .Xr routed 8 . .Pp The following options are available: diff --git a/sbin/savecore/savecore.8 b/sbin/savecore/savecore.8 index 6f631323500f..f034c790e52e 100644 --- a/sbin/savecore/savecore.8 +++ b/sbin/savecore/savecore.8 @@ -134,5 +134,5 @@ The minfree code does not consider the effect of compression or sparse files. .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.1 . diff --git a/sbin/shutdown/shutdown.8 b/sbin/shutdown/shutdown.8 index 41c503ff15e8..cf15bd560153 100644 --- a/sbin/shutdown/shutdown.8 +++ b/sbin/shutdown/shutdown.8 @@ -52,8 +52,9 @@ .Ar time .Op Ar warning-message ... .Sh DESCRIPTION -.Nm Shutdown -provides an automated shutdown procedure for super-users +The +.Nm +utility provides an automated shutdown procedure for super-users to nicely notify users when the system is shutting down, saving them from system administrators, hackers, and gurus, who would otherwise not bother with such niceties. @@ -185,5 +186,5 @@ a colon (``:'') for backward compatibility. .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.0 . diff --git a/sbin/slattach/slattach.8 b/sbin/slattach/slattach.8 index 83eb98100111..d0ba8b54a950 100644 --- a/sbin/slattach/slattach.8 +++ b/sbin/slattach/slattach.8 @@ -58,8 +58,9 @@ .Op Fl S Ar unit .Ar ttyname .Sh DESCRIPTION -.Nm Slattach -is used to assign a tty line to a network interface, +The +.Nm +utility is used to assign a tty line to a network interface, and to define the network source and destination addresses. .Pp The following options are available: @@ -131,8 +132,9 @@ When is disconnected, .Ql Nm "sh -c" Ar unit-command old \-1 is run. -.Nm Slattach -will abort if the unit number +The +.Nm +utility will abort if the unit number changes and .Ql Fl u Ar \%unit-command was not specified. @@ -238,7 +240,9 @@ is a daemon). Messages indicating the specified interface does not exit, the requested address is unknown, the user is not privileged and tried to alter an interface's configuration are logged there. -.Nm Slattach +The +.Nm +utility also logs failure to set the controlling terminal or failure to install signal handlers. Upon connection and redial the ttyname and baud rate are logged and on shutdown the ttyname is logged. @@ -266,5 +270,5 @@ process and can be examined by scripts in order to send a signal to .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.3 . diff --git a/sbin/swapon/swapon.8 b/sbin/swapon/swapon.8 index ac9e018d90a8..026742751157 100644 --- a/sbin/swapon/swapon.8 +++ b/sbin/swapon/swapon.8 @@ -44,8 +44,9 @@ .Nm .Ar special_file ... .Sh DESCRIPTION -.Nm Swapon -is used to specify additional devices on which paging and swapping +The +.Nm +utility is used to specify additional devices on which paging and swapping are to take place. The system begins by swapping and paging on only a single device so that only one disk is required at bootstrap time. @@ -91,5 +92,5 @@ mounted during system operation. .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.0 . diff --git a/sbin/sysctl/sysctl.8 b/sbin/sysctl/sysctl.8 index 4e255e5fd69b..23ed92c3a97d 100644 --- a/sbin/sysctl/sysctl.8 +++ b/sbin/sysctl/sysctl.8 @@ -123,7 +123,9 @@ The information available from consists of integers, strings, devices .Pq Vt dev_t , and opaque types. -.Nm Sysctl +The +.Nm +utility only knows about a couple of opaque types, and will resort to hexdumps for the rest. The opaque information is much more useful if retrieved by special @@ -275,14 +277,16 @@ option has been deprecated and is silently ignored. .Xr sysctl 3 , .Xr sysctl.conf 5 .Sh BUGS -.Nm Sysctl -presently exploits an undocumented interface to the kernel +The +.Nm +utility presently exploits an undocumented interface to the kernel sysctl facility to traverse the sysctl tree and to retrieve format and name information. This correct interface is being thought about for the time being. .Sh HISTORY -.Nm Sysctl -first appeared in +A +.Nm +utility first appeared in .Bx 4.4 . .Pp In diff --git a/sbin/tunefs/tunefs.8 b/sbin/tunefs/tunefs.8 index 4da10b0cb9ef..7ab3665bd812 100644 --- a/sbin/tunefs/tunefs.8 +++ b/sbin/tunefs/tunefs.8 @@ -53,8 +53,9 @@ .Ek .Ar special | Ar filesystem .Sh DESCRIPTION -.Nm Tunefs -is designed to change the dynamic parameters of a filesystem +The +.Nm +utility is designed to change the dynamic parameters of a filesystem which affect the layout policies. The .Nm @@ -167,5 +168,5 @@ You can tune a filesystem, but you can't tune a fish. .Sh HISTORY The .Nm -command appeared in +utility appeared in .Bx 4.2 . diff --git a/sbin/umount/umount.8 b/sbin/umount/umount.8 index d2c8d9bb6cdf..d990f61d8148 100644 --- a/sbin/umount/umount.8 +++ b/sbin/umount/umount.8 @@ -50,8 +50,7 @@ .Sh DESCRIPTION The .Nm -command -calls the +utility calls the .Xr unmount 2 system call to remove a .Ar "special device" @@ -128,5 +127,5 @@ filesystem table .Sh HISTORY A .Nm -command appeared in +utility appeared in .At v6 . diff --git a/sbin/vinum/vinum.8 b/sbin/vinum/vinum.8 index 1f6e319910b2..119a5dfd563f 100644 --- a/sbin/vinum/vinum.8 +++ b/sbin/vinum/vinum.8 @@ -175,7 +175,7 @@ Write a copy of the current configuration to .It Ic quit Exit the .Nm -program when running in interactive mode. Normally this would be done by +utility when running in interactive mode. Normally this would be done by entering the .Dv EOF character. @@ -265,11 +265,11 @@ if no parameters are specified. Create a striped volume from the specified drives. .El .Sh DESCRIPTION +The .Nm -is a utility program to communicate with the kernel component of the Vinum +utility communicates with the kernel component of the Vinum logical volume manager. -.Nm -is designed either for interactive use, when started without command line +It is designed either for interactive use, when started without command line arguments, or to execute a single command if the command is supplied on the command line. In interactive mode, .Nm @@ -973,7 +973,7 @@ writes the list to .It Ic quit Exit the .Nm -program when running in interactive mode. Normally this would be done by +utility when running in interactive mode. Normally this would be done by entering the .Dv EOF character. @@ -986,7 +986,9 @@ command scans the specified disks for partitions containing previously created configuration information. It reads the configuration in order from the most recently updated to least recently updated configuration. +The .Nm +utility maintains an up-to-date copy of all configuration information on each disk partition. You must specify all of the slices in a configuration as the parameter to this command. @@ -1554,8 +1556,9 @@ S raid10.p1.s1 State: up PO: 279 kB Size: 573 MB In this case, the usable part of the volume is even smaller, since the first plex has shrunken to match the smallest drive. .Sh CONFIGURATION FILE +The .Nm -requires that all parameters to the +utility requires that all parameters to the .Ic create commands must be in a configuration file. Entries in the configuration file define volumes, plexes and subdisks, and may be in free format, except that each @@ -1610,7 +1613,9 @@ partition, which is reserved for the complete disk. Define the drive to be a .Dq hot spare drive, which is maintained to automatically replace a failed drive. +The .Nm +utility does not allow this drive to be used for any other purpose. In particular, it is not possible to create subdisks on it. This functionality has not been completely implemented. @@ -1637,8 +1642,9 @@ may be either .Cm round or .Cm prefer Ar plexname . +The .Nm -satisfies a read request from only one of the plexes. A +utility satisfies a read request from only one of the plexes. A .Cm round read policy specifies that each read should be performed from a different plex in @@ -1861,12 +1867,15 @@ is a swap partition, and partition .Dq Li c represents the whole disk and should not be used for any other purpose. .Pp +The .Nm +utility uses the first 265 sectors on each partition for configuration information, so the maximum size of a subdisk is 265 sectors smaller than the drive. .Sh LOG FILE +The .Nm -maintains a log file, by default +utility maintains a log file, by default .Pa /var/log/vinum_history , in which it keeps track of the commands issued to .Nm . @@ -2011,8 +2020,9 @@ filesystem is limited by the speed of the disk. By spreading the volume across multiple disks, you can increase the throughput in multi-access environments. This technique shows little or no performance improvement in single-access environments. +The .Nm -uses a technique called +utility uses a technique called .Dq striping , or sometimes RAID-0, to increase this concurrency of access. The name RAID-0 is misleading: striping does not provide any redundancy or additional reliability. @@ -2328,7 +2338,9 @@ load: 8.01 ms latency, 2 ms transfer, 10.01 ms total. It appears that some hardware RAID systems have problems with large stripes: they appear to always transfer a complete stripe to or from disk, so that a large stripe size will have an adverse effect on performance. +The .Nm +utility does not suffer from this problem: it optimizes all disk transfers and does not transfer unneeded data. .Pp @@ -2473,8 +2485,9 @@ This behaviour of is an invitation to shoot yourself in the foot: with .Nm ccd you can easily overwrite a filesystem. +The .Nm -will not permit this. +utility will not permit this. .Pp For similar reasons, the .Nm Ic start @@ -2510,8 +2523,9 @@ In practice, people aren't too interested in what was in the plex when it was created, and other volume managers cheat by setting them .Em up anyway. +The .Nm -provides two ways to ensure that newly created plexes are +utility provides two ways to ensure that newly created plexes are .Em up : .Bl -bullet .It @@ -2619,7 +2633,7 @@ The name of the editor to use for editing configuration files, by default .Sh HISTORY The .Nm -command first appeared in +utility first appeared in .Fx 3.0 . The RAID-5 component of .Nm