.TH BOOKMARKCTL 1 "Dec 01, 2024" 0.1.0 "BookmarkFS User Manual"
.
.SH NAME
bookmarkctl - manage a mounted BookmarkFS filesystem
.
.SH SYNOPSIS
.B bookmarkctl
.I subcmd
.RI [ args ]
.PP
.B bookmarkctl
.B permd
.RI [ options ]
.I name1
.I name2
.I pathname
.PP
.B bookmarkctl
.B fsck
.I pathname
.PP
.B bookmarkctl
.B xattr\-list
.I pathname
.PP
.B bookmarkctl
.B xattr\-get
.RI [ options ]
.I attrname
.IR pathname ...
.PP
.B bookmarkctl
.B xattr\-get
.RI [ options ]
.B \-a
.IR attrname "... " pathname
.PP
.B bookmarkctl
.B xattr\-set
.RI [ options ]
.I attrname
.I pathname
.PP
.B bookmarkctl
.B help
.PP
.B bookmarkctl
.B version
.
.SH DESCRIPTION
The
.B bookmarkctl
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
sub-command re-arranges the order of the directory entries to be returned
from future
.BR readdir (3)
calls.
.PP
The
.I pathname
argument is the path to the directory.
The
.I name1
and
.I name2
arguments are filenames under that directory.
.SS Filesystem check
The
.B fsck
sub-command displays a list of filesystem errors found under the directory
referred to by
.IR pathname .
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 attrname
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 attrname
argument is the name of the extended attribute,
without the "user.bookmarkfs." prefix.
.
.SH OPTIONS
.SS Permute directory entries
.TP
.B \-s
Exchange the positions of the directory entries represented by
.I name1
and
.IR name2 .
.TP
.B \-b
Move the directory entry represented by
.I name1
to the position just before the one represented by
.IR name2 .
.TP
.B \-a
Move the directory entry represented by
.I name1
to the position just after the one represented by
.IR name2 .
.PP
The
.BR \-s ", " \-b
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 \-a
Switch to multi-attrname mode, where multiple extended attribute names
can be specified instead of multiple files.
.IP
Also, the corresponding
.I attrname
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 HT 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
0
The operation completed successfully.
.TP
1
An error occurred.
.
.SH NOTES
.SS Availability on FreeBSD
By the time this manual is written, this program is not available on
stable releases of FreeBSD, since the latter does not yet support
.BR ioctl (2)
in its
.BR fusefs (5)
implementation.
.
.SH SEE ALSO
.BR fsck.bookmarkfs (1),
.BR mount.bookmarkfs (1),
.BR ioctl (2),
.BR readdir (3),
.BR fusefs (5),
.BR xattr (7)
.PP
The full BookmarkFS User Manual is maintained as a Texinfo document.
To read it locally, run:
.PP
.in +4n
.EX
.B info bookmarkfs
.EE
.in
.
.SH COPYRIGHT
Copyright (C) 2024  CismonX <admin@cismon.net>
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.PP
You should have received a copy of the license along with this document.
If not, see
.UR https://www.gnu.org/licenses/fdl-1.3.html
.UE .