3614 The 'offline' and 'sparse' extended system attributes should be documented in man pages

Reviewed by: Richard Lowe <richlowe@richlowe.net>
Reviewed by: Gordon Ross <gordon.ross@nexenta.com>
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
Approved by: Dan McDonald <danmcd@omniti.com>

3 files changed, 89 insertions, 76 deletions

diff --git a/usr/src/man/man1/chmod.1 b/usr/src/man/man1/chmod.1
index b5c0ca924d..e5de56c1dc 100644
--- a/usr/src/man/man1/chmod.1
+++ b/usr/src/man/man1/chmod.1
@@ -1,4 +1,5 @@
 '\" te
+.\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
 .\" Copyright 1989 AT&T.
 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
@@ -10,7 +11,7 @@
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH CHMOD 1 "Dec 11, 2008"
+.TH CHMOD 1 "Nov 24, 2014"
 .SH NAME
 chmod \- change the permissions mode of a file
 .SH SYNOPSIS
@@ -35,7 +36,6 @@ chmod \- change the permissions mode of a file
 .fi
 
 .SH DESCRIPTION
-.sp
 .LP
 The \fBchmod\fR utility changes or assigns the mode of a file.
 .sp
@@ -44,7 +44,6 @@ The \fBchmod\fR utility changes or assigns the mode of a file.
 directories, and to modify boolean read-write system attributes on regular
 files, directories, and opaque extended attribute files.
 .SS "Absolute Mode"
-.sp
 .LP
 An absolute mode command line has the following format:
 .sp
@@ -213,7 +212,6 @@ For directories, the \fBsetgid\fR bit cannot be set (or cleared) in absolute
 mode; it must be set (or cleared) in symbolic mode using \fBg+s\fR (or
 \fBg-s\fR).
 .SS "Symbolic Mode"
-.sp
 .LP
 A symbolic mode command line has the following format:
 .sp
@@ -483,7 +481,6 @@ set.
 .RE
 
 .SS "ACL Operation"
-.sp
 .LP
 An ACL Operation command line has the following format:
 .sp
@@ -1135,7 +1132,6 @@ user:bob:read_data:allow
 .sp
 
 .SS "Attribute Operation"
-.sp
 .LP
 An attribute operation command line has the following format:
 .sp
@@ -1368,8 +1364,25 @@ The following is a list of \fBAttribute Names and Abbreviation Characters\fR:
 \fBm\fR
 .RE
 
-.SH OPTIONS
 .sp
+.ne 2
+.na
+\fB\fBoffline\fR\fR
+.ad
+.RS 18n
+\fBO\fR
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fBsparse\fR\fR
+.ad
+.RS 18n
+\fBs\fR
+.RE
+
+.SH OPTIONS
 .LP
 The following options are supported:
 .sp
@@ -1414,7 +1427,6 @@ attribute file of the file operand and the file operand itself.
 .RE
 
 .SH OPERANDS
-.sp
 .LP
 The following operands are supported:
 .sp
@@ -1479,7 +1491,6 @@ A path name of a file whose file mode bits are to be modified.
 .RE
 
 .SH USAGE
-.sp
 .LP
 See \fBlargefile\fR(5) for the description of the behavior of \fBchmod\fR when
 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
@@ -2219,7 +2230,7 @@ The following examples replace system attributes of a ZFS file:
 .nf
 $ chmod S=v{archive,hidden,readonly,system,appendonly,\e
      nonodump,immutable,noav_modified,noav_quarantined,\e
-     nounlink} file1
+     nounlink,nooffline,nosparse} file1
 .fi
 .in -2
 .sp
@@ -2243,7 +2254,7 @@ or
 .sp
 .in +2
 .nf
-$ chmod S=c{AHRSa-i--u} file1
+$ chmod S=c{AHRSa-i--u--} file1
 .fi
 .in -2
 .sp
@@ -2278,8 +2289,8 @@ Assuming appropriate privileges, this results in the following system
 attributes of \fBfile1\fR being set: \fBarchive\fR, \fBhidden\fR,
 \fBreadonly\fR, \fBsystem\fR, \fBappendonly\fR, \fBimmutable\fR, and
 \fBnounlink\fR. Assuming appropriate privileges, the following system
