From 970293249bb7cb649de74d7482c48f5df2e9237c Mon Sep 17 00:00:00 2001 From: mm Date: Thu, 5 Jan 2012 11:11:46 +0000 Subject: [PATCH 34/65] MFC r228206, r228353: MFC r228206: Remove unnecesary "Ns" macros and add missing command example to zpool(8). MFC r228353: Some mdoc(7) style and typo fixes to zfs(8). Submitted by: Nobuyuki Koganemaru git-svn-id: http://svn.freebsd.org/base/stable/9@229581 ccf9f872-aa2e-dd11-9fc8-001c23d0bc1f (cherry picked from commit f0970084b1fb6e6cd4b50e6f9efcdef01b36d9cb) Signed-off-by: Xin Li --- cddl/contrib/opensolaris/cmd/zfs/zfs.8 | 81 ++++++++++--------- cddl/contrib/opensolaris/cmd/zpool/zpool.8 | 120 +++++++++++++++------------- 2 files changed, 106 insertions(+), 95 deletions(-) diff --git a/cddl/contrib/opensolaris/cmd/zfs/zfs.8 b/cddl/contrib/opensolaris/cmd/zfs/zfs.8 index c1c1197..d1793ad 100644 --- a/cddl/contrib/opensolaris/cmd/zfs/zfs.8 +++ b/cddl/contrib/opensolaris/cmd/zfs/zfs.8 @@ -377,7 +377,7 @@ property. This directory is created as needed, and automatically mounts the file system when the .Qq Nm Cm mount Fl a command is invoked (without editing -.Pa /etc/fstab Ns ). +.Pa /etc/fstab ) . The .Sy mountpoint property can be inherited, so if @@ -409,7 +409,7 @@ responsible for mounting and unmounting the file system. dataset can be attached to a jail by using the .Qq Nm Cm jail subcommand. You cannot attach a dataset to one jail and the children of the -same dataset to another jails. To allow managment of the dataset from within +same dataset to another jails. To allow management of the dataset from within a jail, the .Sy jailed property has to be set. The @@ -624,10 +624,10 @@ symbol, using one of the following forms: .Bl -bullet -offset 2n .It POSIX name (for example, -.Em joe Ns ) +.Em joe ) .It POSIX numeric ID (for example, -.Em 1001 Ns ) +.Em 1001 ) .El .It Sy userrefs This property is set to the number of user holds on this snapshot. User holds @@ -673,7 +673,7 @@ snapshot. The .Ar snapshot may be specified as a short snapshot name (just the part after the -.Sy @ Ns ), +.Sy @ ) , in which case it will be interpreted as a snapshot in the same filesystem as this dataset. The .Ar snapshot @@ -847,7 +847,7 @@ is an integer from 1 (fastest) to 9 (best compression ratio). Currently, is equivalent to .Cm gzip-6 (which is also the default for -.Xr gzip 1 Ns ). +.Xr gzip 1 ) . The .Cm zle compression algorithm compresses runs of zeros. @@ -952,7 +952,7 @@ space calculation does not include space that is used by descendent datasets, such as snapshots and clones. User space consumption is identified by the .Sy userspace@ Ns Ar user property. -.sp +.Pp Enforcement of user quotas may be delayed by several seconds. This delay means that a user might exceed their quota before the system notices that they are over quota and begins to refuse additional writes with the @@ -960,14 +960,14 @@ over quota and begins to refuse additional writes with the error message. See the .Cm userspace subcommand for more information. -.sp +.Pp Unprivileged users can only access their own groups' space usage. The root user, or a user who has been granted the .Sy userquota privilege with .Qq Nm Cm allow , can get and set everyone's quota. -.sp +.Pp This property is not available on volumes, on file systems before version 4, or on pools before version 15. The .Sy userquota@ Ns ... @@ -979,17 +979,17 @@ symbol, using one of the following forms: .Bl -bullet -offset 2n .It POSIX name (for example, -.Em joe Ns ) +.Em joe ) .It POSIX numeric ID (for example, -.Em 1001 Ns ) +.Em 1001 ) .El .It Sy groupquota@ Ns Ar group Ns = Ns Ar size | Cm none Limits the amount of space consumed by the specified group. Group space consumption is identified by the .Sy userquota@ Ns Ar user property. -.sp +.Pp Unprivileged users can access only their own groups' space usage. The root user, or a user who has been granted the .Sy groupquota @@ -1020,7 +1020,7 @@ than or equal to 128 Kbytes. Changing the file system's .Sy recordsize affects only files created afterward; existing files are unaffected. -.sp +.Pp This property can also be referred to by its shortened column name, .Sy recsize . .It Sy refquota Ns = Ns Ar size | Cm none @@ -1036,13 +1036,13 @@ The .Sy refreservation reservation is accounted for in the parent datasets' space used, and counts against the parent datasets' quotas and reservations. -.sp +.Pp If .Sy refreservation is set, a snapshot is only allowed if there is enough free pool space outside of this reservation to accommodate the current number of "referenced" bytes in the dataset. -.sp +.Pp This property can also be referred to by its shortened column name, .Sy refreserv . .It Sy reservation Ns = Ns Ar size | Cm none @@ -1161,7 +1161,7 @@ version number of 9 or higher, a is set instead. Any changes to .Sy volsize are reflected in an equivalent change to the reservation (or -.Sy refreservation Ns ). +.Sy refreservation ) . The .Sy volsize can only be set to a multiple of @@ -1174,7 +1174,7 @@ run out of space, resulting in undefined behavior or data corruption, depending on how the volume is used. These effects can also occur when the volume size is changed while it is in use (particularly when shrinking the size). Extreme care should be used when adjusting the volume size. -.sp +.Pp Though not recommended, a "sparse volume" (also known as "thin provisioning") can be created by specifying the .Fl s @@ -1708,7 +1708,7 @@ Snapshots are displayed if the property is .Cm on (the default is -.Cm off Ns ). +.Cm off ) . The following fields are displayed, .Sy name , used , available , referenced , mountpoint . .Bl -tag -width indent @@ -2168,10 +2168,10 @@ Creates a stream representation of the last argument (not part of .Fl i or -.Fl I Ns ) +.Fl I ) which is written to standard output. The output can be redirected to a file or to a different system (for example, using -.Xr ssh 1 Ns ). +.Xr ssh 1 ) . By default, a full stream is generated. .Bl -tag -width indent .It Fl i Ar snapshot @@ -2180,10 +2180,10 @@ Generate an incremental stream from the to the last .Ar snapshot . The incremental source (the -.Fl i Ar snapshot Ns ) +.Fl i Ar snapshot ) can be specified as the last component of the snapshot name (for example, the part after the -.Sy @ Ns ), +.Sy @ ) , and it is assumed to be from the same file system as the last .Ar snapshot . .Pp @@ -2191,14 +2191,16 @@ If the destination is a clone, the source may be the origin snapshot, which must be fully specified (for example, .Cm pool/fs@origin , not just -.Cm @origin Ns ). +.Cm @origin ) . .It Fl I Ar snapshot Generate a stream package that sends all intermediary snapshots from the -.Fl I Ar snapshot to the last -.Ar snapshot . For example, +.Fl I Ar snapshot +to the last +.Ar snapshot . +For example, .Ic -I @a fs@d is similar to -.Ic -i @a fs@b; -i @b fs@c; -i @c fs@d Ns . +.Ic -i @a fs@b; -i @b fs@c; -i @c fs@d . The incremental source snapshot may be specified as with the .Fl i option. @@ -2223,12 +2225,12 @@ flag is specified when this stream is received, snapshots and file systems that .It Fl D Generate a deduplicated stream. Blocks which would have been sent multiple times in the send stream will only be sent once. The receiving system must -also support this feature to recieve a deduplicated stream. This flag can +also support this feature to receive a deduplicated stream. This flag can be used regardless of the dataset's .Sy dedup property, but performance will be much better if the filesystem uses a dedup-capable checksum (eg. -.Sy sha256 Ns ). +.Sy sha256 ) . .It Fl r Recursively send all descendant snapshots. This is similar to the .Fl R @@ -2323,14 +2325,14 @@ option is specified, all but the pool name of the sent snapshot path is appended (for example, .Sy b/c@1 appended from sent snapshot -.Sy a/b/c@1 Ns ), +.Sy a/b/c@1 ) , and if the .Fl e option is specified, only the tail of the sent snapshot path is appended (for example, .Sy c@1 appended from sent snapshot -.Sy a/b/c@1 Ns ). +.Sy a/b/c@1 ) . In the case of .Fl d , any file systems needed to replicate the path of the sent snapshot are created @@ -2349,13 +2351,13 @@ Print verbose information about the stream and the time required to perform the receive operation. .It Fl n Do not actually receive the stream. This can be useful in conjunction with the -.It Fl v +.Fl v option to verify the name the receive operation would use. .It Fl F Force a rollback of the file system to the most recent snapshot before performing the receive operation. If receiving an incremental replication stream (for example, one generated by -.Qq Nm Cm send Fl R Fi iI Ns ) , +.Qq Nm Cm send Fl R Fi iI ) , destroy snapshots and file systems that do not exist on the sending side. .El .It Xo @@ -2409,12 +2411,13 @@ option. .Op Fl e .Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ... .Xc -Specifies that the permissions be delegated to "everyone." Multiple permissions +Specifies that the permissions be delegated to "everyone". +Multiple permissions may be specified as a comma-separated list. Permission names are the same as .Tn ZFS subcommand and property names. See the property list below. Property set names, which begin with an at sign -.Pq Sy @ Ns , +.Pq Sy @ , may be specified. See the .Fl s form below for details. @@ -2536,7 +2539,7 @@ commands for the specified file system and its descendents. Sets are evaluated dynamically, so changes to a set are immediately reflected. Permission sets follow the same naming restrictions as ZFS file systems, but the name must begin with an "at sign" -.Pq Sy @ Ns , +.Pq Sy @ , and can be no more than 64 characters long. .It Xo .Nm @@ -2655,7 +2658,7 @@ Describes differences between a snapshot and a successor dataset. The successor dataset can be a later snapshot or the current filesystem. .Pp The changed files are displayed including the change type. The change type -is displayed ussing a single character. If a file or directory was renamed, +is displayed useing a single character. If a file or directory was renamed, the old and the new names are displayed. .Pp The following change types can be displayed: @@ -2680,9 +2683,9 @@ The following file types can be displayed: .It \&B Ta block device .It \&@ Ta symbolic link .It \&= Ta socket -.It \&> Ta door (not supported on Fx Ns ) -.It \&| Ta FIFO (not supported on Fx Ns ) -.It \&P Ta event portal (not supported on Fx Ns ) +.It \&> Ta door (not supported on Fx ) +.It \&| Ta FIFO (not supported on Fx ) +.It \&P Ta event portal (not supported on Fx ) .El .It Fl H Machine-parseable output, fields separated a tab character. diff --git a/cddl/contrib/opensolaris/cmd/zpool/zpool.8 b/cddl/contrib/opensolaris/cmd/zpool/zpool.8 index 2148bbb..cea41bc 100644 --- a/cddl/contrib/opensolaris/cmd/zpool/zpool.8 +++ b/cddl/contrib/opensolaris/cmd/zpool/zpool.8 @@ -195,7 +195,7 @@ are supported: .Bl -tag .It Sy disk A block device, typically located under -.Pa /dev Ns . +.Pa /dev . .Tn ZFS can use individual slices or partitions, though the recommended mode of operation is to use whole disks. A disk can be specified by a full path to the @@ -221,13 +221,14 @@ bytes and can withstand .Pq Em N-1 devices failing before data integrity is compromised. .It Sy raidz -.No ( or Sy raidz1 raidz2 raidz3 Ns ). +(or +.Sy raidz1 raidz2 raidz3 ) . A variation on .Sy RAID-5 that allows for better distribution of parity and eliminates the -.Qq Sy RAID-5 No write hole -(in which data and parity become inconsistent after a power loss). Data and -parity is striped across all disks within a +.Qq Sy RAID-5 +write hole (in which data and parity become inconsistent after a power loss). +Data and parity is striped across all disks within a .No raidz group. .Pp @@ -251,7 +252,7 @@ type specifies a triple-parity group. The .Sy raidz No vdev type is an alias for -.Sy raidz1 Ns . +.Sy raidz1 . .Pp A .No raidz @@ -322,6 +323,9 @@ are used to distinguish where a group ends and another begins. For example, the following creates two root .No vdev Ns s, each a mirror of two disks: +.Bd -literal -offset 2n +.Li # Ic zpool create mypool mirror da0 da1 mirror da2 da3 +.Ed .Ss Device Failure and Recovery .Tn ZFS supports a rich set of mechanisms for handling device failure and data @@ -421,7 +425,7 @@ hardware-dependent and might not be supported on all platforms. .Ss Hot Spares .Tn ZFS allows devices to be associated with pools as -.Qq hot spares Ns . +.Qq hot spares . These devices are not actively used in the pool, but when an active device fails, it is automatically replaced by a hot spare. To create a pool with hot spares, specify a @@ -537,12 +541,13 @@ Number of blocks within the pool that are not allocated. A unique identifier for the pool. .It Sy health The current health of the pool. Health can be -.Qq Sy ONLINE Ns , -.Qq Sy DEGRADED Ns , -.Qq Sy FAULTED Ns , -.Qq Sy OFFLINE Ns , -.Qq Sy REMOVED Ns , or -.Qq Sy UNAVAIL Ns . +.Qq Sy ONLINE , +.Qq Sy DEGRADED , +.Qq Sy FAULTED , +.Qq Sy OFFLINE , +.Qq Sy REMOVED , +or +.Qq Sy UNAVAIL . .It Sy size Total size of the storage pool. .It Sy used @@ -577,7 +582,7 @@ is not a persistent property. It is valid only while the system is up. Setting .Sy altroot defaults to using -.Cm cachefile=none Ns , +.Cm cachefile=none , though this may be overridden using an explicit setting. .El .Pp @@ -585,7 +590,7 @@ The following property can only be set at import time: .Bl -tag -width 2n .It Sy readonly Ns = Ns Cm on No | Cm off If set to -.Cm on Ns , +.Cm on , pool will be imported in read-only mode with the following restrictions: .Bl -bullet -offset 2n .It @@ -606,7 +611,7 @@ command: .Bl -tag -width 2n .It Sy autoexpand Ns = Ns Cm on No | Cm off Controls automatic pool expansion when the underlying LUN is grown. If set to -.Qq Cm on Ns , +.Qq Cm on , the pool will be resized according to the size of the expanded device. If the device is part of a mirror or .No raidz @@ -614,20 +619,20 @@ then all devices within that .No mirror/ Ns No raidz group must be expanded before the new space is made available to the pool. The default behavior is -.Qq off Ns . +.Qq off . This property can also be referred to by its shortened column name, -.Sy expand Ns . +.Sy expand . .It Sy autoreplace Ns = Ns Cm on No | Cm off Controls automatic device replacement. If set to -.Qq Cm off Ns , +.Qq Cm off , device replacement must be initiated by the administrator by using the .Qq Nm Cm replace command. If set to -.Qq Cm on Ns , +.Qq Cm on , any new device, found in the same physical location as a device that previously belonged to the pool, is automatically formatted and replaced. The default behavior is -.Qq Cm off Ns . +.Qq Cm off . This property can also be referred to by its shortened column name, "replace". .It Sy bootfs Ns = Ns Ar pool Ns / Ns Ar dataset Identifies the default bootable dataset for the root pool. This property is @@ -650,7 +655,7 @@ creates a temporary pool that is never cached, and the special value Threshold for the number of block ditto copies. If the reference count for a deduplicated block increases above this number, a new ditto copy of this block is automatically stored. Deafult setting is -.Cm 0 Ns . +.Cm 0 . .It Sy delegation Ns = Ns Cm on No | Cm off Controls whether a non-privileged user is granted access based on the dataset permissions defined on the dataset. See @@ -694,7 +699,7 @@ decreased. The preferred method of updating pools is with the command, though this property can be used when a specific version is needed for backwards compatibility. This property can be any number between 1 and the current version reported by -.Qo Ic zpool upgrade -v Qc Ns . +.Qo Ic zpool upgrade -v Qc . .El .Sh SUBCOMMANDS All subcommands that modify state are logged persistently to the pool in their @@ -731,7 +736,7 @@ subcommand. .Bl -tag -width indent .It Fl f Forces use of -.Ar vdev Ns , +.Ar vdev , even if they appear in use or specify a conflicting replication level. Not all devices can be overridden in this manner. .It Fl n @@ -762,7 +767,8 @@ configuration. If is not currently part of a mirrored configuration, .Ar device automatically transforms into a two-way mirror of -.Ar device No and Ar new_device Ns . If +.Ar device No and Ar new_device . +If .Ar device is part of a two-way mirror, attaching .Ar new_device @@ -772,7 +778,7 @@ begins to resilver immediately. .Bl -tag -width indent .It Fl f Forces use of -.Ar new_device Ns , +.Ar new_device , even if its appears to be in use. Not all devices can be overridden in this manner. .El @@ -846,7 +852,7 @@ is specified. Unless the .Fl R option is specified, the default mount point is -.Qq Pa /pool Ns . +.Qq Pa /pool . The mount point must not exist or must be empty, or else the root dataset cannot be mounted. This can be overridden with the .Fl m @@ -890,9 +896,11 @@ or if .Sy altroot is specified. The mount point must be an absolute path, -.Qq Cm legacy Ns , or Qq Cm none Ns . +.Qq Cm legacy , +or +.Qq Cm none . For more information on dataset mount points, see -.Xr zfs 8 Ns \&. +.Xr zfs 8 . .El .It Xo .Nm @@ -1000,7 +1008,7 @@ performed. Lists pools available to import. If the .Fl d option is not specified, this command searches for devices in -.Qq Pa /dev Ns . +.Qq Pa /dev . The .Fl d option can be specified multiple times, and all directories are searched. If @@ -1028,7 +1036,7 @@ pool property. This is used instead of searching for devices. .It Fl d Ar dir Searches for devices or files in -.Ar dir Ns . +.Ar dir . The .Fl d option can be specified multiple times. @@ -1078,7 +1086,7 @@ pool property. This is used instead of searching for devices. .It Fl d Ar dir Searches for devices or files in -.Ar dir Ns . +.Ar dir . The .Fl d option can be specified multiple times. This option is incompatible with the @@ -1141,7 +1149,7 @@ Imports a specific pool. A pool can be identified by its name or the numeric identifier. If .Ar newpool is specified, the pool is imported using the name -.Ar newpool Ns . +.Ar newpool . Otherwise, it is imported with the same name as its exported name. .Pp If a device is removed from a system without running @@ -1171,7 +1179,7 @@ pool property. This is used instead of searching for devices. .It Fl d Ar dir Searches for devices or files in -.Ar dir Ns . +.Ar dir . The .Fl d option can be specified multiple times. This option is incompatible with the @@ -1236,11 +1244,11 @@ Print a timestamp. Use modifier .Cm d for standard date format. See -.Xr date 1 Ns . +.Xr date 1 . Use modifier .Cm u for unixtime -.Pq equals Qq Ic date +%s Ns . +.Pq equals Qq Ic date +%s . .It Fl v Verbose statistics. Reports usage statistics for individual .No vdev Ns s @@ -1256,7 +1264,7 @@ within the pool, in addition to the pool-wide statistics. Removes .Tn ZFS label information from the specified -.Ar device Ns . +.Ar device . The .Ar device must not be part of an active pool configuration. @@ -1295,24 +1303,24 @@ instead of arbitrary space. Comma-separated list of properties to display. See the .Qq Sx Properties section for a list of valid properties. The default list is -.Sy name Ns , -.Sy size Ns , -.Sy used Ns , -.Sy available Ns , -.Sy capacity Ns , -.Sy health Ns , -.Sy altroot Ns . +.Sy name , +.Sy size , +.Sy used , +.Sy available , +.Sy capacity , +.Sy health , +.Sy altroot . .It Fl T Cm d Ns | Ns Cm u Print a timestamp. .Pp Use modifier .Cm d for standard date format. See -.Xr date 1 Ns . +.Xr date 1 . Use modifier .Cm u for unixtime -.Pq equals Qq Ic date +%s Ns . +.Pq equals Qq Ic date +%s . .El .It Xo .Nm @@ -1380,11 +1388,11 @@ devices cannot be removed from a pool. Replaces .Ar old_device with -.Ar new_device Ns . +.Ar new_device . This is equivalent to attaching -.Ar new_device Ns , +.Ar new_device , waiting for it to resilver, and then detaching -.Ar old_device Ns . +.Ar old_device . .Pp The size of .Ar new_device @@ -1397,7 +1405,7 @@ configuration. is required if the pool is not redundant. If .Ar new_device is not specified, it defaults to -.Ar old_device Ns . +.Ar old_device . This form of replacement is useful after an existing disk has failed and has been physically replaced. In this case, the new disk may have the same .Pa /dev @@ -1407,7 +1415,7 @@ recognizes this. .Bl -tag -width indent .It Fl f Forces use of -.Ar new_device Ns , +.Ar new_device , even if its appears to be in use. Not all devices can be overridden in this manner. .El @@ -1420,7 +1428,7 @@ manner. .Pp Begins a scrub. The scrub examines all data in the specified pools to verify that it checksums correctly. For replicated (mirror or -.No raidz Ns ) +.No raidz ) devices, .Tn ZFS automatically repairs any damage discovered during the scrub. The @@ -1565,11 +1573,11 @@ Print a timestamp. Use modifier .Cm d for standard date format. See -.Xr date 1 Ns . +.Xr date 1 . Use modifier .Cm u for unixtime -.Pq equals Qq Ic date +%s Ns . +.Pq equals Qq Ic date +%s . .El .It Xo .Nm @@ -1649,7 +1657,7 @@ recommended, a pool based on files can be useful for experimental purposes. .It Sy Example 5 No Adding a Mirror to a Tn ZFS No Storage Pool .Pp The following command adds two mirrored disks to the pool -.Em tank Ns , +.Em tank , assuming the pool is already made up of two-way mirrors. The additional space is immediately available to any datasets within the pool. .Bd -literal -offset 2n @@ -1793,7 +1801,7 @@ subcommand as follows: .It Sy Example 15 No Removing a Mirrored Log Device .Pp The following command removes the mirrored log device -.Em mirror-2 Ns . +.Em mirror-2 . .Pp Given this configuration: .Bd -literal -offset 2n -- 1.7.8.3