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: add a newline to the end of each sentence

Browse source 
We don't want the git diff to span the entire paragraph when
only one line is changed.

Also makes the doc more readable in plaintext.
This commit is contained in:
CismonX 2025-01-02 00:43:27 +08:00
parent 0863343749
commit e06a4d55bc
No known key found for this signature in database
GPG key ID: 3094873E29A482FB
1 changed files with 64 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

115
doc/bookmarkfs.texi
View file

@ -93,13 +93,15 @@ features, porting it to other operating systems is not trivial.
The major pitfall is the The major pitfall is the
@uref{https://docs.kernel.org/filesystems/fuse.html, FUSE} dependency. @uref{https://docs.kernel.org/filesystems/fuse.html, FUSE} dependency.
Generally speaking, FUSE is Linux-only. FreeBSD partially implements the Generally speaking, FUSE is Linux-only.
FUSE protocol in its kernel, to the extent that BookmarkFS is mostly usable. FreeBSD partially implements the FUSE protocol in its kernel,
to the extent that BookmarkFS is mostly usable.
However, that's not the case for other operating systems. However, that's not the case for other operating systems.
For example, OpenBSD implements its own FUSE protocol, which is incompatible For example, OpenBSD implements its own FUSE protocol,
with the Linux one. While OpenBSD does provide a libfuse-compatible library, which is incompatible with the Linux one.
however, it only covers the high-level API, and BookmarkFS uses the While OpenBSD does provide a libfuse-compatible library, however,
it only covers the high-level API, and 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.
@ -108,25 +110,25 @@ won't work if you're trying to port BookmarkFS to Microsoft Windows.
@node Sandboxing @node Sandboxing
@section Sandboxing @section Sandboxing
A BookmarkFS backend can be instructed to enter a sandboxed state, where it A BookmarkFS backend can be instructed to enter a sandboxed state,
irrevocably relinquishes most access to the system resources that it's not where it irrevocably relinquishes most access to the system resources
supposed to touch. For example, it can only access the directory that contains that it's not supposed to touch.
the bookmark file; it cannot establish socket connections; it cannot execute For example, it can only access the directory that contains the bookmark file;
other files; ... it cannot establish socket connections; it cannot execute other files; ...
This mechanism reduces the attack surface for exploit, if a vulnerability This mechanism reduces the attack surface for exploit,
is discovered in BookmarkFS and/or its dependencies. if a vulnerability is discovered in BookmarkFS and/or its dependencies.
However, it only deals with untrusted input, and cannot help if the However, it only deals with untrusted input,
operating system has already been compromised. and cannot help if the operating system has already been compromised.
Example of what ``untrusted input'' may include: Example of what ``untrusted input'' may include:
@itemize @bullet{} @itemize @bullet{}
@item Bookmark files that are @emph{not} created by the user using a @item Bookmark files that are @emph{not} created by the user using a
trusted program (e.g. a file obtained from some random person on the internet). trusted program (e.g. a file obtained from some random person on the internet).
@item Filesystem calls from untrusted programs. The program itself may be @item Filesystem calls from untrusted programs.
isolated, but it has a chance to escape the isolated environment The program itself may be isolated, but it has a chance to escape
if it can exploit BookmarkFS. the isolated environment if it can exploit BookmarkFS.
@end itemize @end itemize
On Linux, sandboxing is achieved using @linuxmanpage{seccomp, 2} and On Linux, sandboxing is achieved using @linuxmanpage{seccomp, 2} and
@ -137,12 +139,14 @@ On FreeBSD, @freebsdmanpage{capsicum, 4} is used.
@node Contributing @node Contributing
@section Contributing to BookmarkFS @section Contributing to BookmarkFS
BookmarkFS is hosted on Savannah. Write to the BookmarkFS is hosted on Savannah.
Write to the
@uref{https://savannah.nongnu.org/mail/?group=bookmarkfs, mailing lists} @uref{https://savannah.nongnu.org/mail/?group=bookmarkfs, mailing lists}
for bug reports, feature requests, and other discussions. for bug reports, feature requests, and other discussions.
BookmarkFS is a personal hobby project, and is currently in BookmarkFS is a personal hobby project, and is currently in
experimental stage. Thus, it it not yet ready for open collaboration, experimental stage.
Thus, it it not yet ready for open collaboration,
which means patches are generally rejected unless trivial (e.g. typo fix). which means patches are generally rejected unless trivial (e.g. typo fix).
@ -173,8 +177,8 @@ which means patches are generally rejected unless trivial (e.g. typo fix).
@node Hierarchy @node Hierarchy
@section Filesystem Hierarchy @section Filesystem Hierarchy
BookmarkFS has multiple subsystems. Each one appears as a directory under BookmarkFS has multiple subsystems.
the mountpoint: Each one appears as a directory under the mountpoint:
@example @example
$@{mountpoint@}/bookmarks $@{mountpoint@}/bookmarks
@ -205,19 +209,21 @@ $@{mountpoint@}/tags/$@{tag_name@}/$@{bookmark_name@}
@end example @end example
The ``tags'' subsystem maintains a many-to-many mapping between bookmarks and The ``tags'' subsystem maintains a many-to-many mapping between bookmarks and
their alternative names. Each tag name appears as the filename for directory their alternative names.
@code{$@{tag_name@}}, and @code{$@{bookmark_name@}} is a hard link to the Each tag name appears as the filename for directory @code{$@{tag_name@}},
bookmark file. A bookmark directory cannot be associated with a tag. and @code{$@{bookmark_name@}} is a hard link to the bookmark file.
A bookmark directory cannot be associated with a tag.
If multiple bookmark files with identical names are both associated with a tag, If multiple bookmark files with identical names are both associated with a tag,
it is unspecified which one appears as an entry for the tag directory. it is unspecified which one appears as an entry for the tag directory.
However, consecutive lookups and @code{readdir()}s should produce consistent However, consecutive lookups and @code{readdir()}s should produce consistent
results for that file, provided that it is not renamed or deleted. results for that file, provided that it is not renamed or deleted.
Tag files behave differently from traditional hard links. If the original Tag files behave differently from traditional hard links.
bookmark file is renamed or deleted, it may also change accordingly. If the original bookmark file is renamed or deleted,
It may even link to another file that was previously shadowed. Applications it may also change accordingly.
should tread lightly if they wish to cache tag directory entries. It may even link to another file that was previously shadowed.
Applications should tread lightly if they wish to cache tag directory entries.
To associate a bookmark with a tag, use @posixfuncmanpage{link}: To associate a bookmark with a tag, use @posixfuncmanpage{link}:
@ -246,9 +252,9 @@ Each keyword name appears as the filename for regular file
@code{$@{keyword_name@}}, which is a hard link to the bookmark file. @code{$@{keyword_name@}}, which is a hard link to the bookmark file.
A bookmark directory cannot be associated with a keyword. A bookmark directory cannot be associated with a keyword.
To associate a bookmark with a keyword, use @code{link()}, To associate a bookmark with a keyword, use @code{link()} like we do with tags.
like we do with tags. If the original file is already associated with If the original file is already associated with another keyword,
another keyword, the operation fails with @code{EEXIST}. @code{link()} fails with @code{EEXIST}.
@node Extended Attributes @node Extended Attributes
@ -257,16 +263,18 @@ another keyword, the operation fails with @code{EEXIST}.
BookmarkFS uses extended attributes to manage additional information associated BookmarkFS uses extended attributes to manage additional information associated
with a bookmark. with a bookmark.
Extended attributes is a platform-specific feature. On Linux, see Extended attributes is a platform-specific feature.
@linuxmanpage{xattr, 7}. On FreeBSD, see @freebsdmanpage{extattr, 2}. On Linux, see @linuxmanpage{xattr, 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 @code{user.} name prefix on Linux, and should be which means they have a @code{user.} name prefix on Linux, and should be
accessed with @code{EXTATTR_NAMESPACE_USER} on FreeBSD. accessed with @code{EXTATTR_NAMESPACE_USER} on FreeBSD.
BookmarkFS does not define any common attributes, neither can users create BookmarkFS does not define any common attributes, neither can users create
arbitrary ones. The backend decides which attributes are available during arbitrary ones.
initialization, and all bookmark files share the same set of attributes. The backend decides which attributes are available during initialization,
and all bookmark files share the same set of attributes.
All attributes have a @code{bookmarkfs.} name prefix. All attributes have a @code{bookmarkfs.} name prefix.
For example, to get the GUID of a bookmark file (Firefox backend) on GNU/Linux: For example, to get the GUID of a bookmark file (Firefox backend) on GNU/Linux:
@ -288,24 +296,28 @@ $ getextattr user bookmarkfs.guid \
@section Permute Directory Entries @section Permute Directory Entries
POSIX does not specify the ordering of the directory entries retrieved from POSIX does not specify the ordering of the directory entries retrieved from
the directory stream using @posixfuncmanpage{readdir}. It only guarantees the directory stream using @posixfuncmanpage{readdir}.
that if an entry is not added or removed from the directory after the most It only guarantees that if an entry is not added or removed from the directory
recent call to @posixfuncmanpage{opendir} or @posixfuncmanpage{rewinddir}, after the most recent call to @posixfuncmanpage{opendir} or
that entry is returned once and only once. @posixfuncmanpage{rewinddir}, that entry is returned once and only once.
This allows filesystem implementations to organize directory entries in a more This allows filesystem implementations to organize directory entries in a more
relaxed manner. There could be extra overhead to maintain a predictable relaxed manner.
ordering of directory entries, since they may not have a linear structure on There could be extra overhead to maintain a predictable ordering of
modern on-disk filesystems (e.g. ext4 uses ``HTree'' for large directories). directory entries, since they may not have a linear structure on modern
on-disk filesystems (e.g. ext4 uses ``HTree'' for large directories).
As for users of a filesystem, the order of directory entries generally As for users of a filesystem, the order of directory entries generally
does not matter. If they care, they can add a prefix to the filename, does not matter.
and let the application do the sorting. If they care, they can add a prefix to the filename, and let the application
do the sorting.
However, the order of which a bookmark entry appears in the web browser However, the order of which a bookmark entry appears in the web browser
sometimes does matter. Thus, BookmarkFS guarantees it to be equivalent to the sometimes does matter.
directory traversal order. New entries are appended to the end; removed In BookmarkFS, it is guaranteed to be equivalent to the
entries do not affect the order of other entries. directory traversal order.
New entries are appended to the end; removed entries do not affect
the order of other entries.
@node Check for Errors @node Check for Errors
@ -318,10 +330,6 @@ entries do not affect the order of other entries.
In BookmarkFS, each backend provides a way to manipulate a certain kind of In BookmarkFS, each backend provides a way to manipulate a certain kind of
application bookmarks. application bookmarks.
BookmarkFS ships with two backends. One for Firefox, the other for Chromium.
If you which to add support for more backends, you may submit a feature request
or implement one using the Backend API.
Typically, backends are built into shared libraries, and are installed as: Typically, backends are built into shared libraries, and are installed as:
@example @example
@ -342,6 +350,11 @@ $ /usr/local/bin/mount.bookmarkfs -o backend=firefox \
The @code{mount.bookmarkfs} program loads the bookmark file using the The @code{mount.bookmarkfs} program loads the bookmark file using the
backend module @code{/usr/local/lib/bookmarkfs/backend-firefox.so}. backend module @code{/usr/local/lib/bookmarkfs/backend-firefox.so}.
Currently, BookmarkFS ships with two backends.
One for Firefox, the other for Chromium.
If you which to add support for more backends,
you may submit a feature request or implement one using the Backend API.
@node Firefox @node Firefox
@section Firefox Backend @section Firefox Backend