-attributes of \fBfile1\fR are cleared: \fBnodump\fR, \fBav_modified\fR, and
-\fBav_quarantined\fR.
+attributes of \fBfile1\fR are cleared: \fBnodump\fR, \fBav_modified\fR,
+\fBav_quarantined\fR, \fBoffline\fR, and \fBsparse\fR.
 
 .LP
 \fBExample 21 \fRClearing All System Attributes of a ZFS File
@@ -2439,7 +2450,7 @@ or
 .sp
 .in +2
 .nf
-$ chmod S+c{-HS--------} file1
+$ chmod S+c{-H-S--------} file1
 .fi
 .in -2
 .sp
@@ -2550,13 +2561,11 @@ set are also set on \fBfile2\fR. All system attributes of \fBfile1\fR that are
 cleared are also cleared on \fBfile2\fR.
 
 .SH ENVIRONMENT VARIABLES
-.sp
 .LP
 See \fBenviron\fR(5) for descriptions of the following environment variables
 that affect the execution of \fBchmod\fR: \fBLANG\fR, \fBLC_ALL\fR,
 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 .SH EXIT STATUS
-.sp
 .LP
 The following exit values are returned:
 .sp
@@ -2578,7 +2587,6 @@ An error occurred.
 .RE
 
 .SH ATTRIBUTES
-.sp
 .LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .sp
@@ -2596,13 +2604,11 @@ Interface Stability	Committed
 .TE
 
 .SH SEE ALSO
-.sp
 .LP
 \fBgetfacl\fR(1), \fBls\fR(1), \fBsetfacl\fR(1), \fBchmod\fR(2),
 \fBfgetattr\fR(3C), \fBacl\fR(5), \fBattributes\fR(5), \fBenviron\fR(5),
 \fBfsattr\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
 .SH NOTES
-.sp
 .LP
 Absolute changes do not work for the set-group-\fBID\fR bit of a directory. You
 must use \fBg+s\fR or \fBg-s\fR.
diff --git a/usr/src/man/man1/ls.1 b/usr/src/man/man1/ls.1
index 8327abc700..3990ad10bc 100644
--- a/usr/src/man/man1/ls.1
+++ b/usr/src/man/man1/ls.1
@@ -1,4 +1,5 @@
 '\" te
+.\" Copyright 2014 Nexenta Systems, Inc.  All Rights Reserved.
 .\" Copyright 1989 AT&T
 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
@@ -10,7 +11,7 @@
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH LS 1 "Jun 3, 2009"
+.TH LS 1 "Nov 24, 2014"
 .SH NAME
 ls \- list contents of directory
 .SH SYNOPSIS
@@ -39,7 +40,6 @@ ls \- list contents of directory
 .fi
 
 .SH DESCRIPTION
-.sp
 .LP
 For each \fIfile\fR that is a directory, \fBls\fR lists the contents of the
 directory. For each \fIfile\fR that is an ordinary file, \fBls\fR repeats its
@@ -177,13 +177,14 @@ looks as follows:
 .nf
 $ls -/ c  file
 -rw-r--r--   1 root     root           0 May 10 14:17 file
-                {AHRSadim-u}
+                {AHRSadim-u--}
 
 $ls -/ v file
 -rw-r--r--   1 root     root           0 May 10 14:17 file
-                {archive,hidden,readonly,system,appendonly\e
-                 nodump,immutable, av_modified,\e
-                 noav_quarantined,nounlink}
+                {archive,hidden,readonly,system,\e
+                 appendonly,nodump,immutable,av_modified,\e
+                 noav_quarantined,nounlink,nooffline,\e
+                 nosparse}
 
 $ls -l -% all file
 -rw-r--r--   1 root     root           0 May 10 14:17 file
@@ -317,7 +318,6 @@ The 1000 bit is turned on, and execution is off (undefined bit-state).
 .RE
 
 .SS "/usr/bin/ls"
-.sp
 .ne 2
 .na
 \fB\fBl\fR\fR
@@ -329,7 +329,6 @@ is on and the group execution bit is off).
 .RE
 
 .SS "/usr/xpg4/bin/ls and /usr/xpg6/bin/ls"
-.sp
 .ne 2
 .na
 \fB\fBL\fR\fR
@@ -359,7 +358,6 @@ permissions during access.
 For others permissions, the third position can be occupied by \fBt\fR or
 \fBT\fR. These refer to the state of the sticky bit and execution permissions.
 .SS "Color Output"
