\input texinfo  @c -*-texinfo-*-

@setfilename bookmarkfs.info
@include version.texi
@settitle BookmarkFS User Manual

@macro manpage {name, section, url}
@uref{\url\,, @code{\name\(\section\)}}
@end macro

@macro linuxmanpage {name, section}
@manpage{\name\, \section\,
    https://man7.org/linux/man-pages/man\section\/\name\.\section\.html}
@end macro

@macro freebsdmanpage {name, section}
@manpage{\name\, \section\,
    https://man.freebsd.org/cgi/man.cgi?\name\(\section\)}
@end macro

@macro posixfuncmanpage {name}
@manpage{\name\, 3p,
    https://pubs.opengroup.org/onlinepubs/9799919799/functions/\name\.html}
@end macro

@macro linuxdoc {name, path}
@uref{https://docs.kernel.org/\path\, \name\}
@end macro

@copying
This manual is for BookmarkFS, version @value{VERSION}.

@quotation
Copyright @copyright{} 2024  CismonX <admin@@cismon.net>

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.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
@end quotation
@end copying

@titlepage
@title BookmarkFS
@subtitle version @value{VERSION}
@author CismonX

@page
@vskip 0pt plus 1filll
@insertcopying

@end titlepage


@summarycontents
@contents

@node Top
@top BookmarkFS User Manual

@insertcopying


@node Overview
@chapter Overview

BookmarkFS is a FUSE-based pseudo-filesystem which provides an interface to
the bookmark data of web browsers.

Currently, the following browsers (and their derivatives) are supported:

@itemize @bullet{}
@item Firefox
@item Chromium
@end itemize

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/}.


@node Porting
@section Porting BookmarkFS

Currently, BookmarkFS only runs on GNU/Linux and FreeBSD.

Although BookmarkFS sticks hard to POSIX and avoids using platform-specific
features, porting it to other operating systems is not trivial.

The major pitfall is the @linuxdoc{FUSE, filesystems/fuse.html} dependency.
Generally speaking, FUSE is Linux-only.
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.

For example, OpenBSD implements its own FUSE protocol,
which is incompatible with the Linux one.
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}.
For a similar reason, @uref{https://github.com/winfsp/winfsp, WinFsp}
won't work if you're trying to port BookmarkFS to Microsoft Windows.


@node Sandboxing
@section Sandboxing

A BookmarkFS backend can be instructed to enter a sandboxed state,
where it irrevocably relinquishes most access to the system resources
that it's not supposed to touch.
For example:

@itemize @bullet{}
@item access local files other than the bookmark storage
@item establish socket connections
@item execute other files
@end itemize

This mechanism reduces the attack surface for exploit,
if a vulnerability is discovered in BookmarkFS and/or its dependencies.
However, it only deals with untrusted input,
and cannot help if the operating system has already been compromised.

Example of what ``untrusted input'' may include:

@itemize @bullet{}
@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).
@item Filesystem calls from untrusted programs.
The program itself may be isolated, but it has a chance to escape
the isolated environment if it can exploit BookmarkFS.
@end itemize

On Linux, sandboxing is achieved using @linuxmanpage{seccomp, 2} and
@linuxmanpage{landlock, 7}.
On FreeBSD, @freebsdmanpage{capsicum, 4} is used.


@node Contributing
@section Contributing to BookmarkFS

BookmarkFS is hosted on Savannah.
Write to the
@uref{https://savannah.nongnu.org/mail/?group=bookmarkfs, mailing lists}
for bug reports, feature requests, and other discussions.

BookmarkFS is a personal hobby project, and is currently in
experimental stage.
Thus, it it not yet ready for open collaboration,
which means patches are generally rejected unless trivial (e.g. typo fix).


@node Programs
@chapter Programs


@node mount.bookmarkfs
@section @command{mount.bookmarkfs}

@example
mount.bookmarkfs [@var{options}] @var{src} @var{target}
@end example

The @command{mount.bookmarkfs} program mounts a BookmarkFS filesystem to the
location specified by @var{target}.

The @var{src} argument is presumably the pathname of a file that stores
bookmark data.
Its exact interpretation is backend-defined.

To unmount a BookmarkFS filesystem, run @linuxmanpage{fusermount3, 1} or
@linuxmanpage{umount, 8} on @var{target}.
The daemon process will automatically dismount the filesystem upon
@code{SIGINT} or @code{SIGTERM} receipt, however, it only works in
non-sandbox mode.

Available options:

@table @option
@item -o backend=@var{name}
The backend used by the filesystem (@pxref{Backends}).
This option is mandatory.

@item -o @@@var{key}[=@var{value}]
A backend-specific option.
This option can be provided multiple times.

@item -o accmode=@var{mode}
File access mode.
Defaults to @code{0700}.

This option applies to both directories and regular files.
Execution bits on regular files are masked off.

Should be used in combination with @option{-o allow_other} for other users to
access the files.

@anchor{File Modification/Change Time}
@cindex File Modification/Change Time
@item -o ctime
Maintain file change time, while modification time follows change time.
If this option is not provided, maintain file modification time instead.

Usually, a bookmark's ``modification time'' attribute behaves differently
from both mtime and ctime.
In Chromium, for instance, when a bookmark is renamed, neither itself
nor the parent directory changes timestamp accordingly.

BookmarkFS do not follow browser behavior here, and instead try to stay
compatible with POSIX.
Since a bookmark has only one ``modification time'' attribute instead of two,
the user has to choose which one to maintain.
If choosing mtime, ctime only updates when mtime does.
Otherwise, mtime may change when the file content is not modified --
inefficient but makes applications that depend on ctime less fragile.

The kernel may cache file attributes, making ctime appear more ``correct''
than what we claim.
However, this behavior should not be relied upon.

@item -o eol
Add a newline (ASCII LF character) to the end of each file.

Before writing the file content back to the backend,
a trailing newline is automatically removed (if one exists).

@item -o file_max=@var{bytes}
Max file size limit.
Defaults to @code{32768}.

@item -o no_sandbox
Do not enable sandboxing features (@pxref{Sandboxing}).

@anchor{Disabling Landlock}
@item -o no_landlock
Do not use Landlock for sandboxing.
This option is ignored on non-Linux platforms.

Without Landlock, sandboxing offers less security.
However, Landlock is a rather new feature (requires kernel version 5.13
or later), thus we provide an option to disable it separately.

@item -F
Stay in the foreground, do not daemonize.

@item -h
Print help text, and then exit.
@item -V
Print version and feature information, and then exit.
@end table

Unrecognized options specified with @option{-o} are passed to libfuse
(and subsequently to the kernel, if applicable) as-is.
Notable options:

@table @option
@item -o rw
Mount the filesystem read/write.

By default, the filesystem is mounted read-only.
This behavior won't change in the future, since the hackish nature of
BookmarkFS makes it forever unstable.

@quotation Warning
Always backup the bookmarks before mounting it read/write, or risk losing
your data!
@end quotation

@item -o debug
Set libfuse log level to @code{FUSE_LOG_DEBUG}.
Log messages related to each FUSE request will be printed to standard error.

@item -o fsname
The name that appears as the @code{fs_spec} field in @linuxmanpage{fstab, 5}.
Defaults to the backend name.

@item -o atime,diratime,relatime
These options (and other atime-related ones) are ignored.

BookmarkFS only supports @option{noatime} mounts,
since the ``access time'' attribute of a bookmark necessarily means
``the last time it was accessed from the browser''.
As a bookmark management tool independent from the browser,
BookmarkFS should never update that time automatically.

Nonetheless, the user can still update atime explicitly (e.g. with
@posixfuncmanpage{futimens}).
@end table


@node fsck.bookmarkfs
@section @command{fsck.bookmarkfs}

@example
fsck.bookmarkfs [@var{options}] @var{pathname}
@end example

The @command{fsck.bookmarkfs} program checks and optionally repairs a
BookmarkFS filesystem.

Unlike @command{fsck} on general-purpose filesystems (e.g. ext4),
this program does not check the integrity or validity of a bookmark file --
the underlying filesystem containing the bookmark storage is responsible for
that.
Instead, it checks for bookmark names that are not valid as filename
(e.g. contains slash characters).
@xref{Filesystem Check}.

Available options:

@table @option
@item -o backend=@var{name}
The backend used by the filesystem (@pxref{Backends}).

If this option is not provided, or @var{name} is empty, performs online fsck.

@item -o @@@var{key}[=@var{value}]
A backend-specific option.
This option can be provided multiple times.

@item -o handler=@var{name}
The handler for resolving errors found during fsck
(@pxref{Filesystem-Check Handlers}).

If this option is not provided, or @var{name} is empty,
a built-in handler will be used.
@xref{Built-in Filesystem-Check Handler}.

@item -o %@var{key}[=@var{value}]
A handler-specific option.
This option can be provided multiple times.

@item -o repair
Attempt to repair errors found during fsck.

@quotation Warning
Always backup the bookmarks before repairing, or risk losing your data!
@end quotation

@item -o rl_app=@var{name}
Readline application name in interactive mode.
Defaults to ``fsck.bookmarkfs''.

@item -o type=bookmark|tag|keyword
Subsystem type (@pxref{Hierarchy}).
Defaults to ``bookmark''.

This option is ignored when performing online fsck.

@item -i
Enable interactive mode.
@item -R
Perform fsck on subdirectories recursively.

This option is ignored when performing fsck on tags or keywords.

@item -o no_sandbox
Do not enable sandboxing features (@pxref{Sandboxing}).

@item -o no_landlock
Do not use Landlock for sandboxing.
This option is ignored on non-Linux platforms.

Also @pxref{Disabling Landlock}.

@item -h
Print help text, and then exit.
@item -V
Print version and feature information, and then exit.
@end table


@node mkfs.bookmarkfs
@section @command{mkfs.bookmarkfs}

@example
mkfs.bookmarkfs [@var{options}] @var{pathname}
@end example

The @command{mkfs.bookmarkfs} program creates a BookmarkFS filesystem
on the file specified by @var{pathname}.

Available options:

@table @option
@item -o backend=@var{name}
The backend used by the filesystem (@pxref{Backends}).
This option is mandatory.

@item -o @@@var{key}[=@var{value}]
A backend-specific option.
This option can be provided multiple times.

@item -o force
Overwrite existing files when creating the filesystem.

@item -h
Print help text, and then exit.
@item -V
Print version and feature information, and then exit.
@end table


@node bookmarkctl
@section @command{bookmarkctl}

@example
bookmarkctl @var{subcmd} [@var{args}]
@end example

The @command{bookmarkctl} program is a command-line wrapper for various
I/O controls of a BookmarkFS filesystem.

@example
bookmarkctl permd @var{pathname} @var{op} @var{name1} @var{name2}
@end example

The @command{permd} sub-command re-arranges the order of the directory entries
returned from @code{readdir()} calls.
@xref{Permute Directory Entries}.

The @var{pathname} argument is the path to the directory.
The @var{name1} and @var{name2} arguments are filenames under that directory.

The @var{op} argument is the operation to perform on the directory:

@table @code
@item swap
Exchange the positions of the directory entries represented by @code{name1}
and @code{name2}.

@item move-before
Move the directory entry represented by @code{name1} to the position just
@emph{before} the one represented by @code{name2}.

@item move-after
Move the directory entry represented by @code{name1} to the position just
@emph{after} the one represented by @code{name2}.
@end table

@example
bookmarkctl fsck @var{pathname} @var{op}
@end example

The @command{fsck} sub-command checks for errors within a
BookmarkFS filesystem.
@xref{Filesystem Check}.

The @command{pathname} argument is the path to the directory
to perform checks on.

The @command{op} argument is the operation to perform on the directory:

@itemize @bullet{}
@item @code{list} -- Display a list of errors found under the given directory.
Will not recurse into subdirectories.
@end itemize

For the full fsck functionalities, @pxref{fsck.bookmarkfs}.

@example
bookmarkctl help
@end example

Print help text, and then exit.

@example
bookmarkctl version
@end example

Print version information, and then exit.


@node Filesystem
@chapter The Filesystem

When a BookmarkFS filesystem is mounted using the @command{mount.bookmarkfs}
program, a daemon process acts as a proxy between the kernel (which relays
filesystem requests to FUSE requests) and the backend (which manipulates
actual bookmark data, @pxref{Backends}), thus providing POSIX
(and platform-specific) filesystem API access to bookmarks.

BookmarkFS is designed in the hope that web browser bookmarks
can be managed flexibly using a combination of existing software,
without having to reinvent the wheel.
However, like most other pseudo-filesystems,
it cannot be considered fully POSIX-compliant.
Users should be aware of the limitations when using BookmarkFS.


@node Hierarchy
@section Filesystem Hierarchy

BookmarkFS has multiple subsystems.
Each one appears as a directory under the mountpoint:

@example
@var{$@{mountpoint@}}/bookmarks
@var{$@{mountpoint@}}/tags
@var{$@{mountpoint@}}/keywords
@end example

If the backend does not support a subsystem, the corresponding directory
does not exist.

Currently all subsystem definitions are hard-coded within the
@command{mount.bookmarkfs} program, and cannot be extended by the backend.


@node Bookmarks
@subsection Bookmarks

@example
@var{$@{mountpoint@}}/bookmarks/@var{$@{bookmark_dir...@}}/@var{$@{bookmark@}}
@end example

The ``bookmarks'' subsystem maintains the hierarchical structure, names, URLs
and other information of a bookmark storage.
Each bookmark folder name appears as the filename for directory
@var{$@{bookmark_dir@}}, and each @var{$@{bookmark@}} is a regular file
that refers to a bookmark.

The name of a bookmark file is usually the ``bookmark title'',
which is the name that appears in the browser's bookmark manager.
The content of a bookmark file is usually the URL associated with the bookmark.

Not all bookmark names can be represented as a filename (e.g. contains
slash character; longer than @code{NAME_MAX}; @dots{}).
For a bookmark or bookmark folder with an invalid name, the corresponding file
does not exist on the filesystem.
To deal with such bookmarks, @pxref{Filesystem Check};
or you can instruct the backend to identify bookmarks using GUIDs
instead of titles (and then access the titles via extended attributes).

Some file attributes are used to represent bookmark metadata:

@table @code
@item st_ino
ID of the bookmark (stored as lower bits).

@item st_size
Length of the bookmark URL in bytes.
Always @code{0} for directories.

@item st_atim
Last access time of the bookmark.

@item st_mtim
Last modification time of the bookmark.
@xref{File Modification/Change Time}.
@end table

Additional information of a bookmark or bookmark folder can be accessed via
the extended attributes of the corresponding file, for backends that
supports it (@pxref{Extended Attributes}).


@node Tags
@subsection Tags

@example
@var{$@{mountpoint@}}/tags/@var{$@{tag_dir@}}/@var{$@{bookmark@}}
@end example

The ``tags'' subsystem maintains a many-to-many mapping between bookmarks and
their alternative names.
Each tag name appears as the filename for directory @var{$@{tag_dir@}},
and @var{$@{bookmark@}} 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,
it is unspecified which one appears as an entry for the tag directory.
However, consecutive lookups and @code{readdir()}s should produce consistent
results for that file, provided that it is not renamed or deleted.

Tag files behave differently from traditional hard links.
If the original bookmark file is renamed or deleted,
it may also change accordingly.
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}:

@example C
fd = open("tags/gnu/readline", O_CREAT | O_WRONLY, 0600);
// Oops, fd == -1, errno == EPERM

fd = link("bookmarks/other/readline", "tags/gnu/readline", 0);
// OK!
@end example

Make sure that the two files have identical names, otherwise @code{link()}
fails with @code{EPERM}.


@node Keywords
@subsection Keywords

@example
@var{$@{mountpoint@}}/keywords/@var{$@{keyword_name@}}
@end example

The ``keywords'' subsystem maintains a one-to-one mapping between bookmarks
and their alternative names, independent from tag names.
Each keyword name appears as the filename for regular file
@var{$@{keyword_name@}}, which is a hard link to the bookmark file.
A bookmark directory cannot be associated with a keyword.

To associate a bookmark with a keyword, use @code{link()} like we do with tags.
If the original file is already associated with another keyword,
@code{link()} fails with @code{EEXIST}.


@node Error Codes
@section Error Codes

When a filesystem operation fails, the kernel returns an error code for the
system call.
In addition to common error codes, there's few more in BookmarkFS:

@table @code
@item EPERM
Attempting to perform an unsupported operation.
For example:

@itemize @bullet{}
@item @code{chmod()}, @code{chown()}, and other operations that makes no sense
for web browser bookmarks.
@item Moving a file across subsystems.
@item Creating a bookmark file with a name that is not valid UTF-8
(on Chromium backend).
@end itemize

@item EIO
An unexpected internal error occurred, likely due to a bug in BookmarkFS,
or a corruption in the bookmark storage.

When this error occurs, a log message describing the situation may be printed
to the standard error of the daemon process.
Sometimes this error comes from the kernel-side FUSE implementation,
and there's no error message.

Once this error occurs, behavior of any further operations on the filesystem
is undefined.

@item ESTALE
The file associated with the file descriptor no longer exists.

The error may occur when the underlying bookmark storage has been modified by
another process (e.g. a web browser) after opening a file.

If the filesystem is mounted in exclusive mode, this error should not occur.
@end table

Other BookmarkFS-specific errors may occur.
See the corresponding manual section for details.


@node Extended Attributes
@section Extended Attributes

BookmarkFS uses extended attributes to manage additional information associated
with a bookmark.

Extended attributes is a platform-specific feature.
On Linux, see @linuxmanpage{xattr, 7}.
On FreeBSD, see @freebsdmanpage{extattr, 2}.

All BookmarkFS extended attributes fall under the ``user'' namespace,
which means they have a @code{user.} name prefix on Linux, and should be
accessed with @code{EXTATTR_NAMESPACE_USER} on FreeBSD.
All attributes have a @code{bookmarkfs.} name prefix.

For example, to get the GUID of a bookmark file (Firefox backend):

@example C
// Linux
len = fgetxattr(fd, "user.bookmarkfs.guid", buf, sizeof(buf));

// FreeBSD
len = extattr_get_fd(fd, EXTATTR_NAMESPACE_USER, "bookmarkfs.guid",
        buf, sizeof(buf));
@end example

BookmarkFS does not define any common attributes, neither can users create
arbitrary ones.
The backend decides which attributes are available during initialization,
and all bookmark files share the same set of attributes.


@node Directory Entry Ordering
@section Directory Entry Ordering

POSIX does not specify the ordering of the directory entries retrieved from
the directory stream using @posixfuncmanpage{readdir}.
It only guarantees that if an entry is not added or removed from the directory
after the most recent call to @posixfuncmanpage{opendir} or
@posixfuncmanpage{rewinddir}, that entry is returned once and only once.

This allows filesystem implementations to organize directory entries in a more
relaxed manner.
There could be extra overhead to maintain a predictable ordering of
directory entries, since they may not have a linear structure on modern
on-disk filesystems (e.g. ext4 uses
@linuxdoc{htree, filesystems/ext4/dynamic.html#hash-tree-directories}
for large directories).

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, and let the application
do the sorting.

However, the order of which a bookmark entry appears in the web browser
sometimes does matter.
In BookmarkFS, it is guaranteed to be equivalent to the
directory traversal order.
New entries are appended to the end; removed entries do not affect
the order of other entries.


@node Permute Directory Entries
@subsection Permute Directory Entries

BookmarkFS provides an I/O control for rearranging directory entries:

@example C
#include <bookmarkfs/ioctl.h>

int ioctl (int dirfd, BOOKMARKFS_IOC_PERMD,
        struct bookmarkfs_permd_data const *argp);
@end example

The @code{bookmarkfs_permd_data} structure is defined as:

@example C
struct bookmarkfs_permd_data @{
    enum bookmarkfs_permd_op op;

    char name1[NAME_MAX + 1];
    char name2[NAME_MAX + 1];
@};
@end example

The @code{op} field denotes the operation to perform on the directory:

@table @code
@item BOOKMARKFS_PERMD_OP_SWAP
Exchange the positions of the directory entries represented by @code{name1}
and @code{name2}.

@item BOOKMARKFS_PERMD_OP_MOVE_BEFORE
Move the directory entry represented by @code{name1} to the position just
@emph{before} the one represented by @code{name2}.

@item BOOKMARKFS_PERMD_OP_MOVE_AFTER
Move the directory entry represented by @code{name1} to the position just
@emph{after} the one represented by @code{name2}.
@end table

On success, @code{ioctl()} returns @code{0}.
Otherwise, it returns @code{-1} and sets @code{errno}:

@table @code
@item EACCES
Write or search permission is denied for the directory.

@item EINVAL
@code{op} is not one of the values defined in enum @code{bookmarkfs_permd_op}.

@item EINVAL
@code{name1} or @code{name2} is not a valid filename
(e.g. empty string; contains slash character, @dots{}).

@item ENOENT
The directory does not contain @code{name1} or @code{name2}.

@item EPERM
The backend does not support rearranging entries for this directory.
@end table

To ensure that the order change is visible to further @code{readdir()} calls,
@code{fsync()} or @code{close()} the directory.


@node Filesystem Check
@section Filesystem Check


@node Backends
@chapter Backends

In BookmarkFS, each backend provides a way to manipulate a certain kind of
application bookmarks.

Typically, backends are built into shared libraries, and are installed as:

@example
@var{$@{pkglibdir@}}/backend-@var{$@{short_name@}}@var{$@{shlib_suffix@}}
@end example

Where @var{$@{short_name@}} is the name passed to the frontend program, and
@var{$@{shlib_suffix@}} is the common filename extension for shared library
files on the current platform (e.g. @file{.so} on GNU/Linux and FreeBSD).

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
@section Firefox Backend

The Firefox backend provides access to the bookmark data of the web browser
@uref{https://www.mozilla.org/en-US/firefox/new/, Mozilla Firefox}
and its derivatives, notably @uref{https://www.torproject.org/, Tor Browser}
and @uref{https://librewolf.net/, Librewolf}.

Firefox bookmarks are stored in a SQLite database under the profile directory:

@example
~/.mozilla/firefox/@var{$@{profile_name@}}/places.sqlite
@end example

When mounting the filesystem, this pathname shall be passed as the @var{src}
argument (@pxref{mount.bookmarkfs}).
Actual path for the profile directories may differ across distributions.

Backend-specific options:

@table @option
@item filename=title|guid
Whether to use the bookmark title or GUID as the bookmark file name.
Defaults to ``title''.

A bookmark GUID is a base64url-encoded 128-bit string uniquely associated
with a bookmark or bookmark folder.

When creating a new file:

@table @option
@item title
The GUID is randomly generated by the backend.

@item guid
The filename must be a valid GUID, and must not duplicate with other files
on the same filesystem, otherwise @code{open()} fails with @code{EPERM}.

Also set the GUID string as the bookmark title.
@end table

With @option{filename=title}, the GUID is available as an extended attribute
(@pxref{Extended Attributes}), and vise versa.

@item lock=exclusive|normal
The database connection locking mode for the bookmark storage.
Defaults to ``normal'' when the filesystem is mounted read-only,
``exclusive'' otherwise.

This option corresponds to the
@uref{https://www.sqlite.org/pragma.html#pragma_locking_mode,
@code{locking_mode}} pragma on SQLite.
With @option{lock=exclusive}, other process cannot access the bookmark storage
until the filesystem is dismounted.

The Firefox browser holds an exclusive lock on the database by default.
If you wish to mount the bookmarks while keeping the browser session open,
set the @code{storage.sqlite.exclusiveLock.enabled} browser preference
to @code{false}.

@item assume_title_distinct
If this options is provided, the backend assumes that bookmark names are
distinct under the same bookmark folder.
This option is ignored with @option{filename=guid}.

This option may improve @code{readdir()} performance, however,
making a false assumption results in a directory entry with duplicate names.
It is recommended to perform a full filesystem check (@pxref{Filesystem Check})
on the bookmark storage before mounting with this option.

@end table


@node Chromium
@section Chromium Backend

The Chromium backend provides access to the bookmark data of the web browser
@uref{https://www.chromium.org/Home/, Chromium} and its derivatives,
notably @uref{https://github.com/ungoogled-software/ungoogled-chromium,
ungoogled-chromium}.

Chromium bookmarks are stored in a text file (in JSON format)
under the profile directory:

@example
~/.config/chromium/@var{$@{profile_name@}}/Bookmarks
@end example

When mounting the filesystem, this pathname shall be passed as the @var{src}
argument (@pxref{mount.bookmarkfs}).
Actual path for the profile directories may differ across distributions.

Backend-specific options:

@table @option
@item filename=title|guid
Whether to use the bookmark title or GUID as the bookmark file name.
Defaults to ``title''.

A bookmark GUID is a hex-encoded (``8-4-4-4-12'', lowercase) 128-bit string
uniquely associated with a bookmark or bookmark folder.

When creating a new file:

@table @option
@item title
The GUID is randomly generated by the backend.
It is guaranteed to be a valid version 4 UUID as specified by
@uref{https://datatracker.ietf.org/doc/html/rfc4122, RFC 4122}.

@item guid
The filename must be a valid GUID, and must not duplicate with other files
on the same filesystem, otherwise @code{open()} fails with @code{EPERM}.

Also set the GUID string as the bookmark title.
@end table

With @option{filename=title}, the GUID is available as an extended attribute
(@pxref{Extended Attributes}), and vise versa.

@item watcher=native|fallback|none
The file watcher to use for the bookmark storage.
Defaults to ``native'' when the filesystem is mounted read-only,
``none'' otherwise.

@table @option
@item native
Watch for file changes using platform-specific features.

On Linux, @linuxmanpage{fanotify, 7} is used.
Requires kernel version 5.13 or later for unprivileged users.
@linuxmanpage{inotify, 7} does not have this limitation, however,
it is incompatible with our sandboxing design.

On FreeBSD, @freebsdmanpage{kevent, 2} with @code{EVFILT_VNODE} is used.

@item fallback
Watch for file changes by checking @code{st_ino} and @code{st_mtim} attributes
with @code{fstatat()} periodically.

Less efficient than ``native'' implementations, but should work on any
POSIX-compatible system.

@item none
Do not watch for file changes.

With @option{watcher=none}, changes on the bookmark storage are not visible
to the filesystem.
@end table
@end table

This backend does not scale well with large bookmark storage,
since it keeps everything in memory, and has to parse the entire JSON file
whenever a reload is required.

Another limitation is the lack of tags (@pxref{Tags}) and keywords
(@pxref{Keywords}) support.
Chromium does not have such concepts.


@node Backend API
@section Backend API


@node Filesystem-Check Handlers
@chapter Filesystem-Check Handlers


@node Built-in Filesystem-Check Handler
@section Built-in Handler


@node Tcl-Based Filesystem-Check Handler
@section Tcl-Based Handler


@node Filesystem-Check Handler API
@section Handler API


@node General Index
@appendix General Index

@printindex cp


@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi


@bye