makary/bookmarkfs
1
0
Fork 0
mirror of https://git.sr.ht/~cismonx/bookmarkfs synced 2025-06-07 19:58:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: misc update

Browse source
This commit is contained in:
CismonX 2025-03-11 10:33:31 +08:00
parent 48b1d8c98d
commit 08b9ea81d6
No known key found for this signature in database
GPG key ID: 3094873E29A482FB
1 changed files with 39 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

69
doc/bookmarkfs.texi
View file

@ -84,20 +84,18 @@ Currently, the following browsers (and their derivatives) are supported:
@item Chromium @item Chromium
@end itemize @end itemize
BookmarkFS is free software, distributed under the terms of the
@uref{https://www.gnu.org/licenses/#GPL, GNU General Public License},
either version 3, or any later version of the license.
To install BookmarkFS, refer to the @file{INSTALL.md} file under the To install BookmarkFS, refer to the @file{INSTALL.md} file under the
root directory of the project codebase. root directory of the project codebase.
BookmarkFS is free software, distributed under the terms of the GNU General
Public License, either version 3, or any later version of the license.
You should have received a copy of the GNU General Public License along with
BookmarkFS. If not, see @uref{https://www.gnu.org/licenses/}.
BookmarkFS is BookmarkFS is
@uref{https://savannah.nongnu.org/projects/bookmarkfs, hosted on Savannah}. @uref{https://savannah.nongnu.org/projects/bookmarkfs, hosted on Savannah},
Write to the where latest releases, development sources and other information are available.
@uref{https://savannah.nongnu.org/mail/?group=bookmarkfs, mailing lists} Also see @uref{https://builds.sr.ht/~cismonx/bookmarkfs, builds.sr.ht}
for bug reports, feature requests, and other discussions. for CI build logs.
@node Porting BookmarkFS @node Porting BookmarkFS
@section Porting BookmarkFS @section Porting BookmarkFS
@ -115,8 +113,8 @@ However, that's not the case for other operating systems.
For example, OpenBSD implements its own FUSE protocol, For example, OpenBSD implements its own FUSE protocol,
which is incompatible with the Linux one. which is incompatible with the Linux one.
While OpenBSD does provide a libfuse-compatible library, however, OpenBSD does provide a libfuse-compatible library, however,
it only covers the high-level API, and BookmarkFS uses the it only covers the high-level API, while BookmarkFS uses the
@uref{https://libfuse.github.io/doxygen/fuse__lowlevel_8h.html, low-level API}. @uref{https://libfuse.github.io/doxygen/fuse__lowlevel_8h.html, low-level API}.
For a similar reason, @uref{https://github.com/winfsp/winfsp, WinFsp} For a similar reason, @uref{https://github.com/winfsp/winfsp, WinFsp}
won't work if you're trying to port BookmarkFS to Microsoft Windows. won't work if you're trying to port BookmarkFS to Microsoft Windows.
@ -157,11 +155,25 @@ Meanwhile, FreeBSD does not support @code{FUSE_READDIRPLUS} and directory
entry caching, which makes listing directory entries less efficient. entry caching, which makes listing directory entries less efficient.
@node Mailing Lists
@section Mailing Lists
Write to the
@uref{https://savannah.nongnu.org/mail/?group=bookmarkfs, mailing lists}
for bug reports, feature requests, and other discussions.
Please do @emph{not} send feature patches, since BookmarkFS is
currently in experimental stage, and is not yet ready for collaboration.
Trivial patches, such as bugfix and typo corrections, are okay.
For security-related problems, please email directly to the project maintainer.
@node Programs @node Programs
@chapter Programs @chapter Programs
BookmarkFS ships with programs that provide users with a command-line BookmarkFS ships with command-line programs to create, mount, fix,
interface to create, mount, fix, and manage BookmarkFS filesystems. and manage BookmarkFS filesystems.
Those programs do not work on their own, and usually require a ``backend'' Those programs do not work on their own, and usually require a ``backend''
for low-level functionalities. for low-level functionalities.
@ -185,8 +197,7 @@ that contains bookmark data.
The exact interpretation of this option is backend-defined. The exact interpretation of this option is backend-defined.
@item target @item target
Pathname of the directory where the filesystem shall be mounted to Pathname of the directory to mount the filesystem.
(i.e., the ``mountpoint'').
@end table @end table
Files under the filesystem are assigned ownership according to Files under the filesystem are assigned ownership according to
@ -770,7 +781,7 @@ An unexpected internal error occurred, likely due to a bug in BookmarkFS,
or a corruption in the bookmark storage. or a corruption in the bookmark storage.
When this error occurs, a log message describing the situation may be printed When this error occurs, a log message describing the situation may be printed
to the standard error of the daemon process. to the standard error of the filesystem daemon.
Sometimes this error comes from the kernel-side FUSE implementation, Sometimes this error comes from the kernel-side FUSE implementation,
and there's no error message. and there's no error message.
@ -803,7 +814,7 @@ On FreeBSD, see @freebsdmanpage{extattr, 2}.
All BookmarkFS extended attributes fall under the ``user'' namespace, All BookmarkFS extended attributes fall under the ``user'' namespace,
which means they have a @samp{user.} name prefix on Linux, and should be which means they have a @samp{user.} name prefix on Linux, and should be
accessed with @code{EXTATTR_NAMESPACE_USER} on FreeBSD. accessed with @code{EXTATTR_NAMESPACE_USER} on FreeBSD.
All attributes have a @samp{bookmarkfs.} name prefix. All attribute names have a @samp{bookmarkfs.} prefix.
For example, to get the GUID of a bookmark file (Firefox backend): For example, to get the GUID of a bookmark file (Firefox backend):
@ -818,8 +829,9 @@ len = extattr_get_fd(fd, EXTATTR_NAMESPACE_USER, "bookmarkfs.guid",
BookmarkFS does not define any common attributes, neither can users create BookmarkFS does not define any common attributes, neither can users create
arbitrary ones. arbitrary ones.
The backend decides which attributes are available during initialization, The backend context decides which attributes are available
and all bookmark files share the same set of attributes. (@pxref{Create Backend Context}),
and all bookmark files under it share the same set of attributes.
@node Directory Entries @node Directory Entries
@ -1799,8 +1811,7 @@ The function should return @t{0} on success, and @t{-1} on error.
@node Destroy Backend Context @node Destroy Backend Context
@subsection Destroy Backend Context @subsection Destroy Backend Context
When a backend context is no longer used, the @code{backend_destroy} function The @code{backend_destroy} function is called to destroy a backend context.
is called.
It must not be @code{NULL}. It must not be @code{NULL}.
Upon destruction, the backend should release all system resources Upon destruction, the backend should release all system resources
@ -2461,7 +2472,7 @@ Function arguments:
The pointer referring to the backend context. The pointer referring to the backend context.
@item parent_id @item parent_id
ID of the parent directory where the new object shall be created. ID of the parent directory to create the new object.
It could be a bookmark ID or tag ID, depending on the value of @code{flags}. It could be a bookmark ID or tag ID, depending on the value of @code{flags}.
@item name @item name
@ -3046,9 +3057,8 @@ The function should return @t{0} on success, and @t{-1} on error.
@node Filesystem-Check Handlers @node Filesystem-Check Handlers
@chapter Filesystem-Check Handlers @chapter Filesystem-Check Handlers
The filesystem-check handler is responsible for instructing the The filesystem-check handler instructs the @command{fsck.bookmarkfs} program
@command{fsck.bookmarkfs} program on what to do with each invalid on what to do with invalid bookmark names.
bookmark name.
Like backends, filesystem-check handlers are typically built into Like backends, filesystem-check handlers are typically built into
shared libraries, and are installed as: shared libraries, and are installed as:
@ -3432,8 +3442,7 @@ The function should return @t{0} on success, and @t{-1} on error.
@node Destroy Handler Context @node Destroy Handler Context
@subsection Destroy Handler Context @subsection Destroy Handler Context
When a handler context is no longer used, the @code{destroy} function The @code{destroy} function is called to destroy a handler context.
is called.
It must not be @code{NULL}. It must not be @code{NULL}.
Upon destruction, The handler should release all system resources Upon destruction, The handler should release all system resources
@ -4134,7 +4143,7 @@ Refer to the source code in @file{src/sandbox.c} for implementation details.
@node File Watcher @node File Watcher
@section File Watcher @section File Watcher
File watchers detects filesystem changes using platform-specific features: File watchers detect filesystem changes using platform-specific features:
@table @asis @table @asis
@item Linux @item Linux
@ -4250,7 +4259,7 @@ The file being watched does not exist.
@item @code{-EIO} @item @code{-EIO}
An internal error has occurred. An internal error has occurred.
Further calls to @code{watcher_poll()} will always fail. Further calls to @code{watcher_poll()} on this watcher will always fail.
@end table @end table
@end table @end table