-.sp
 .LP
 If color output is enabled, the environment variable LS_COLORS is checked.  If
 it exists, it's contents are used to control the colors used to display
@@ -817,11 +815,9 @@ The appropriate color codes are chosen by selecting the most specific match,
 starting with the file suffixes and proceeding with the file types until a
 match is found. The \fBno\fR (normal file) type matches any file.
 .SH OPTIONS
-.sp
 .LP
 The following options are supported:
 .SS "/usr/bin/ls, /usr/xpg4/bin/ls, and /usr/xpg6/bin/ls"
-.sp
 .LP
 The following options are supported for all three versions:
 .sp
@@ -1773,7 +1769,7 @@ for files that have extended attributes.
 .sp
 .ne 2
 .na
-\fB\fB-c\fR | \fB-v\fR\fR
+\fB\fB-/ c\fR | \fBv\fR\fR
 .ad
 .sp .6
 .RS 4n
@@ -1888,6 +1884,17 @@ when attempting to unlink or rename files and directories that are marked as
 .sp
 .ne 2
 .na
+\fB\fBoffline\fR\fR
+.ad
+.sp .6
+.RS 4n
+Indicate that a file is offline.  Solaris systems have no special semantics for
+this attribute.
+.RE
+
+.sp
+.ne 2
+.na
 \fB\fBreadonly\fR\fR
 .ad
 .sp .6
@@ -1900,6 +1907,19 @@ still be modified.
 .sp
 .ne 2
 .na
+\fB\fBsparse\fR\fR
+.ad
+.sp .6
+.RS 4n
+Indicate that a file can be interpreted as sparse.  It does not indicate that
+the file is actually sparse or not.  The sparse attribute is cleared when the
+file is truncated to zero length.  Solaris systems have no other special
+semantics for this attribute.
+.RE
+
+.sp
+.ne 2
+.na
 \fB\fBsystem\fR\fR
 .ad
 .sp .6
@@ -1926,13 +1946,15 @@ immutable          i
 av_modified        m
 av_quarantined     q
 nounlink           u
+offline            O
+sparse             s
 .fi
 .in -2
 .sp
 
 .sp
 .LP
-The display in verbose mode (/ v) uses full attribute names when it is set and
+The display in verbose mode (\fB-/ v\fR) uses full attribute names when it is set and
 the name prefixed by 'no' when it is not set.
 .sp
 .LP
@@ -1949,17 +1971,19 @@ The display positions are as follows:
 .sp
 .in +2
 .nf
-{||||||||||}
- |||||||||+- u (nounlink)
- ||||||||+-- q (av_quarantined)
- |||||||+--- m (av_modified)
- ||||||+---- i (immutable)
- |||||+----- d (nodump)
- ||||+------ a (appendonly)
- |||+------- S (system)
- ||+-------- R (readonly)
- |+--------- H (hidden)
- +---------- A (archive)
+{||||||||||||}
+ |||||||||||+- s (sparse)
+ ||||||||||+-- O (offline)
+ |||||||||+--- u (nounlink)
+ ||||||||+---- q (av_quarantined)
+ |||||||+----- m (av_modified)
+ ||||||+------ i (immutable)
+ |||||+------- d (nodump)
+ ||||+-------- a (appendonly)
+ |||+--------- S (system)
+ ||+---------- R (readonly)
+ |+----------- H (hidden)
+ +------------ A (archive)
 .fi
 .in -2
 .sp
@@ -2019,9 +2043,9 @@ If extended system attributes are not supported or if the user does not have
 not set, \fBcrtime\fR is treated as a synonym for \fBmtime\fR.
 .sp
 .LP
-When option argument \fB-all\fR is specified, all available timestamps are
-printed which includes \fB-atime\fR, \fB-ctime\fR, \fB-mtime\fR and on the
-extended system attribute supporting file systems, \fB-crtime\fR (create time).
+When option argument \fBall\fR is specified, all available timestamps are
+printed which includes \fBatime\fR, \fBctime\fR, \fBmtime\fR and on the
+extended system attribute supporting file systems, \fBcrtime\fR (create time).
 The option \fB-% all\fR does not effect which timestamp is displayed in long
 format and does not affect sorting.
 .sp
