New commands -projid, -get_projid, -get_projid_r, -set_projid, -set_projid_r, -find test -has_projid, -find actions get_projid, set_projid, get_projid_minmax

xorriso/xorriso.texi

@@ -50,7 +50,7 @@
 @c man .\" First parameter, NAME, should be all caps
 @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 @c man .\" other parameters are allowed: see man(7), man(1)
-@c man .TH XORRISO 1 "Version 1.5.7, Oct 10, 2024"
+@c man .TH XORRISO 1 "Version 1.5.7, Nov 01, 2024"
 @c man .\" Please adjust this date whenever revising the manpage.
 @c man .\"
 @c man .\" Some roff macros, for reference:
@@ -654,6 +654,21 @@ number grew over the years.
 @strong{-lfa_flags}. Its command -lsattr lists 22 flags the same way as the
 program lsattr does. They can be set by xorriso command -chattr and can be
 enabled by -lfa_flags for restoring when their files get restored to disk.
+@c man .PP
+@cindex XFS-style project ids, _definition
+@strong{XFS-style project ids} are numbers which define the members of file
+object groups, called projects. They can be set by programs chattr(1) and
+xfs_quota(8) and reported by programs lsattr(1) and xfs_quota(8).
+The files of a project can share quotas which limit their usage of filesystem
+resources. This is possible in XFS and in specially prepared and mounted ext4
+filesystems. Project id 0 means that the file is not member of any project.
+@*
+@command{xorriso} records non-zero project ids of disk files if enabled by
+command @strong{-projid}. Command -get_projid lists the project ids of files.
+They can be set by command -set_projid and get restored to disk if enabled
+by -projid. Usually project id 0 is not set to restored disk files, so that
+they may get the project id of their parent disk directory.
+@sp 1
 @c man .SS
 @node Processing, Dialog, Extras, Top
 @chapter Command processing
@@ -1397,6 +1412,53 @@ Mode "default" reinstates the default settings:
 @*
 Use "default:on" to get default settings with enabled processing.
 @c man .TP
+@item -projid mode[:mode...]
+@kindex -projid   controls handling of XFS-style project ids
+@cindex XFS-style project ids, control handling, -projid
+Enable, disable, or influence processing of XFS-style project ids.
+@*
+Mode "on" enables recording and restoring of project ids.
+@*
+Mode "off" disables it.
+@*
+Mode "restore_0" enables restoring of project id 0 when files get extracted
+to disk. Default is "no_restore_0" which leaves the decision about the project
+id to the local filesystem, if the file has project id 0 in the ISO filesystem.
+@*
+Mode "map+" defines mappings of project id intervals in the ISO to project id
+intervals on disk when files get restored. The form is:
+@*
+  map+low_in_iso,high_in_iso=low_on_disk[,[high_on_disk]]
+@*
+"low_in_iso" and "high_in_iso" define the number interval from which the
+mapping happens at restore time. "low_on_disk" is the mapping result of
+"low_in_iso". Project id numbers up to "high_in_iso" get mapped to
+@*
+  low_on_disk + (project_id - low_in_iso)
+@*
+If the resulting number is higher than "high_on_disk", then it gets mapped to
+"high_on_disk". "low_on_disk" without following comma means
+"low_on_disk,low_on_disk" which maps the whole "_in_iso" interval to the single
+number "low_on_disk". "low_on_disk," with no following number means
+"low_on_disk,4294967295".
+@*
+Multiple "map+" modes may be given with one or more -projid commands.
+E.g.:
+@*
+  -projid on:map+1,1=11,11:map+1000,1999=2000,
+@*
+The first match in the list of mappings defines the mapping of a given
+project id in the ISO.
+@*
+Pseudo-mode "map_test=" can be used to learn the current mapping
+of the given project number. It immediately reports the mapping result on
+result channel and does not change the current -projid settings. E.g.:
+@*
+  -projid map_test=1001
+@*
+Mode "default" discards all defined mappings and sets -projid to
+"off:no_restore_0".
+@c man .TP
 @item -md5 "on"|"all"|"off"|"load_check_off"
 @kindex -md5   controls handling of MD5 sums
 @cindex MD5, control handling, -md5
