tar/tar-1.26-docu-xattrs.patch

diff --git a/doc/tar.texi b/doc/tar.texi
index d678db9..ab8a0c8 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -162,6 +163,7 @@ How to Create Archives
 How to List Archives
 
 * list dir::
+* List Extended Attributes::
 
 How to Extract Members from an Archive
 
@@ -1492,6 +1494,7 @@ for a detailed discussion of globbing patterns and related
 
 @menu
 * list dir::
+* List Extended Attributes::
 @end menu
 
 @node list dir
@@ -1522,6 +1525,116 @@ drwxrwxrwx myself/user       0 1990-05-31 21:49 practice/
 When you use a directory name as a file name argument, @command{tar} acts on
 all the files (including sub-directories) in that directory.
 
+@node List Extended Attributes
+@unnumberedsubsec Listing xattrs, POSIX ACLs and SELinux context
+
+From upstream GNU tar 1.26.9, tar is able to store, extract and list extended
+file attributes.  Listing of those attributes is then active only in verbose and
+double-verbose mode.
+
+This section exercises how to list attributes on examples.  Lets start with
+simple verbose mode.  This output is inspired by GNU @command{ls -l} command
+output.
+
+@itemize @bullet
+@item
+Show only pure extended attributes.
+
+@smallexample
+$ tar --xattrs --list -v archive.tar
+-rw-rwxr--  user/group 0 2012-08-08 15:15 acls.txt
+-rw-rw-r--* user/group 0 2012-08-08 15:15 xattrs.txt
+@end smallexample
+
+Note the asterisk on the third line!  It reflects the situation that the file
+'xattrs.txt' has some extended attribute set.  The default mode (same as if you
+are extracting extended attributes) shows information only about extended
+attributes from 'user.*' domain.  Anyway, feel free to change the sensitivity
+using @option{--xattrs-include} or @option{--xattrs-exclude} options.
+
+@item Show only POSIX ACLs - the character you should look for is '+':
+
+@smallexample
+$ tar --acls --list -v archive.tar
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
+-rw-rw-r--  praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
+@end smallexample
+
+@item Show only SELinux - the key character is '.':
+
+@smallexample
+$ tar --selinux --list -v archive.tar
+-rw-rw-r--.  praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
+-rw-rw-r--   praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
+@end smallexample
+
+@item
+Show info about ACLs, SELinux and general extended attributes together:
+
+@smallexample
+$ tar --selinux --acls --xattrs --list -v archive.tar
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
+@end smallexample
+
+In this case, the priority of character is '+' > '.' > '*'.  You don't see the
+general extended attributes flag ('*' character) on this example because it is
+hidden by '.' (meaning that the file has SELinux context set).
+
+@end itemize
+
+The example of double verbose mode is here.  In this output the single verbose
+characters '.', '+' and '*' are also present after the permission string.
+
+@smallexample
+$ tar --xattrs --selinux --acls -tvvf archive.tar
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
+  s: unconfined_u:object_r:user_tmp_t:s0
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
+  s: unconfined_u:object_r:user_tmp_t:s0
+  a: user::rw-,user:tester:rwx,group::rw-,mask::rwx,other::r--
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
+  s: unconfined_u:object_r:user_tmp_t:s0
+  x: 12 user.xattr
+  x: 12 user.we_like_tar
+@end smallexample
+
+This mode extends tar's output with additional lines beginning with
+distinguishing characters - 's' for SELinux context, 'a' for POSIX Access
+Control Lists  and 'x' for generic extended attributes.
+
+In this format, POSIX ACLs are written in SHORT TEXT FORM as specified in manual
+page @command{man 5 acl}.
+
+Use the @option{--xattrs-include} again if you want to print other than default
+'user.*' extended attributes domain:
+
+@smallexample
+$ tar --xattrs --xattrs-include='*' --acls --selinux -tvvf archive.tar
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:16 selinux_only.txt
+  s: unconfined_u:object_r:user_tmp_t:s0
+  x: 36 security.selinux
+-rw-rwxr--+ praiskup/praiskup 0 2012-08-08 15:15 acls.txt
+  s: unconfined_u:object_r:user_tmp_t:s0
+  a: user::rw-,user:tester:rwx,group::rw-,mask::rwx,other::r--
+  x: 36 security.selinux
+  x: 44 system.posix_acl_access
+-rw-rw-r--. praiskup/praiskup 0 2012-08-08 15:15 xattrs.txt
+  s: unconfined_u:object_r:user_tmp_t:s0
+  x: 36 security.selinux
+  x: 12 user.xattr
+  x: 12 user.we_like_tar
+@end smallexample
+
+As is in @pxref{Option Summary} section described, tar by default stores all
+extended attributes that are available (not only 'user.*' domain).  It means
+that the SELinux context and POSIX ACLs (because they are implemented using the
+generic extended attributes on usual file system) may be stored twice sometimes
+-- firstly in "raw" file system binary format and secondly in more portable way
+-- using appropriate system calls (invoked by @command{tar} options
+@option{--selinux} and @option{--acls}).
+
 @node extract
 @section How to Extract Members from an Archive
 @cindex Extraction
