From b96ed2a4906e23e397116c4cf1f93b801cb0b285 Mon Sep 17 00:00:00 2001 From: CismonX Date: Tue, 18 Mar 2025 06:19:59 +0800 Subject: [PATCH] doc: add docs for bookmarkctl xattr-* sub-commands --- doc/bookmarkctl.1 | 104 ++++++++++++++++++++++++++++++++++++++++++-- doc/bookmarkfs.texi | 96 +++++++++++++++++++++++++++++++++++++++- 2 files changed, 196 insertions(+), 4 deletions(-) diff --git a/doc/bookmarkctl.1 b/doc/bookmarkctl.1 index 42ce45a..1254185 100644 --- a/doc/bookmarkctl.1 +++ b/doc/bookmarkctl.1 @@ -20,6 +20,28 @@ bookmarkctl - manage a mounted BookmarkFS filesystem .I pathname .PP .B bookmarkctl +.B xattr\-list +.I pathname +.PP +.B bookmarkctl +.B xattr\-get +.RI [ options ] +.I name +.IR pathname ... +.PP +.B bookmarkctl +.B xattr\-get +.RI [ options ] +.B \-m +.IR name "... " pathname +.PP +.B bookmarkctl +.B xattr\-set +.RI [ options ] +.I name +.I pathname +.PP +.B bookmarkctl .B help .PP .B bookmarkctl @@ -28,8 +50,9 @@ bookmarkctl - manage a mounted BookmarkFS filesystem .SH DESCRIPTION The .B bookmarkctl -program is a command-line wrapper for various I/O controls of a BookmarkFS -filesystem. +program is a command-line wrapper for various operations on a BookmarkFS +filesystem that cannot be done portably with POSIX utilities alone, +including I/O controls and managing extended attributes. .SS Permute directory entries The .B permd @@ -56,6 +79,37 @@ It does not recurse into subdirectories. .PP For the full fsck functionalities, use .BR fsck.bookmarkfs (1). +.SS List extended attribute names +The +.B xattr\-list +sub-command displays a list of extended attribute names +of the file referred to by +.IR pathname . +.PP +Only the names prefixed with "user.bookmarkfs." are listed, +with the prefix removed. +.SS Get extended attribute value +The +.B xattr\-get +sub-command displays one or multiple extended attribute values +of the file referred to by +.IR pathname . +.PP +The +.I name +argument is the name of the extended attribute, +without the "user.bookmarkfs." prefix. +.SS Set extended attribute value +The +.B xattr\-set +sub-command updates the value of an extended attribute +of the file referred to by +.IR pathname . +.PP +The +.I name +argument is the name of the extended attribute, +without the "user.bookmarkfs." prefix. . .SH OPTIONS .SS Permute directory entries @@ -78,6 +132,49 @@ and .B \-a options are mutually exclusive. If multiple options are provided, the last one takes effect. +.SS Get extended attribute value +.TP +.B \-b +Treat the value as binary, and print it verbatim. +.IP +If this option is not provided, non-printable characters are replaced with '?'. +.TP +.B \-m +Switch to multi-name mode, where multiple extended attribute names +can be specified instead of multiple files. +.IP +Also, the corresponding +.I name +is printed alongside with the value, instead of +.IR pathname . +.TP +.B \-q +Print values only, do not print names. +.IP +If provided twice, do not print the suffix character after each value. +.TP +\fB\-s\fR \fIchar\fR +The character separating each name and value. +Defaults to the ASCII LT character. +.TP +\fB\-n\fR \fIchar\fR +The character suffixing each value. +Defaults to the ASCII LF character. +.PP +For the +.B \-s +and +.B \-n +options, if +.I char +contains multiple characters, the first one is used. +If empty, the ASCII NUL character is used. +.SS Set extended attribute value +.TP +\fB\-v\fR \fIvalue\fR +New value for the extended attribute. +.IP +If this option is not provided, the new value is read from standard input. . .SH EXIT STATUS .TP @@ -101,7 +198,8 @@ implementation. .BR mount.bookmarkfs (1), .BR ioctl (2), .BR readdir (3), -.BR fusefs (5) +.BR fusefs (5), +.BR xattr (7) .PP The full BookmarkFS User Manual is maintained as a Texinfo document. To read it locally, run: diff --git a/doc/bookmarkfs.texi b/doc/bookmarkfs.texi index 071ea91..ed4e147 100644 --- a/doc/bookmarkfs.texi +++ b/doc/bookmarkfs.texi @@ -537,7 +537,8 @@ Print version and feature information, and then exit. @section @command{bookmarkctl} The @command{bookmarkctl} program is a command-line wrapper for various -I/O controls of a BookmarkFS filesystem. +operations on a BookmarkFS filesystem that cannot be done portably with +POSIX utilities alone, including I/O controls and managing extended attributes. @example bookmarkctl @var{subcmd} [@var{args}] @@ -600,6 +601,99 @@ Path to the directory to perform checks on. For the full fsck functionalities, @pxref{fsck.bookmarkfs}. +@item xattr-list +Displays a list of extended attribute names. +@xref{Extended Attributes}. + +@example +bookmarkctl xattr-list @var{pathname} +@end example + +@table @var +@item pathname +Path to the file to obtain extended attribute names. +@end table + +Only the names prefixed with @samp{user.bookmarkfs.} are listed, +with the prefix removed. + +@item xattr-get +Displays extended attribute values. +@xref{Extended Attributes}. + +@example +bookmarkctl xattr-get [@var{options}] @var{name} @var{pathname}... +bookmarkctl xattr-get [@var{options}] -m @var{name}... @var{pathname} +@end example + +@table @var +@item name +Name of the extended attribute, without the @samp{user.bookmarkfs.} prefix. + +@item pathname +Path to the file to obtain extended attribute values. +@end table + +Options: + +@table @option +@item -b +Treat the value as binary, and print it verbatim. + +If this option is not provided, non-printable characters are replaced with +@samp{?}. + +@item -m +Switch to multi-name mode, where multiple extended attribute names +can be specified instead of multiple files. + +Also, the corresponding @var{name} is printed alongside with the value, +instead of @var{pathname}. + +@item -q +Print values only, do not print names. + +If provided twice, do not print the suffix character after each value. + +@item -s @var{char} +The character separating each name and value. +Defaults to the ASCII LT character. + +@item -n @var{char} +The character suffixing each value. +Defaults to the ASCII LF character. +@end table + +For the @option{-s} and @option{-n} options, +if @var{char} contains multiple characters, the first one is used. +If empty, the ASCII NUL character is used. + +@item xattr-set +Update the value of an extended attribute. +@xref{Extended Attributes}. + +@example +bookmarkctl xattr-set [@var{options}] @var{name} @var{pathname} +@end example + +@table @var +@item name +Name of the extended attribute to update, +without the @samp{user.bookmarkfs.} prefix. + +@item pathname +Path to the file to update extended attribute value. +@end table + +Options: + +@table @option +@item -v @var{value} +New value for the extended attribute. + +If this option is not provided, the new value is read from standard input. +@end table + @item help Print help text, and then exit.