@@ -2205,7 +2229,6 @@ all files.
 .RE
 
 .SS "/usr/bin/ls"
-.sp
 .ne 2
 .na
 \fB\fB-F\fR\fR
@@ -2247,7 +2270,6 @@ groups is not considered an error: \fB-C\fR and \fB-1\fR (one), \fB-H\fR and
 determines the timestamps used for sorting or in long format listings. The last
 option \fB-t\fR, \fB-S\fR, or \fB-U\fR determines the sorting behavior.
 .SS "/usr/xpg4/bin/ls"
-.sp
 .ne 2
 .na
 \fB\fB-F\fR\fR
@@ -2284,7 +2306,6 @@ option specifying a specific timestamp (\fB-c\fR, \fB-u\fR, \fB-% atime\fR ,
 used for sorting or in long format listings. The last \fB-t\fR, \fB-S\fR, or
 \fB-U\fR option determines the sorting behavior.
 .SS "/usr/xpg6/bin/ls"
-.sp
 .ne 2
 .na
 \fB\fB-F\fR\fR
@@ -2323,7 +2344,6 @@ crtime\fR, \fB-% ctime\fR, and \fB-% mtime\fR) determines the timestamps used
 for sorting or in long format listings. The last \fB-t\fR, \fB-S\fR, or
 \fB-U\fR option determines the sorting behavior.
 .SH OPERANDS
-.sp
 .LP
 The following operand is supported:
 .sp
@@ -2338,7 +2358,6 @@ diagnostic message is output on standard error.
 .RE
 
 .SH USAGE
-.sp
 .LP
 See \fBlargefile\fR(5) for the description of the behavior of \fBls\fR when
 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
@@ -2517,22 +2536,24 @@ including indirect blocks, is printed.
 .nf
 example% ls -/ c file    (extended system attribute in compact mode)
 -rw-r--r--   1 root     root           0 May 10 14:17 file
-                         {AHRSadim-u}
+                         {AHRSadim-u--}
 .fi
 .in -2
 .sp
 
 .sp
 .LP
-In this example, \fBav_quarantined\fR is not set.
+In this example, \fBav_quarantined\fR, \fBoffline\fR, and \fBsparse\fR
+are not set.
 .sp
 .in +2
 .nf
 example% ls -/ v file (extended system attribute in verbose mode)
 -rw-r--r--   1 root     root           0 May 10 14:17 file
-                {archive,hidden,readonly,system,appendonly\e
-                 nodump,immutable,av_modified,\e
-                 noav_quarantined,nounlink}
+		{archive,hidden,readonly,system,\e
+		 appendonly,nodump,immutable,av_modified,\e
+		 noav_quarantined,nounlink,nooffline,\e
+		 nosparse}
 
 example% ls -/ v file     (no extended system attribute)
 -rw-r--r--  1 root    staff        0 May 16 14:48 file
@@ -2542,7 +2563,7 @@ example% ls -/ c file        (extended system attribute
                               supported file system)
 
 -rw-r--r--  1 root staff        3 Jun  4 22:04 file
-               {A------m--}
+               {A------m----}
 .fi
 .in -2
 .sp
@@ -2557,7 +2578,7 @@ extended system attribute supported file.
 example% ls -/ c  -%crtime file
 
 -rw-r--r--    root     root          0 May 10 14:17 file
-               {AHRSadim-u}
+               {AHRSadim-u--}
 .fi
 .in -2
 .sp
@@ -2588,7 +2609,6 @@ example% ls -%crtime -tl file*
 .LP
 In this example the files are sorted by creation time.
 .SH ENVIRONMENT VARIABLES
-.sp
 .LP
 See \fBenviron\fR(5) for descriptions of the following environment variables
 that affect the execution of \fBls\fR: \fBLANG\fR, \fBLC_ALL\fR,
@@ -2634,7 +2654,6 @@ is generated regardless of the value of the --color option.
 .RE
 
 .SH EXIT STATUS
-.sp
 .ne 2
 .na
 \fB\fB0\fR\fR
@@ -2653,7 +2672,6 @@ An error occurred.
 .RE
 
 .SH FILES
-.sp
 .ne 2
 .na
 \fB\fB/etc/group\fR\fR
@@ -2684,13 +2702,10 @@ terminal information database
 .RE
 
 .SH ATTRIBUTES