@@ -2371,6 +2484,10 @@ Normally when creating an archive, @command{tar} strips an initial
 treats names specially if they have initial @samp{/} or internal
 @samp{..}.  This option disables that behavior.  @xref{absolute}.
 
+@opsummary{acls}
+@item --acls
+Causes @command{tar} to store/restore/list POSIX ACL's.  @xref{Attributes}.
+
 @opsummary{after-date}
 @item --after-date
 
@@ -2919,6 +3036,11 @@ contents have changed (as opposed to just @option{--newer}, which will
 also back up files for which any status information has
 changed).  @xref{after}.
 
+@opsummary{no-acls}
+@item --no-acls
+Causes @command{tar} not to store, extract or list POSIX ACL's.
+@xref{Attributes}.
+
 @opsummary{no-anchored}
 @item --no-anchored
 An exclude pattern can match any subsequence of the name's components.
@@ -3002,11 +3124,20 @@ locations.  Usually @command{tar} determines automatically whether
 the archive can be seeked or not.  Use this option to disable this
 mechanism.
 
+@opsummary{no-selinux}
+@item --no-selinux
+Causes @command{tar} not to store, extract or list SELinux security context.
+@xref{Attributes}.
+
 @opsummary{no-unquote}
 @item --no-unquote
 Treat all input file or member names literally, do not interpret
 escape sequences.  @xref{input name quoting}.
 
+@opsummary{no-xattrs}
+@item --no-xattrs
+Causes @command{tar} not to store, extract or list xattrs.  @xref{Attributes}.
+
 @opsummary{no-wildcards}
 @item --no-wildcards
 Do not use wildcards.
@@ -3239,6 +3370,11 @@ in cases when such recognition fails.  It takes effect only if the
 archive is open for reading (e.g. with @option{--list} or
 @option{--extract} options).
 
+@opsummary{selinux}
+@item --selinux
+Causes @command{tar} to store, extract or list SELinux security context.
+@xref{Attributes}.
+
 @opsummary{show-defaults}
 @item --show-defaults
 
@@ -3466,6 +3602,11 @@ Enable or disable warning messages identified by @var{keyword}.  The
 messages are suppressed if @var{keyword} is prefixed with @samp{no-}.
 @xref{warnings}.
 
+@opsummary{xattrs}
+@item --xattrs
+Causes @command{tar} to store, restore or list extended file attributes.  For
+more info see @xref{Attributes}.
+
 @opsummary{wildcards}
 @item --wildcards
 Use wildcards when matching member names with patterns.
@@ -4218,6 +4359,11 @@ tar (child): trying gzip
 @cindex @samp{Record size = %lu blocks}, warning message
 @item record-size
 @samp{Record size = %lu blocks}
+@kwindex xattr-write
+@item xattr-write
+@samp{%s: Cannot set '%s' extended attribute for file '%s'}
+@*@samp{%s: Cannot set POSIX ACLs for file '%s'}
+@*@samp{%s: Cannot set SELinux context for file '%s'}
 @end table
 
 @subheading Keywords controlling incremental extraction:
@@ -8770,6 +8916,8 @@ implementation able to read @samp{ustar} archives will be able to read
 most @samp{posix} archives as well, with the only exception that any
 additional information (such as long file names etc.) will in such
 case be extracted as plain text files along with the files it refers to.
+This is the only format that can store ACLs, SELinux context and extended
+attributes.
 
 This archive format will be the default format for future versions
 of @GNUTAR{}.
@@ -9412,6 +9560,135 @@ Same as both @option{--same-permissions} and @option{--same-order}.
 
 This option is deprecated, and will be removed in @GNUTAR{} version 1.23.
 
+@opindex xattrs
+@item --xattrs
+This option causes @command{tar} to store, restore or list the extended file
+attributes (for information about extended attributes see @command{man(5)
+attr}).
+
+Note that all extended attributes are stored "as-is" (in file system binary
+format) and the resulting archive may be not fully portable.  See the
+@option{--selinux} and @option{--acls} options when you want to deal with these
+types of extended attributes in a better way.
+
+The @option{--xattrs} option implies the option @option{--format=posix} when
+tar is in @option{--create} operation mode.  It is the only one format which
+hase usable headers for storing additional file information like extended
+attributes are.
+
+By default, all extended attributes are stored into the archive.  The reason is
+that we want to make the backup process as complete as possible by default.  On
+the other hand, during extracting only the 'user.*' domain is extracted by
+default.  Anyway, this default behaviour may be easily modified by the
+@option{--xattrs-include} and @option{--xattrs-exclude} options.
+
+When you list an archive in verbose mode
+(@command{tar --xattrs --verbose -tf archive.tar}), tar shows the '*' character
+after the permissions string of concrete file ringht to tell you that at least
+one extended attribute is stored with corresponding file.
+
+Double verbose mode (@command{tar --xattrs -tvvf archive.tar}) prints the
+extended attribute length (in bytes) and its ASCII key (for printed examples
+@pxref{List Extended Attributes}).
+
+@option{--xattrs} option has no equivalent short option.
+
+Warnings which occur during impossible writing of extended attributes to
+a file system may be suppressed using the @option{--warning=no-xattr-write}
+option.
+
+@opindex no-xattrs
+@item --no-xattrs
+This option causes @command{tar} not to store/extract or list the current
+extended attributes.  This option does not affect options @option{--no-selinux}
+or @option{--no-acls}.
+
+The @option{--no-xattrs} option has no equivalent short option name.
+
+@opindex xattrs-include
+@opindex xattrs-exclude
+@item --xattrs-include=MASK
+@itemx --xattrs-exclude=MASK
+
+These options allows the xattr store/restore/list process to be more fine
+grained.  The default configuration is that @option{--create} mode handles all
+available extended attributes and the @option{--extract}/@option{--list} mode
+handles only 'user.*' domain.  These options may be used for editing of this
+default behaviour.
+
+@itemize @bullet
+@item
+Lets say we want to store all attributes except some "public restricted" domain
+(e.g.  'user.restricted.*' domain.  The correct way how to do it is:
+
+@command{tar --xattrs --xattrs-include='*' --xattrs-exclude='user.restricted.*'
+-cf archive.tar FILES}
+@item
+And, when we want to extract only some specific domain from an archive - we can
+use:
+
+@command{tar --xattrs --xattrs-include='security.capability' -xf archive.tar
+FILES}
+@end itemize
+
+Multiple passed include/exclude patterns are combined together.  The attribute
+is covered then only if (1) at least one of all include patterns matches its
+keyword and (2) no exclude pattern matches its keyword.
+
+When only include pattern is set - exclude pattern is left in default mode (and
+vice versa).
+
+@opindex selinux
+@item --selinux
+This option causes @command{tar} to store/extract/list the SELinux context
+information into/from an archive.  Command @command{tar} is able to show info
+whether the SELinux context is present in archived file using the verbose
+listing mode (@command{tar --selinux -tvf archive.tar}).  It shows the '.'
+character after permission string in that case.  Double-verbose listing mode
+(@command{tar -tvvf archive.tar}) then prints the full SELinux context to
+standard output, @pxref{List Extended Attributes} for printed example.
+
+This option implies the @option{--format=posix} when @command{tar} works in
+@option{--create} operation mode.
+
+Warnings complaining that SELinux context may not be written to a file system
+may be suppressed by the @option{--warning=no-xattr-write} option.
+
+The @option{--selinux} option has no equivalent short option name.
+
+@opindex no-selinux
+@item --no-selinux
+This option causes @command{tar} not to store the current SELinux security
+context information in the archive and not to extract any SELinux information in
+an archive.
+
+The @option{--no-selinux} option has no equivalent short option name.
+
+@opindex acls
+@item --acls
+This option causes @command{tar} to store the current POSIX access control lists
+into the archive or restore POSIX ACLs from an archive.  It also allows
+@command{tar} to show whether archived file contains ACLs when the verbose mode
+is active (@option{tar --acls -tvf} shows the symbol '+' after the permission
+characters in that case).  Double-verbose mode allows @command{tar} to list
+contained POSIX ACLs (@command{tar --acls -tvvf archive.tar}), for printed
+examples @pxref{List Extended Attributes}.
+
+This option implies the @option{--format=posix} when @command{tar} works in
+@option{--create} operation mode.
+
+Warnings complaining that POSIX ACLs may not be written to a file system may be
+suppressed by the @option{--warning=no-xattr-write} option.
+
+The @option{--acls} option has no equivalent short form.
+
+@opindex no-acls
+@item --no-acls
+This option causes @command{tar} not to store the current POSIX ACL into the
+archive and not to extract any POSIX ACL information from an archive.
+
+The @option{--no-acls} option has no equivalent short option name.
+
 @end table
 
 @node Portability