Blame SOURCES/tar-1.26-docu-xattrs.patch

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