-.sp
 .LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .SS "/usr/bin/ls"
-.sp
 
-.sp
 .TS
 box;
 c | c
@@ -2715,9 +2730,7 @@ For all options except \fB-A\fR, \fB-b\fR, \fB-e\fR, \fB-E,\fR \fB-h\fR,
 \fB--numeric-uid-gid\fR, \fB--reverse\fR, \fB--recursive\fR, \fB--si\fR,
 \fB--size\fR, and \fB--time-style\fR, see \fBstandards\fR(5).
 .SS "/usr/xpg4/bin/ls"
-.sp
 
-.sp
 .TS
 box;
 c | c
@@ -2742,9 +2755,7 @@ For all options except \fB-A\fR, \fB-b\fR, \fB-e\fR, \fB-E,\fR \fB-h\fR,
 \fB--numeric-uid-gid\fR, \fB--reverse\fR, \fB--recursive\fR, \fB--si\fR,
 \fB--size\fR, and \fB--time-style\fR, see \fBstandards\fR(5).
 .SS "/usr/xpg6/bin/ls"
-.sp
 
-.sp
 .TS
 box;
 c | c
@@ -2769,13 +2780,11 @@ For all options except \fB-A\fR, \fB-b\fR, \fB-e\fR, \fB-E,\fR \fB-h\fR,
 \fB--numeric-uid-gid\fR, \fB--reverse\fR, \fB--recursive\fR, \fB--si\fR,
 \fB--size\fR, and \fB--time-style\fR, see \fBstandards\fR(5).
 .SH SEE ALSO
-.sp
 .LP
 \fBchmod\fR(1), \fBcp\fR(1), \fBsetfacl\fR(1), \fBfgetattr\fR(3C),
 \fBstrftime\fR(3C), \fBterminfo\fR(4), \fBacl\fR(5), \fBattributes\fR(5),
 \fBenviron\fR(5), \fBfsattr\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
 .SH NOTES
-.sp
 .LP
 Unprintable characters in file names can confuse the columnar output options.
 .sp
diff --git a/usr/src/man/man3c/fgetattr.3c b/usr/src/man/man3c/fgetattr.3c
index efae0e0ace..7b473bada4 100644
--- a/usr/src/man/man3c/fgetattr.3c
+++ b/usr/src/man/man3c/fgetattr.3c
@@ -1,9 +1,10 @@
 '\" te
+.\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
 .\" Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH FGETATTR 3C "Aug 4, 2008"
+.TH FGETATTR 3C "Nov 24, 2014"
 .SH NAME
 fgetattr, fsetattr, getattrat, setattrat \- get and set system attributes
 .SH SYNOPSIS
@@ -35,7 +36,6 @@ fgetattr, fsetattr, getattrat, setattrat \- get and set system attributes
 .fi
 
 .SH DESCRIPTION
-.sp
 .LP
 The \fBfgetattr()\fR function obtains an nvlist of system attribute information
 about an open file object specified by the file descriptor \fIfildes\fR,
@@ -105,15 +105,15 @@ T}
 	\fBA_GROUPSID\fR	T{
 nvlist composed of \fBuint32_value\fR and \fBstring\fR
 T}
+	\fBA_OFFLINE\fR	\fBboolean_value\fR
+	\fBA_SPARSE\fR	\fBboolean_value\fR
 .TE
 
 .SH RETURN VALUES
-.sp
 .LP
 Upon successful completion, 0 is returned. Otherwise, -1  is returned and
 \fBerrno\fR is set to indicate the error.
 .SH ERRORS
-.sp
 .LP
 The \fBfgetattr()\fR, \fBgetattrat()\fR, \fBfsetattr()\fR, and
 \fBsetattrat()\fR, functions will fail if:
@@ -287,7 +287,6 @@ if (setattrat(fildes, XATTR_VIEW_READWRITE, "file", request)) {
 .in -2
 
 .SH ATTRIBUTES
-.sp
 .LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .sp
@@ -305,7 +304,6 @@ MT-Level	Safe
 .TE
 
 .SH SEE ALSO
-.sp
 .LP
 \fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2), \fBfstat\fR(2), \fBfstatat\fR(2),
 \fBopen\fR(2), \fBpipe\fR(2), \fBlibnvpair\fR(3LIB), \fBattributes\fR(5),