@@ -1436,12 +1498,12 @@ Checksums can be exploited via commands -check_md5, -check_md5_r, via find
 actions get_md5, check_md5, and via -check_media.
 @c man .TP
 @item -for_backup
-@kindex -for_backup    acl,xattr,hardlinks,md5,lfa_flags
+@kindex -for_backup    acl,xattr,hardlinks,md5,lfa_flags,projid
 @cindex Backup, enable features, -for_backup
 Enable all extra features which help to produce or to restore backups with
 highest fidelity of file properties. Currently this is a shortcut for:
 @*
-  -hardlinks on -acl on -xattr any -md5 on 
+  -hardlinks on -acl on -xattr any -md5 on -projid on
 @*
 and possibly:
 @*
@@ -2488,6 +2550,18 @@ to be directories or regular data files or else a SORRY event will happen.
 Files below the given directories will be skipped silently if their type is
 not suitable for -chattr.
 @c man .TP
+@item -set_projid number iso_rr_path [***]
+@kindex -set_projid   sets XFS-style project ids in ISO image
+@cindex  XFS-style project ids, set in ISO image, -set_projid
+Set the XFS-style project ids like programs xfs_quota(8) or chattr(1)
+would do to disk files. The permissible number range is 0 to 4294967295.
+0 means that the file does not belong to any project.
+@c man .TP
+@item -set_projid_r number iso_rr_path [***]
+@kindex -set_projid_r   sets XFS-style project ids in ISO image
+@cindex  XFS-style project ids, set in ISO image, -set_projid_r
+Like -projid but affecting also all files below the given directories.
+@c man .TP
 @item -alter_date type timestring iso_rr_path [***]
 @kindex -alter_date   sets timestamps in ISO image
 @cindex Timestamps, set in ISO image, -alter_date
@@ -2689,6 +2763,9 @@ Matches files which have a non-trivial ACL.
 @item -has_xattr :
 Matches files which have xattr name-value pairs from user namespace.
 @*
+@item -has_any_xattr :
+Matches files which have any xattr other than ACL.
+@*
 @item -has_aaip :
 Matches files which have ACL or any xattr.
 @*
@@ -2711,8 +2788,8 @@ E.g. look for files which have 'i' or 'a' or both of them set:
 @*
  -has_some_lfa_flags_of ia
 @*
-@item -has_any_xattr :
-Matches files which have any xattr other than ACL.
+@item -has_projid number :
+Matches files which bear the given XFS-style project id number.
 @*
 @item -has_md5 :
 Matches data files which have MD5 checksums.
@@ -2966,12 +3043,24 @@ Command -backslash_codes does not affect the output.
 @item lsattrd
 shows the Linux file attribute flags like command -lsattrd does.
 @*
-@item chattr
+@item chattr mode
 applies -chattr with the given mode. Other than command -chattr this silently
 skips any file which are not -type "dir" or "file".
 @*
 E.g.: -exec chattr +sDu --
 @*
+@item get_projid
+shows the XFS-style project id number.
+@*
+@item get_projid_minmax
+shows at the end of the -find run the minimal and the maximal XFS-style
+project id numbers among the files which were matched by the find tests.
+@*
+@item set_projid number
+applies -set_projid with the given number. Number range is 0 to 4294967295.
+@*
+E.g.: -exec set_projid 1001 --
+@*
 @item get_md5
 prints the MD5 sum, if recorded, together with file path.
 @*
@@ -5832,6 +5921,18 @@ attributes attached. In this case all flags will be shown as '-'.
 Like -lsattr but listing the directory attributes if the iso_rr_path leads to
 a directory, rather than the attributes of the files in the directory.
 @c man .TP
+@item -get_projid iso_rr_pattern [***]
+@kindex -get_projid   shows XFS-style project ids in ISO image
+@cindex XFS-style project ids, show in ISO image, -get_projid
+Print the XFS-style project ids of the given file objects. On disk this
+information can be inspected by programs lsattr(1) or xfs_quota(8).
+@c man .TP
+@item -get_projid_r iso_rr_pattern [***]
+@kindex -get_projid_r   shows XFS-style project ids in ISO image
+@cindex XFS-style project ids, show in ISO image, -get_projid_r
+Like -get_projid but listing recursively the whole file trees underneath of
+directories.
+@c man .TP
 @item -du iso_rr_pattern [***]
 @kindex -du   show directory size in ISO image
 @cindex Navigate, directory size in ISO image, -du
