BookmarkFS User Manual ¶

1.1 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 FUSE 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 low-level API. For a similar reason, WinFsp won’t work if you’re trying to port BookmarkFS to Microsoft Windows.

1.2 Limitations on FreeBSD ¶

Currently, the FreeBSD fusefs(5) implementation does not support FUSE_IOCTL. All custom ioctl(2) calls on a FUSE filesystem fail with ENOTTY without the requests being sent to the FUSE server.

Thus, BookmarkFS features that depend on ioctl() do not work on FreeBSD, which includes:

• Permute directory entries (see Permute Directory Entries)
• Online filesystem check (see Online Filesystem Check)

Meanwhile, FreeBSD does not support FUSE_READDIRPLUS and directory entry caching, which makes listing directory entries less efficient.

1.3 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:

• access local files other than the bookmark storage
• establish socket connections
• execute other files

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.

Examples of what “untrusted input” may include:

• Bookmark files that are not created by the user using a trusted program (e.g., a file obtained from some random person on the internet).
• 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.

On Linux, sandboxing is achieved using seccomp(2) and landlock(7). On FreeBSD, capsicum(4) is used.

1.4 The Utility Library ¶

The BookmarkFS Utility Library implements various common utility functions. It is used internally by most of BookmarkFS’s components, including the backends (see Backends) and the mount.bookmarkfs program.

Typically, the library is built into a shared object, and installed as:

${libdir}/bookmarkfs_util${shlib_suffix}

${libdir}

Presumably ${prefix}/lib. See The Uniform Naming Scheme in GNU Automake.

${shlib_suffix}

The common filename extension for shared library files on the current platform (e.g., .so on GNU/Linux and FreeBSD).

Public headers are installed under ${pkgincludedir} (presumably ${prefix}/include/bookmarkfs). To use the library functions, include the following headers as needed:

hash.h

Non-cryptographic hash function.

hashmap.h

A simple hashtable implementation.

prng.h

Non-cryptographic pseudo-random number generator.

sandbox.h

A simple sandbox implementation. See Sandboxing.

version.h

Get version and feature information of the library.

watcher.h

Single-file filesystem watcher.

Usage of the library functions is rather simple and straightforward, thus there’s currently no dedicated manual sections. Refer to the comments in the corresponding header files for details.

2.1 mount.bookmarkfs ¶

The mount.bookmarkfs program mounts a BookmarkFS filesystem.

mount.bookmarkfs [options] src target

src

The bookmark storage, presumably the pathname of a regular file that contains bookmark data.

The exact interpretation of this option is backend-defined.

target

Pathname of the directory where the filesystem shall be mounted to (i.e., the “mountpoint”).

Files under the filesystem are assigned ownership according to the effective user ID and group ID of the calling process. On FreeBSD, you may wish to set the ‘vfs.usermount’ sysctl(8) to 1 for unprivileged mounts.

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

Options:

-o backend=name

The backend used by the filesystem (see Backends). This option is mandatory.

Alternatively, name could be specified in ‘lib_path:sym_name’ format, where:

lib_path 

Presumably the pathname to the backend library. Its exact interpretation is equivalent to the first argument for dlopen(3p).

sym_name

See Backend Symbol Name Format.

-o @key[=value]

A backend-specific option. This option can be provided multiple times.

-o accmode=mode

File access mode. Defaults to 0700.

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

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

-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:

modification time

ctime only updates when mtime does.

change time

ctime updates normally; mtime always updates when ctime does, even if the file content is not modified.

This behavior may be inefficient, but makes applications that depend on ctime less fragile.

The kernel may automatically update and cache ctime, making it more “correct” than what we expect. However, this behavior should not be relied upon.

-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).

-o file_max=bytes

Max file size limit. Defaults to 32768.

This limit also applies to extended attribute values.

-o no_sandbox

Do not enable sandboxing features (see Sandboxing).

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

-F

Stay in the foreground, do not daemonize.

-h

Print help text, and then exit.

-V

Print version and feature information, and then exit.

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

-o rw

Mount the filesystem read/write.

Warning: Always backup the bookmark storage before mounting it read/write, or risk losing your data!

By default, the filesystem is mounted read-only. This behavior won’t change in the future, due to the hackish nature of most BookmarkFS backends.

When mounted read/write, other process must not write to the underlying bookmark storage, otherwise data corruption may occur.

-o debug

Set libfuse log level to FUSE_LOG_DEBUG. Log messages related to each FUSE request will be printed to standard error.

-o fsname=name

Name for the filesystem. Defaults to the backend name.

This name is equivalent to the fs_spec field in fstab(5), and appears as the ‘SOURCE’ column in findmnt(8) output.

-o atime,diratime,relatime

These options (and other atime-related ones) are ignored.

BookmarkFS only supports 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 is still allowed to explicitly update atime (e.g., with futimens(3p)).

2.2 fsck.bookmarkfs ¶

The fsck.bookmarkfs program checks and optionally repairs a BookmarkFS filesystem.

fsck.bookmarkfs [options] pathname

Filesystem check on BookmarkFS has a different purpose compared to on-disk filesystems. See Filesystem Check.

Depending on the options specified, filesystem check works either in online or offline mode:

Online Mode

In online mode, fsck is performed on a mounted BookmarkFS filesystem using ioctl() (see Online Filesystem Check).

The pathname argument refers to the directory to operate on.

Offline Mode

In offline mode, fsck is performed directly on the bookmark storage via the corresponding backend.

The pathname argument is the path to the bookmark storage, equivalent to the src argument given to mount.bookmarkfs.

Alternatively, pathname could be specified in ‘src:dir’ format, where dir refers to the directory to operate on, relative to the root directory of the subsystem.

Options:

-o backend=name

The backend used by the filesystem (see Backends).

Value of name could be specified in an alternative format. See Alternative Backend Name.

If this option is not provided, or name is empty, performs online fsck. Otherwise perform offline fsck.

-o @key[=value]

A backend-specific option. This option can be provided multiple times.

-o handler=name

The handler for resolving errors found during fsck (see Filesystem-Check Handlers).

Alternatively, name could be specified in ‘lib_path:sym_name’ format, where:

lib_path 

Presumably the pathname to the fsck handler library. Its exact interpretation is equivalent to the first argument for dlopen(3p).

sym_name

See Filesystem-Check Handler Symbol Name Format.

If this option is not provided, or name is empty, a built-in handler will be used. See Built-in Handler.

-o %key[=value]

A handler-specific option. This option can be provided multiple times.

-o repair

Attempt to repair errors found during fsck.

Warning: Always backup the bookmark storage before repairing, or risk losing your data!

-o rl_app=name

Readline application name in interactive mode. Defaults to ‘fsck.bookmarkfs’.

See Conditional Init Constructs in GNU Readline Library.

-o type=bookmark|tag|keyword

Subsystem type (see Filesystem Hierarchy). Defaults to ‘bookmark’.

This option is ignored when performing online fsck.

-i

Enable interactive mode.

-R

Perform fsck on subdirectories recursively.

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

-o no_sandbox

Do not enable sandboxing features (see Sandboxing).

-o no_landlock

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

Also see Disabling Landlock.

-h

Print help text, and then exit.

-V

Print version and feature information, and then exit.

2.3 mkfs.bookmarkfs ¶

The mkfs.bookmarkfs program creates a new BookmarkFS filesystem.

mkfs.bookmarkfs [options] pathname

pathname

The underlying bookmark storage for the new filesystem.

This option is equivalent to the src argument for mount.bookmarkfs.

Options:

-o backend=name

The backend used by the filesystem (see Backends). This option is mandatory.

Value of name could be specified in an alternative format. See Alternative Backend Name.

-o @key[=value]

A backend-specific option. This option can be provided multiple times.

-o force

If the file referred to by pathname already exists, overwrite it.

-h

Print help text, and then exit.

-V

Print version and feature information, and then exit.

2.4 bookmarkctl ¶

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

bookmarkctl subcmd [args]

Sub-commands:

permd

Re-arranges the order of the directory entries obtained from readdir(). See Permute Directory Entries.

bookmarkctl permd pathname op name1 name2

pathname

Path to the directory.

name1

name2

Filename of entries under the directory.

op

Operation to perform on the directory:

‘swap’

Exchange the positions of the directory entries represented by name1 and name2.

‘move-before’

Move the directory entry represented by name1 to the position just before the one represented by name2.

‘move-after’

Move the directory entry represented by name1 to the position just after the one represented by name2.

fsck

Check for errors within a BookmarkFS filesystem. See Filesystem Check.

bookmarkctl fsck pathname op

pathname

Path to the directory to perform checks on.

op

Operation to perform on the directory:

‘list’

Display a list of errors found under the given directory. Will not recurse into subdirectories.

For the full fsck functionalities, see fsck.bookmarkfs.

help

Print help text, and then exit.

version

Print version information, and then exit.

3.1 Filesystem Hierarchy ¶

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

${mountpoint}/bookmarks
${mountpoint}/tags
${mountpoint}/keywords

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

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

• Bookmarks
• Tags
• Keywords

${mountpoint}/bookmarks/${bookmark_dir...}/${bookmark}

${mountpoint}/tags/${tag_dir}/${bookmark}

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!

${mountpoint}/keywords/${keyword_name}

3.2 Error Codes ¶

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

EPERM

Attempting to perform an unsupported operation. For example:

• chmod(), chown(), and other operations that makes no sense for web browser bookmarks.
• Moving a file across subsystems.
• Creating a bookmark file with a name that is not valid UTF-8 (on Chromium backend).

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.

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.

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

3.3 Extended Attributes ¶

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

Extended attributes is a platform-specific feature. On Linux, see xattr(7). On FreeBSD, see extattr(2).

All BookmarkFS extended attributes fall under the “user” namespace, which means they have a ‘user.’ name prefix on Linux, and should be accessed with EXTATTR_NAMESPACE_USER on FreeBSD. All attributes have a ‘bookmarkfs.’ name prefix.

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

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

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

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.

3.4 Directory Entries ¶

The ‘.’ and ‘..’ entries

POSIX consider ‘.’ and ‘..’ as “special” filenames, which must refer to the current and parent directory, if they exist.

These entries are optional, and BookmarkFS does not support them, for the sake of simplicity. Additionally, bookmarks with such names are hidden from the filesystem until fixed with fsck (see Filesystem Check).

Ordering of directory entries

POSIX does not specify the ordering of the directory entries retrieved from the directory stream using readdir(3p). It only guarantees that if an entry is not added or removed from the directory after the most recent call to opendir(3p) or rewinddir(3p), 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 htree 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.

To change the ordering of directory entries, see Permute Directory Entries.

• Permute Directory Entries

#include <bookmarkfs/ioctl.h>

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

struct bookmarkfs_permd_data {
    enum bookmarkfs_permd_op op;

    char name1[NAME_MAX + 1];
    char name2[NAME_MAX + 1];
};

3.5 Filesystem Check ¶

On-disk filesystems may suffer from data corruption due to power loss or hardware failures, thus they usually provide a “filesystem check” mechanism to detect and fix those problems.

As a pseudo-filesystem, BookmarkFS does not check for data integrity, and “filesystem check” is given a new purpose: To check if a bookmark name is valid as a filename, and “repair” (rename) it if it isn’t.

A POSIX-compliant filesystem has various restrictions regarding filenames:

• must not contain ‘/’ characters
• must not be empty or longer than NAME_MAX
• must not duplicate with another file in the same directory
• ‘.’ and ‘..’ must refer to the current and parent directory

It is commonplace for bookmark names to not meet such criteria, thus a filesystem check is often necessary when switching to BookmarkFS from another bookmark management software.

• Online Filesystem Check

#include <bookmarkfs/ioctl.h>

int ioctl (int dirfd, BOOKMARKFS_IOC_FSCK_NEXT,
        struct bookmarkfs_fsck_data *argp);

int ioctl (int dirfd, BOOKMARKFS_IOC_FSCK_APPLY,
        struct bookmarkfs_fsck_data *argp);

int ioctl (int dirfd, BOOKMARKFS_IOC_FSCK_REWIND);

struct bookmarkfs_fsck_data {
    uint64_t id;
    uint64_t extra;
    char     name[NAME_MAX + 1];
};

4.1 Firefox Backend ¶

The Firefox backend provides access to the bookmark data of the web browser Mozilla Firefox and its derivatives, notably Tor Browser and Librewolf.

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

~/.mozilla/firefox/${profile_name}/places.sqlite

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

Backend name: ‘firefox’.

Backend-specific options (mount.bookmarkfs only):

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:

‘title’

The GUID is randomly generated by the backend.

‘guid’

The filename must be a valid GUID, and must not duplicate with other files on the same filesystem, otherwise open() or mkdir() fails with EPERM.

Also set the GUID string as the bookmark title.

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 locking_mode pragma on SQLite. With 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 storage.sqlite.exclusiveLock.enabled browser preference to false.

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 filename=guid.

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

If launched from fsck.bookmarkfs, all backend-specific options are ignored, and always enforces the lock=exclusive option.

Backend-specific options (mkfs.bookmarkfs only):

date_added=timestamp

File creation time for the bookmark root directories. Defaults to the current time.

Format of timestamp is equivalent to the ‘date_added’ extended attribute (see below).

Extended attributes:

‘title’

The bookmark title. Only available with filename=guid.

This value is allowed be set to any string that does not contain a NUL character, and does not have to be valid as a filename.

‘guid’

The bookmark GUID. Only available with filename=title.

‘description’

An arbitrary text associated with the bookmark.

Usually, when bookmarking a page in the browser, this value is set to the content attribute of the <meta> element whose name is ‘description’.

‘date_added’

The bookmark creation time.

Value is a decimal integer representing number of microseconds since the Unix epoch.

4.2 Chromium Backend ¶

The Chromium backend provides access to the bookmark data of the web browser Chromium and its derivatives, notably ungoogled-chromium.

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

~/.config/chromium/${profile_name}/Bookmarks

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

Backend name: ‘chromium’.

Backend-specific options (mount.bookmarkfs only):

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 128-bit string uniquely associated with a bookmark or bookmark folder. The GUID string has a “8-4-4-4-12” format, while all alphabetic characters are in lowercase. For example:

0bc5d13f-2cba-5d74-951f-3f233fe6c908

When creating a new file:

‘title’

The GUID is randomly generated by the backend. It is guaranteed to be a valid version 4 UUID as specified by RFC 4122.

‘guid’

The filename must be a valid GUID, and must not duplicate with other files on the same filesystem, otherwise open() or mkdir() fails with EPERM.

Also set the GUID string as the bookmark title.

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.

‘native’

Watch for file changes using platform-specific features:

Linux

fanotify(7) is used. Requires kernel version 5.13 or later for unprivileged users.

inotify(7) does not have this limitation, however, it is incompatible with our sandboxing design.

FreeBSD

kevent(2) with EVFILT_VNODE is used.

‘fallback’

Watch for file changes by checking st_ino and st_mtim attributes with fstatat() periodically.

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

‘none’

Do not watch for file changes.

With watcher=none, changes on the bookmark storage are not visible to the filesystem.

If launched from fsck.bookmarkfs, all backend-specific options are ignored, and always enforces the watcher=none option.

Backend-specific options (mkfs.bookmarkfs only):

date_added=timestamp

File creation time for the bookmark root directories. Defaults to the current time.

Format of timestamp is equivalent to the ‘date_added’ extended attribute (see below).

Extended attributes:

‘title’

The bookmark title. Only available with filename=guid.

This value is allowed be set to any UTF-8 string that does not contain a NUL character, and does not have to be valid as a filename.

‘guid’

The bookmark GUID. Only available with filename=title.

‘date_added’

The bookmark creation time.

Value is a decimal integer representing number of microseconds since the Windows FILETIME epoch (134774 days ahead of the Unix epoch).

Notable limitations:

• Does not scale well with large bookmark storage, since everything is kept in memory, and the entire JSON file has to be parsed whenever a reload is required.
• No support for tags (see Tags) and keywords (see Keywords), since Chromium does not have such concepts.

4.3 Backend API ¶

The Backend API specifies how a BookmarkFS backend communicates with a frontend program (e.g., mount.bookmarkfs).

Warning: Currently BookmarkFS is experimental. The Backend API may change drastically without prior notice.

To implement the Backend API, a backend library should expose a symbol with the following name:

bookmarkfs_backend_${name}

Where ${name} is equivalent to the value given to the -o backend=name option of frontend programs.

The symbol should name a data object identifier of the following type:

#include <bookmarkfs/backend.h>

struct bookmarkfs_backend {
    bookmarkfs_backend_create_func  *backend_create;
    bookmarkfs_backend_destroy_func *backend_destroy;
    bookmarkfs_backend_info_func    *backend_info;
    bookmarkfs_backend_init_func    *backend_init;
    bookmarkfs_backend_mkfs_func    *backend_mkfs;
    bookmarkfs_backend_sandbox_func *backend_sandbox;

    bookmarkfs_bookmark_get_func    *bookmark_get;
    bookmarkfs_bookmark_list_func   *bookmark_list;
    bookmarkfs_bookmark_lookup_func *bookmark_lookup;

    bookmarkfs_bookmark_create_func  *bookmark_create;
    bookmarkfs_bookmark_delete_func  *bookmark_delete;
    bookmarkfs_bookmark_fsck_func    *bookmark_fsck;
    bookmarkfs_bookmark_permute_func *bookmark_permute;
    bookmarkfs_bookmark_rename_func  *bookmark_rename;
    bookmarkfs_bookmark_set_func     *bookmark_set;
    bookmarkfs_bookmark_sync_func    *bookmark_sync;

    bookmarkfs_object_free_func *object_free;
};

Each field is a function pointer provided by the backend. Some can be optional and set to NULL, if the backend does not support the corresponding features.

• Initialize Backend
• Get Backend Information
• Create Backend Context
• Destroy Backend Context
• Lookup Bookmark

typedef int (bookmarkfs_backend_init_func) (
    uint32_t flags
);

typedef void (bookmarkfs_backend_info_func) (
    uint32_t flags
);

typedef int (bookmarkfs_backend_create_func) (
    struct bookmarkfs_backend_conf const  *conf,
    struct bookmarkfs_backend_create_resp *resp
);

typedef void (bookmarkfs_backend_destroy_func) (
    void *backend_ctx
);

typedef int (bookmarkfs_bookmark_lookup_func) (
    void                            *backend_ctx,
    uint64_t                         id,
    char const                      *name,
    uint32_t                         flags,
    struct bookmarkfs_bookmark_stat *stat_buf
);

5.1 Built-in Handler ¶

The built-in filesystem-check handler is linked into the fsck.bookmarkfs program. It has minimal functionalities, but is capable enough to handle most common fsck scenarios.

Handler-specific options:

prompt=str

Readline prompt string. Defaults to ‘% ’.

This option is ignored in non-interactive mode.

translit=char

Transliterate bad (‘/’) characters into char (must be a single ASCII character). Defaults to ‘_’.

For each bookmark entry, the built-in handler prints a message to standard output explaining why the bookmark name is invalid.

When the -o repair option is given, the handler renames the bookmark according to the following rules:

BOOKMARKFS_FSCK_RESULT_NAME_DUPLICATE

Append a ‘_${counter}’ suffix to the name, where ${counter} is a self-incrementing 32-bit integer in decimal format.

If appending the suffix would exceed max name length, truncate the name first.

BOOKMARKFS_FSCK_RESULT_NAME_BADCHAR

Transliterate the bad character into another character.

BOOKMARKFS_FSCK_RESULT_NAME_BADLEN

If the name is too long, truncate it to NAME_MAX bytes.

If the name is empty, see below:

BOOKMARKFS_FSCK_RESULT_NAME_DOTDOT

BOOKMARKFS_FSCK_RESULT_NAME_INVALID

Rename to ‘fsck-${id}’, where ${id} is the bookmark ID in decimal format.

In interactive mode, the handler prompts the user before applying the rename. The user may issue a command to indicate what to do with each entry:

p

Print the ID and new name of current entry.

a[-]

Apply the proposed rename for the current entry.

e[-] new_name

Change the proposed rename to new_name and then apply.

c

Continue to the next entry.

s[-]

Skip current directory.

S[-]

Skip current directory and all subdirectories.

r[-]

Rewind current directory.

R[-]

Rewind all.

w[-]

Save applied changes.

q

Save applied changes and quit.

The optional ‘-’ suffix inhibits the default behavior of continuing to the next entry, after the command completes successfully.

5.2 Tcl-Based Handler ¶

The Tcl-based filesystem-check handler allows fsck entries to be handled via Tcl scripting.

Handler name: ‘tcl’.

Handler-specific options:

script=path

Path to the Tcl script file. This option is mandatory.

The script is evaluated once after interpreter initialization. The evaluation result will be used as the command name for later executions.

The following variables are set before script evaluation:

$::bookmarkfs::fsck::isInteractive

Equals to 1 if the -i option is given to fsck.bookmarkfs, 0 otherwise.

$::bookmarkfs::fsck::isReadonly

Equals to 0 if the -o repair option is given to fsck.bookmarkfs, 1 otherwise.

unsafe

Enable unsafe Tcl interpreter features.

Should be used in combination with the -o no_sandbox option if you wish to access extra system resources (e.g., open local files).

Without this option, the Tcl interpreter has limited functionalities as if created with interp create -safe. See Safe Interpreters.

Each time fsck.bookmarkfs finds an entry, or completes a handler-initiated operation, the command returned from the script is executed with a single list argument. The first element of the list is an integer indicating the reason for this handler call:

$::bookmarkfs::fsck::result::nameDuplicate

$::bookmarkfs::fsck::result::nameBadChar

$::bookmarkfs::fsck::result::nameBadLen

$::bookmarkfs::fsck::result::nameDotDot

$::bookmarkfs::fsck::result::nameInvalid

See Filesystem-Check Result Code for the meaning of each value.

The second element is a list of information about the current entry:

0. The bookmark ID
1. Extra information regarding the invalid name, equivalent to the extra field in structure bookmarkfs_fsck_data.
2. Name of the bookmark
3. ID of the parent directory

-1

If the command is being executed for the first time, or the previous execution returns $::bookmarkfs::fsck::handler::next, this value never appears.

If the previous execution of the command returns $::bookmarkfs::fsck::handler::userInput, the second element of the list is a string of user input.

Otherwise, this value indicates that the previous operation is successfully performed on the entry.

The command should return a list indicating the operation to perform on the entry. First element of the list should be one of the following values:

$::bookmarkfs::fsck::handler::next

Continue to the next entry.

$::bookmarkfs::fsck::handler::apply

Apply change for the current entry. Not available in read-only mode.

Second element of the list should be a string for the new name of the bookmark.

$::bookmarkfs::fsck::handler::userInput

Request for user input. Only available in interactive mode.

Second element of the list should be a string for Readline prompt, equivalent to the prompt=str option of the built-in handler.

$::bookmarkfs::fsck::handler::save

Save applied changes.

$::bookmarkfs::fsck::handler::stop

Save applied changes and quit.

Once this value is returned, the command will never be executed again.

$::bookmarkfs::fsck::handler::rewind

Rewind current directory.

$::bookmarkfs::fsck::handler::skip

Skip current directory.

$::bookmarkfs::fsck::handler::skipChildren

Skip current directory and all subdirectories.

$::bookmarkfs::fsck::handler::reset

Rewind all.

Here is an example Tcl script that simply prints each fsck entry (requires the unsafe option):

chan configure stdout -encoding utf-8
coroutine whatever apply {{} {
    set args [yield [info coroutine]]
    while 1 {
        lassign $args why data
        if {$why > -1} {
            lassign $data id extra name parent
            puts "id: $id, extra: $extra, name: $name, parent: $parent"
        }
        set args [yield [list $::bookmarkfs::fsck::handler::next]]
    }
}}

5.3 Handler API ¶

The Filesystem-Check Handler API specifies how a fsck handler communicates with fsck.bookmarkfs.

Warning: Currently BookmarkFS is experimental. The Handler API may change drastically without prior notice.

To implement the Filesystem-Check Handler API, a fsck handler library should expose a symbol with the following name:

bookmarkfs_fsck_handler_${name}

Where ${name} is equivalent to the value given to the -o handler=name option of fsck.bookmarkfs.

The symbol should name a data object identifier of the following type:

#include <bookmarkfs/fsck_handler.h>

struct bookmarkfs_fsck_handler {
    bookmarkfs_fsck_handler_info_func *info;

    bookmarkfs_fsck_handler_create_func  *create;
    bookmarkfs_fsck_handler_destroy_func *destroy;

    bookmarkfs_fsck_handler_run_func *run;
};

Each field is a function pointer provided by the fsck handler. Some can be optional and set to NULL, if the backend does not support the corresponding features.

• Get Handler Information
• Create Handler Context
• Destroy Handler Context
• Run Handler

typedef void (bookmarkfs_fsck_handler_info_func) (
    uint32_t flags
);

typedef int (bookmarkfs_fsck_handler_create_func) (
    struct bookmarkfs_conf_opt const  *opts,
    uint32_t                           flags,
    void                             **handler_ctx_ptr
);

typedef void (bookmarkfs_fsck_handler_destroy_func) (
    void *handler_ctx
);

typedef int (bookmarkfs_fsck_handler_run_func) (
    void                               *handler_ctx,
    int                                 why,
    union bookmarkfs_fsck_handler_data *data
);