@@ -5870,8 +5971,8 @@ like described with -find:
 @*
   -bad_outname, -decision, -disk_name, -disk_path, -has_acl,
   -has_any_xattr, -has_lfa_flags, -has_some_lfa_flags_of,
-  -has_xattr, -lba_range, -maxdepth, -mindepth, -name,
-  -or_use_pattern, -prune, -size, -true, -type,
+  -has_projid, -has_xattr, -lba_range, -maxdepth, -mindepth,
+  -name, -or_use_pattern, -prune, -size, -true, -type,
   -use_pattern, -wholename
 @*
 The others get defaulted to -false, because they are not applicable to disk
@@ -5955,10 +6056,18 @@ See -find for a description of parameter mode.
 E.g. -exec list_extattr e --
 @*
 @item lsattrd
-prints the Linux file attribute flags like command -lsattrd does.
+prints to the result channel the Linux file attribute flags like
+command -lsattrd does.
 This shows non-settable flags, too, even if they are to be ignored by the
 setting of command -lfa_flags.
+@*
+@item get_projid
+prints the XFS-style project id number to the result channel.
 @end table
+@*
+@item get_projid_minmax
+prints at the end of the -findx run the minimal and the maximal XFS-style
+project id numbers among the files which were matched by the find tests.
 @c man .TP
 @item -compare disk_path iso_rr_path
 @kindex -compare   reports ISO/disk differences
@@ -6865,7 +6974,12 @@ Print program name and version, component versions, license.
 @item -list_extras code
 @kindex -list_extras   lists compile time extra features
 @cindex Program, list extra features, -list_extras
-Tell whether certain extra features were enabled at compile time.
+Tell whether certain extra features were enabled at compile time and the
+environment provided the necessary system interfaces.
+Application of the enabled features might fail at run time because the system
+does not provide the necessary interfaces or the involved local filesystem
+does not provide the desired feature.
+@*
 Code "all" lists all features and a headline.
 Other codes pick a single feature.
 Code "codes" lists them. They share names with related commands
@@ -6878,6 +6992,8 @@ Code "codes" lists them. They share names with related commands
 "lfa_flags" tells whether xorriso has an adapter for local Linux file
 attributes (see man 1 chattr).
 @*
+"projid" tells whether xorriso has an adapter for local XFS-style project ids.
+@*
 "jigdo" tells whether production of Jigdo files is possible.
 @*
 "zisofs" tells whether zisofs and built-in gzip filters are enabled.
@@ -8110,13 +8226,15 @@ Startup files and program options can override the effect of SOURCE_DATE_EPOCH.
 @c man .BR wodim(1),
 @c man .BR cdrskin(1)
 @c man .TP
-@c man ACL, xattr, Linux file attributes
+@c man ACL, xattr, Linux file attributes, project ids
 @c man .BR getfacl(1),
 @c man .BR setfacl(1),
 @c man .BR getfattr(1),
 @c man .BR setfattr(1),
 @c man .BR lsattr(1),
-@c man .BR chattr(1)
+@c man .BR chattr(1),
+@c man .BR ext4(5),
+@c man .BR xfs_quota(8)
 @c man .TP
 @c man MD5 checksums
 @c man .BR md5sum(1)
@@ -8145,13 +8263,15 @@ growisofs(1),
 cdrecord(1),
 wodim(1),
 cdrskin(1)
-@item ACL, xattr, Linux file attributes
+@item ACL, xattr, Linux file attributes, project ids
 getfacl(1),
 setfacl(1),
 getfattr(1),
 setfattr(1),
 lsattr(1),
-chattr(1)
+chattr(1),
+ext4(5),
+xfs_quota(8)
 @item MD5 checksums
 md5sum(1)
 @item On FreeBSD some commands differ: