BookmarkFS User Manual ¶

3.1.1 Bookmarks ¶

The “bookmarks” subsystem maintains the hierarchical structure, names, URLs and other information of a bookmark storage.

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

Each bookmark folder name appears as the filename for directory ${bookmark_dir}, and each ${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. For a bookmark or bookmark folder with an invalid name, the corresponding file is not visible to lookups and readdir() calls. To deal with such bookmarks, see 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:

st_ino

ID of the bookmark (stored as lower bits).

st_size

Length of the bookmark URL in bytes. Always 0 for directories.

st_atim

Last access time of the bookmark.

st_mtim

Last modification time of the bookmark. See Last Modification/Change Time.

Additional information of a bookmark or bookmark folder can be accessed via the extended attributes of the corresponding file, for backends that supports it. See Extended Attributes.

3.1.2 Tags ¶

The “tags” subsystem maintains a many-to-many mapping between bookmarks and their alternative names.

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

Each tag name appears as the filename for directory ${tag_dir}, and ${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 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 associated bookmark file of a tag is renamed or deleted, it may 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 link(3p):

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!

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

3.1.3 Keywords ¶

The “keywords” subsystem maintains a one-to-one mapping between bookmarks and their alternative names, independent from tag names.

${mountpoint}/keywords/${keyword_name}

Each keyword name appears as the filename for regular file ${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 link(3p) like we do with tags. If the original file is already associated with another keyword, link() fails with EEXIST.

3.4.1 Permute Directory Entries ¶

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

struct bookmarkfs_permd_data permd_data = { /* ... */ };

status = ioctl(dirfd, BOOKMARKFS_IOC_PERMD, &permd_data);
// ...

The bookmarkfs_permd_data structure is defined as:

#include <bookmarkfs/ioctl.h>

struct bookmarkfs_permd_data {
    enum bookmarkfs_permd_op op;

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

The op field denotes the operation to perform on the directory:

BOOKMARKFS_PERMD_OP_SWAP

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

BOOKMARKFS_PERMD_OP_MOVE_BEFORE

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

BOOKMARKFS_PERMD_OP_MOVE_AFTER

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

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

EACCES

Write or search permission is denied for the directory.

EINVAL

op is not one of the values defined in enum bookmarkfs_permd_op.

EINVAL

name1 or name2 is not a valid filename (e.g., empty string; contains ‘/’ character).

ENOENT

The directory does not contain entries named name1 or name2.

ENOTTY

The kernel does not support FUSE_IOCTL. See Limitations on FreeBSD.

EPERM

The backend does not support rearranging entries for this directory.

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

3.5.1 Online Filesystem Check ¶

BookmarkFS provides I/O controls to perform online filesystem checks:

struct bookmarkfs_fsck_data fsck_data = { /* ... */ };

result = ioctl(dirfd, BOOKMARKFS_IOC_FSCK_NEXT, &fsck_data);
// ...
result = ioctl(dirfd, BOOKMARKFS_IOC_FSCK_APPLY, &fsck_data);
// ...
result = ioctl(dirfd, BOOKMARKFS_IOC_FSCK_REWIND);
// ...

The bookmarkfs_fsck_data structure is defined as:

#include <bookmarkfs/ioctl.h>

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

Filesystem-check commands:

BOOKMARKFS_IOC_FSCK_NEXT

Find the next bookmark with invalid name under the directory.

On success, ioctl() updates fsck_data, and returns one of the values defined in enum bookmarkfs_fsck_result:

BOOKMARKFS_FSCK_RESULT_END

There are no more bookmarks with invalid name under the directory.

Fields in fsck_data have unspecified values.

BOOKMARKFS_FSCK_RESULT_NAME_DUPLICATE

The bookmark name duplicates with another bookmark which appears earlier in the directory stream.

Value of extra is the ID of the other bookmark.

BOOKMARKFS_FSCK_RESULT_NAME_BADCHAR

The bookmark contains a bad character (i.e., the ASCII ‘/’ character).

Value of extra is the byte offset where the bad character first appears in name.

BOOKMARKFS_FSCK_RESULT_NAME_BADLEN

The bookmark name is either longer than NAME_MAX, or an empty string.

Value of extra is the length of the bookmark name, and name is truncated if longer than NAME_MAX.

BOOKMARKFS_FSCK_RESULT_NAME_DOTDOT

The bookmark name is either ‘.’ or ‘..’.

Value of extra is unspecified.

On failure, ioctl() returns -1, and sets errno.

BOOKMARKFS_IOC_FSCK_APPLY

“Repair” a bookmark by renaming it.

The id field must be set to a value previously obtained from BOOKMARKFS_IOC_FSCK_NEXT with the same dirfd, otherwise the behavior is undefined.

The name field should be set to the new name for the bookmark. The extra field is unused.

On success, ioctl() updates fsck_data, and returns one of the values defined in enum bookmarkfs_fsck_result, like with BOOKMARKFS_IOC_FSCK_NEXT. Additionally, it may also return:

BOOKMARKFS_FSCK_RESULT_NAME_INVALID

The new name is not a valid bookmark name.

Value of extra is a backend-specific reason code explaining why the bookmark name is invalid. It may equal to one of the following predefined values:

BOOKMARKFS_NAME_INVALID_REASON_NOTUTF8

The name is not valid UTF-8.

On failure, ioctl() returns -1, and sets errno:

EACCES

Write or search permission is denied for the directory.

To ensure that the rename is visible to further lookups and readdir() calls, fsync() or close() the directory.

BOOKMARKFS_IOC_FSCK_REWIND

Reset the fsck state for the directory.

Further BOOKMARKFS_IOC_FSCK_NEXT requests will start from the beginning of the directory stream.

On success, ioctl() returns 0. Otherwise, it returns -1, and sets errno.

Common error codes for all filesystem-check ioctls:

ENOTTY

The kernel does not support FUSE_IOCTL. See Limitations on FreeBSD.

EPERM

The backend does not support fsck for this directory.

4.3.1 General Information ¶

Multithreading

Currently, all BookmarkFS programs are single-threaded, and backend functions are called sequentially. This is an intended design to keep BookmarkFS simple. Multithreading may help with performance in some scenarios, but not much, and we choose not to bother with it.

A downside of the this design is that backends should refrain from spending too much time in a function, especially waiting for I/O. Once a backend function blocks, the entire filesystem hangs. Future iterations of the Backend API may introduce event notification mechanisms to improve the situation.

Sometimes a backend may wish to use multithreading internally for whatever reason. If it does, a few more precautions should be taken in mind:

• The SIGINT, SIGTERM and SIGHUP signals should be blocked with pthread_sigmask(3p) for the child threads. If a signal is delivered to a child thread, the program may not be terminated promptly, since libfuse relies on EINTR to break out of the event loop.

Backend Contexts ¶

A backend context maintains internal states for manipulating a specific bookmark storage.

Each BookmarkFS filesystem mounted by mount.bookmarkfs is backed by a backend context. The context is created before mount, and destroyed after dismount. Backend functions that operate on a single context accept an argument (usually named backend_ctx) which refers to the context.

Callback Functions

Some backend functions (e.g., bookmark_get) accept a function pointer argument, usually named callback, to be invoked by the backend.

It is guaranteed that backend functions are never called from within a callback function.

Exclusive Mode ¶

If exclusive mode is enabled for a backend context, modifications to the corresponding bookmark storage should only be performed by calling backend functions on the current context. If the bookmark storage is modified by other means, filesystem and backend behavior is undefined.

Frontend programs may perform optimizations based on this assumption.

The backend decides whether exclusive mode should be enabled for a context during backend_create (see Create Backend Context), by setting the BOOKMARKFS_BACKEND_EXCLUSIVE response flag.

Error Codes

Some backend functions return an error code on failure instead of just -1.

For backend functions analogous to the corresponding filesystem calls, the error code should honor POSIX as well as platform-specific conventions. For example:

• When replacing a non-empty directory with bookmark_rename, the function should fail with EEXIST or ENOTEMPTY as specified in rename(3p).
• When trying to get/set the value of a non-existent extended attribute, the function should fail with ENODATA on Linux, and ENOATTR on FreeBSD. See Extended Attributes.

Also see Error Codes for BookmarkFS-specific error codes.

A backend function may also return other error codes which it sees fit, however, they should be chosen carefully. A bad error code may confuse filesystem users or even break applications.

4.3.2 Initialize Backend ¶

The backend_init function is called before any other functions (except for backend_info). If not NULL, it is guaranteed to be called exactly once throughout the lifetime of the process.

Type of the backend_init function is defined as:

typedef int (bookmarkfs_backend_init_func) (
    uint32_t flags
);

Function arguments:

flags

A bit array of the following flags:

BOOKMARKFS_BACKEND_LIB_READY

Indicates that the utility library is already initialized. See The Utility Library.

Some frontend programs use the utility library. If they do, they always initialize it before initializing the backend. The utility library must not be initialized multiple times, otherwise the behavior is undefined.

BOOKMARKFS_FRONTEND_FSCK

BOOKMARKFS_FRONTEND_MOUNT

BOOKMARKFS_FRONTEND_MKFS

Denotes the frontend program that launches the backend. These flags are mutually exclusive.

The function should return 0 on success, and -1 on error.

4.3.3 Get Backend Information ¶

The backend_info function is called to print information about the backend. It can be NULL.

When this function is called, it should write a human-readable message of the corresponding information to standard output.

Type of the backend_info function is defined as:

typedef void (bookmarkfs_backend_info_func) (
    uint32_t flags
);

Function arguments:

flags

A bit array of the following flags:

BOOKMARKFS_BACKEND_INFO_HELP

Indicates that the function should print a help message. Mutually exclusive with BOOKMARKFS_BACKEND_INFO_VERSION.

The message should contain a brief description of this backend, as well as a list of backend-specific options.

BOOKMARKFS_BACKEND_INFO_VERSION

Indicates that the function should print a version message. Mutually exclusive with BOOKMARKFS_BACKEND_INFO_HELP.

In addition to the version number, the version message may contain dependency versions, compile-time options, and other information that can be used to determine a specific version of the backend.

BOOKMARKFS_FRONTEND_FSCK

BOOKMARKFS_FRONTEND_MOUNT

BOOKMARKFS_FRONTEND_MKFS

Denotes the frontend program that launches the backend. These flags are mutually exclusive.

4.3.4 Create Backend Context ¶

The backend_create function is called to create a backend context. It must not be NULL.

Type of the backend_create function is defined as:

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

Function arguments:

conf

Backend configuration items.

The bookmarkfs_backend_conf structure is defined as:

struct bookmarkfs_backend_conf {
    uint32_t  version;
    uint32_t  flags;
    char     *store_path;

    struct bookmarkfs_conf_opt *opts;
};

version

Version number of the frontend program, equivalent to the BOOKMARKFS_VERNUM macro in ${pkgincludedir}/version.h.

flags

A bit array of the following flags:

BOOKMARKFS_BACKEND_READONLY

Indicates that the filesystem is mounted read-only, and the functions that may write to the bookmark storage will not be called for this session.

BOOKMARKFS_BACKEND_CTIME

Indicates that the -o ctime option is given to mount.bookmarkfs.

BOOKMARKFS_BACKEND_NO_SANDBOX

Indicates that the -o no_sandbox option is given to mount.bookmarkfs.

If the backend does not support sandboxing, backend_create should fail. Otherwise, function backend_sandbox should be implemented. See Enter Sandbox.

BOOKMARKFS_BACKEND_NO_LANDLOCK

Indicates that the -o no_landlock option is given to mount.bookmarkfs.

BOOKMARKFS_BACKEND_FSCK_ONLY

Indicates that the backend is launched from fsck.bookmarkfs.

Exclusive mode must be enabled for this context (see Exclusive Mode), and only the bookmark_lookup, bookmark_list, bookmark_check and bookmark_sync functions will be called on the bookmark objects.

store_path

Path to the bookmark storage, equivalent to the src argument passed to mount.bookmarkfs.

The string is guaranteed to be NUL-terminated, and valid throughout the lifetime of the current backend. The function is free to modify the string, however, it must not write past the string boundary.

opts

Linked list of backend-specific options, NULL if there are none.

The bookmarkfs_conf_opt structure is defined as:

struct bookmarkfs_conf_opt {
    char *key;
    char *val;

    struct bookmarkfs_conf_opt *next;
};

key

val

Key and value of the current option. If the option does not have a value (no ‘=’ character present), val is NULL.

When not NULL, the strings are guaranteed to be NUL-terminated, and valid throughout the lifetime of the current backend context. The function is free to modify the strings, however, it must not write past the string boundary.

next

Pointer to the next option, NULL if there are no more options.

The backend must not re-assign the fields in opt.

resp

Information of the new backend context.

The initial content of this argument is unspecified. When the backend context is successfully created, the function should populate this argument with appropriate values.

The bookmarkfs_backend_create_resp structure is defined as:

struct bookmarkfs_backend_create_resp {
    char const *name;
    void       *backend_ctx;
    uint64_t    bookmarks_root_id;
    uint64_t    tags_root_id;
    char const *xattr_names;
    uint32_t    flags;
};

name

Name of the backend context, used as default value for the -o fsname=name option of mount.bookmarkfs.

Must be a NUL-terminated string valid at least until the next function call on this backend context.

backend_ctx

An opaque pointer referring to the backend context.

The pointer will be passed to further function calls on this context.

bookmarks_root_id

ID of the bookmarks root directory (i.e., ${mountpoint}/bookmarks). Must not be greater than BOOKMARKFS_MAX_ID.

If sandboxing is requested, and the ID cannot be determined in a safe way before entering sandbox, the backend may leave this field as-is or set it to UINT64_MAX.

tags_root_id

ID of the tags root directory (i.e., ${mountpoint}/tags). Must not be greater than BOOKMARKFS_MAX_ID.

This field should be left as-is or set to UINT64_MAX, if one of the following conditions is met:

• Sandboxing is requested, and the ID cannot be determined in a safe way before entering sandbox.
• The backend does not support tags for this context. See Tags.

xattr_names

Names of extended attributes (see Extended Attributes) supported for this backend context.

Must be a concatenation of NUL-terminated strings valid throughout the lifetime of this backend context. An empty string denotes the end of list.

flags

A bit array of the following flags:

BOOKMARKFS_BACKEND_EXCLUSIVE

Indicates that the backend claims exclusive access to the bookmark storage. See Exclusive Mode.

BOOKMARKFS_BACKEND_HAS_KEYWORD

Indicates that the backend supports keywords for this context. See Keywords.

The function should return 0 on success, and -1 on error.

4.3.5 Destroy Backend Context ¶

The backend_destroy function is called to destroy a backend context. It must not be NULL.

Upon destruction, the backend should release all system resources associated with this context. Changes made to the bookmark storage should be persisted.

Type of the backend_destroy function is defined as:

typedef void (bookmarkfs_backend_destroy_func) (
    void *backend_ctx
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

4.3.6 Enter Sandbox ¶

The backend_sandbox function is called to instruct the backend to enter a sandboxed state, where it has limited access to system resources, thereby improving security. See Sandboxing.

This function is only called if the BOOKMARKFS_BACKEND_NO_SANDBOX flag is not set for this context.

Considering how sandboxing is usually implemented, it may be complicated or even impractical for multiple backend contexts to enter sandbox separately without affecting one another. Thus it is guaranteed that, when launched from a frontend program like mount.bookmarkfs which requires sandboxing, only one backend context will be created throughout the lifetime of the process.

Type of the backend_sandbox function is defined as:

typedef int (bookmarkfs_backend_sandbox_func) (
    void                                  *backend_ctx,
    struct bookmarkfs_backend_create_resp *resp
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

resp

See Backend-Create Response for the definition of struct bookmarkfs_backend_create_resp.

Fields in this argument should be left as-is, except for:

bookmarks_root_id

This field must be set to the ID of the bookmarks root directory, if not already done so in backend_create.

tags_root_id

This field should be set to the ID of the tags root directory, if not already done so in backend_create.

If the backend does not support tags for this context, this field should be left as-is or set to UINT64_MAX.

The function should return 0 on success, and -1 on error.

Once this function fails, no further function calls will be performed on the backend except for backend_destroy.

4.3.7 Lookup Bookmark ¶

The bookmark_lookup function is called to obtain the attributes of a bookmark or a bookmark-related object. It must not be NULL.

Type of the bookmark_lookup function is defined as:

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

Function arguments:

backend_ctx

The pointer referring to the backend context.

id

ID of the object to be used for lookup. It could be a bookmark ID or tag ID, depending on the value of flags.

name

Name of the object to lookup. It could be a bookmark name, tag name or keyword name, depending on the value of flags.

When not NULL, name is guaranteed to be a valid filename, which should be used to lookup an object under the directory referred to by id. Otherwise, the function should operate on the object referred to by id itself.

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

Lookup a bookmark or bookmark folder. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

Lookup a tag, or a bookmark under a tag. See Tags.

BOOKMARKFS_BOOKMARK_TYPE_KEYWORD

Lookup a keyword. See Keywords.

The value of id is unspecified.

stat_buf

Attributes of the object to lookup.

The initial content of this argument is unspecified. When the object is successfully found, the function should populate this argument with appropriate values.

The bookmarkfs_bookmark_stat structure is defined as:

struct bookmarkfs_bookmark_stat {
    uint64_t id;
    ssize_t  value_len;

    struct timespec atime;
    struct timespec mtime;
};

id

ID of the object.

value_len

Length of the object value in bytes. -1 if the object refers to a directory.

atime

mtime

Last access and modification time of the object.

Values should be the time elapsed since the Unix epoch.

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

4.3.8 List Bookmarks ¶

The bookmark_list function is called to list the bookmarks or bookmark-related objects under a directory. It must not be NULL.

Type of the bookmark_list function is defined as:

typedef int (bookmarkfs_bookmark_list_func) (
    void                         *backend_ctx,
    uint64_t                      id,
    off_t                         off,
    uint32_t                      flags,
    bookmarkfs_bookmark_list_cb  *callback,
    void                         *user_data,
    void                        **cookie_ptr
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

id

Object ID of the directory. It could be a bookmark ID or tag ID, depending on the value of flags.

off

Position of the current bookmark_list operation, equivalent to the second argument for seekdir(3p).

Initially, the value is always 0. Subsequent calls (with the same cookie) use the values obtained from entry->off of callback function calls. If not, the position is unspecified.

A subsequent call with a 0 value indicates rewinddir(3p).

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_LIST_WITHSTAT

Indicates that the caller requires the attributes of the objects in the list.

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

List bookmarks (and bookmark folders) under a bookmark folder. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

List tags, or bookmarks under a tag. See Tags.

BOOKMARKFS_BOOKMARK_TYPE_KEYWORD

List keywords. See Keywords.

The value of id is unspecified.

callback

Function to be called for each object found under the directory. If NULL, bookmark_list should return immediately without changing current position.

Ordering of the objects should follow the ordering of which they appear in the browser. See Directory Entry Ordering.

Type of the callback function is defined as:

typedef int (bookmarkfs_bookmark_list_cb) (
    void                                   *user_data,
    struct bookmarkfs_bookmark_entry const *entry
);

Function arguments:

user_data

Must be equal to the user_data argument value for the current bookmark_list call.

entry

Information of this object.

The bookmarkfs_bookmark_entry structure is defined as:

struct bookmarkfs_bookmark_entry {
    char const *name;
    off_t       off;

    struct bookmarkfs_bookmark_stat stat;
};

name

Name of the object entry. Must be a valid filename.

Objects with invalid name should be exempted from the list. See Filesystem Check.

off

Position of the current entry, to be used for subsequent calls to bookmark_list.

stat

Attributes of the object entry.

See Bookmark Attributes for the definition of struct bookmarkfs_bookmark_stat.

If the BOOKMARKFS_BOOKMARK_LIST_WITHSTAT flag is not given, the caller ignores atime and mtime, and only use value_len to determine whether the entry refers to a directory.

Values of entry and name only need to be valid until the callback function returns.

Return value:

0

Continue to the next entry, if one exists.

Non-zero value

Stop listing entries, and use this value as the return value for the current bookmark_list call.

user_data

An opaque pointer which should be passed as-is to the callback function.

cookie_ptr

Pointer to the “cookie” for the current bookmark_list operation. NULL if not used by the caller.

The “cookie” is an opaque pointer which stores internal states to be used for subsequent operations on the same directory.

If the value pointed to by cookie_ptr is NULL, it indicates that this is an initial operation. The function should set the value to a pointer which is not NULL.

The cookie obtained from bookmark_list may be used for bookmark_check, and vise versa. However, the position of each operation should be maintained separately.

The function must not change the cookie value.

Return value:

0

All entries in the directory have been listed.

Negated errno

An error occurred.

Arbitrary non-zero value

The function is terminated by a call to callback that returns a non-zero value.

If returning a negative value, the position of the current bookmark_list operation is unspecified.

4.3.9 Get Bookmark Content ¶

The bookmark_get function is called to get the content or extended attribute value of a bookmark.

The “content” of a bookmark is equivalent to the content of a regular file on a BookmarkFS filesystem that refers to a bookmark. See Bookmarks.

Type of the bookmark_get function is defined as:

typedef int (bookmarkfs_bookmark_get_func) (
    void                        *backend_ctx,
    uint64_t                     id,
    char const                  *xattr_name,
    bookmarkfs_bookmark_get_cb  *callback,
    void                        *user_data,
    void                       **cookie_ptr
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

id

ID of the bookmark (could be a bookmark folder if xattr_name is not NULL).

xattr_name

Name of an extended attribute.

If not NULL, xattr_name is guaranteed to be a NUL-terminated string, and the function should get the corresponding extended attribute value instead of the bookmark content.

callback

Function to be called for the required bookmark data. It is guaranteed not to be NULL.

Type of the callback function is defined as:

typedef int (bookmarkfs_bookmark_get_cb) (
    void       *user_data,
    void const *value,
    size_t      value_len
);

Function arguments:

user_data

Must be equal to the user_data argument value of the current bookmark_get call.

value

Bookmark content (or extended attribute) data. Must not be NULL.

It may contain arbitrary bytes, and only need to be valid until the callback function returns.

value_len

Length of value in bytes.

The function returns 0 on success. Otherwise, the function returns a negated errno which should be used as the return value for the current bookmark_get call.

user_data

An opaque pointer which should be passed as-is to the callback function.

cookie_ptr

Pointer to the “cookie” for the current bookmark_get operation. NULL if not used by the caller.

The “cookie” is an opaque pointer which stores internal states for subsequent operations on the same bookmark (and xattr_name) to determine whether the corresponding data has changed.

If the value pointered to by cookie_ptr is NULL, it indicates that this is an initial operation. If the backend supports watching for changes of bookmark content, it may set the value to a pointer which is not NULL.

The function must not change the cookie value.

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

Notable error codes:

EAGAIN

Bookmark data has not been changed externally since the last call to bookmark_get with the same cookie. If this error code is returned, callback must not be called.

“Externally” means that the modification comes from another process which has access to the bookmark storage. In exclusive mode, this is not expected to happen, and bookmark_list is always called with a cookie_ptr of NULL value. See Exclusive Mode.

If changes cannot be detected in an efficient way, false positives are acceptable. False negatives are also acceptable for a short time duration (preferably no more than a few seconds).

4.3.10 Free Cookie ¶

When a cookie obtained from bookmark_list, bookmark_get or bookmark_check is no longer used, the cookie_free function is called. It must not be NULL.

The function should release all system resources associated with this cookie.

Type of the cookie_free function is defined as:

typedef void (bookmarkfs_cookie_free_func) (
    void                        *backend_ctx,
    void                        *cookie,
    enum bookmarkfs_cookie_type  cookie_type
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

cookie

Cookie to be freed.

cookie_type

Type of the cookie. It must be one of the values defined in enum bookmarkfs_cookie_type:

BOOKMARKFS_COOKIE_TYPE_WATCH

Indicates that the cookie is obtained from bookmark_get.

BOOKMARKFS_COOKIE_TYPE_LIST

Indicates that the cookie is obtained from bookmark_list or bookmark_check.

4.3.11 Set Bookmark Content ¶

The bookmark_set function is called to update the data associated with a bookmark or bookmark-related object. It is never called when the filesystem is mounted read-only.

Type of the bookmark_set function is defined as:

typedef int (bookmarkfs_bookmark_set_func) (
    void       *backend_ctx,
    uint64_t    id,
    char const *xattr_name,
    uint32_t    flags,
    void const *val,
    size_t      val_len
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

id

ID of the object to update. It could be a bookmark ID or tag ID, depending on the value of flags.

xattr_name

Name of an extended attribute.

If not NULL, xattr_name is guaranteed to be a NUL-terminated string, and the function should update the corresponding extended attribute value instead of the bookmark content.

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_SET_ATIME

BOOKMARKFS_BOOKMARK_SET_MTIME

Indicates that the function should update the timestamps associated with the object, instead of the bookmark content or extended attribute value.

The val argument points to an array of struct timespec, the first element refers to the last access time, and the second element refers to the last modification time for the object. If a flag is not set, the corresponding timestamp should be left as-is.

Values of xattr_name and val_len are unspecified.

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

Update the data associated with a bookmark or bookmark folder. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

Update the data associated with a tag. See Tags.

val

Pointer to the new value of the object data.

val_len

Length of the new value in bytes.

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

The backend does not need to update the last modification time of a bookmark upon bookmark content update, since the caller knows better when the bookmark content is actually modified, and always explicitly updates the mtime after a writeback.

However, if the BOOKMARKFS_BACKEND_CTIME flag is set for this context, the function should automatically update the bookmark mtime to the current time upon extended attribute update.

4.3.12 Create Bookmark ¶

The bookmark_create function is called to create a new bookmark or bookmark-related object. It is never called when the filesystem is mounted read-only.

Type of the bookmark_create function is defined as:

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

Function arguments:

backend_ctx

The pointer referring to the backend context.

parent_id

ID of the parent directory to create the new object. It could be a bookmark ID or tag ID, depending on the value of flags.

name

Name of the new object. It could be a bookmark name, tag name or keyword name, depending on the value of flags.

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_CREATE_DIR

Indicates that the new object to be created should be a directory.

If this flag is not set, the new object should be a bookmark.

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

Create a bookmark or bookmark folder. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

Create a tag, or associate an existing bookmark with a tag. See Tags.

BOOKMARKFS_BOOKMARK_TYPE_KEYWORD

Associate an existing bookmark with a new keyword. See Keywords.

The value of parent_id is unspecified.

stat_buf

Attributes of the new object.

See Bookmark Attributes for the definition of struct bookmarkfs_bookmark_stat.

Except for the id field, the initial content of this argument is unspecified. When the object is successfully found, the function should populate this argument with appropriate values.

When associating an existing bookmark with a tag or keyword, the initial value of the id field refers to the bookmark to be associated. Generally it should be left as-is, but the backend is allowed to re-assign it to the ID of another bookmark (see below for restrictions).

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

Restrictions for the new object:

New bookmark

Bookmark content should be empty if possible.

Other reasonable values (e.g., ‘about:blank’) are also acceptable if the bookmark storage does not allow empty bookmark content.

New directory

Should not contain any entries.

New association

Should appear to be the same object as the associated bookmark, or at least contain the same content.

When a new object is successfully created, the function should automatically update the last modification time of the parent directory to the current time.

4.3.13 Rename Bookmark ¶

The bookmark_rename function is called to rename and/or reparent a bookmark or a bookmark-related object. It is never called when the filesystem is mounted read-only.

Type of the bookmark_rename function is defined as:

typedef int (bookmarkfs_bookmark_rename_func) (
    void       *backend_ctx,
    uint64_t    old_parent_id,
    char const *old_name,
    uint64_t    new_parent_id,
    char const *new_name,
    uint32_t    flags
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

old_parent_id

ID of the parent directory containing the object to be renamed. It could be a bookmark ID or tag ID, depending on the value of flags.

old_name

Name of the object to be renamed. It could be a bookmark name, tag name or keyword name, depending on the value of flags.

new_parent_id

ID of the new parent directory for the object.

new_name

New name of the object.

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_RENAME_NOREPLACE

Indicates that the function should not replace an existing object.

This flag is analogous to the RENAME_NOREPLACE flag for renameat2(2).

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

Rename a bookmark. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

Rename a tag. See Tags.

The function should fail with EPERM if either old_parent_id or new_parent_id does not refer to the tags root directory, since renaming a tag association makes no sense.

BOOKMARKFS_BOOKMARK_TYPE_KEYWORD

Rename a keyword. See Keywords.

Values of old_parent_id and new_parent_id are unspecified.

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

When replacing an existing object:

• The two objects should be of the same type (e.g., a bookmark cannot replace a bookmark folder).
• When replacing a directory, the destination object must be empty.
• If two objects are the same, the function should do nothing and return successfully.

Upon successful completion, the function should automatically update the last modification time of the parent directories.

4.3.14 Delete Bookmark ¶

The bookmark_delete function is called to remove a bookmark or a bookmark-related object. It is never called when the filesystem is mounted read-only.

Type of the bookmark_delete function is defined as:

typedef int (bookmarkfs_bookmark_delete_func) (
    void       *backend_ctx,
    uint64_t    parent_id,
    char const *name,
    uint32_t    flags
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

parent_id

ID of the parent directory containing the object to be removed. It could be a bookmark ID or tag ID, depending on the value of flags.

name

Name of the object to be removed. It could be a bookmark name, tag name or keyword name, depending on the value of flags.

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_DELETE_DIR

Indicates that the object to be removed is a directory.

If the current backend context is not in exclusive mode (see Exclusive Mode), this information may be incorrect. If so, the function should fail with ENOTDIR or EISDIR.

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

Remove a bookmark or an empty bookmark folder. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

Remove a tag, or dissociate a bookmark from a tag. See Tags.

BOOKMARKFS_BOOKMARK_TYPE_KEYWORD

Remove a keyword. See Keywords.

The value of parent_id is unspecified.

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

Upon successful completion, the function should automatically update the last modification time of the parent directory.

4.3.15 Permute Bookmarks ¶

The bookmark_permute function is called to rearrange bookmarks or bookmark-related objects under a directory. It is never called when the filesystem is mounted read-only.

This function should implement the BOOKMARKFS_IOC_PERMD I/O control. See Permute Directory Entries.

Type of the bookmark_permute function is defined as:

typedef int (bookmarkfs_bookmark_permute_func) (
    void                     *backend_ctx,
    uint64_t                  parent_id,
    enum bookmarkfs_permd_op  op,
    char const               *name1,
    char const               *name2,
    uint32_t                  flags
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

parent_id

ID of the parent directory containing the objects to be rearranged. It could be a bookmark ID or tag ID, depending on the value of flags.

op

Operation to perform on objects represented by name1 and name2.

See Rearrange Operations for the meaning of each value.

name1

name2

Names of the objects to be rearranged. They could be bookmark names, tag names or keyword names, depending on the value of flags.

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

Rearrange entries under a bookmark folder. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

Rearrange tags or tag associations. See Tags.

BOOKMARKFS_BOOKMARK_TYPE_KEYWORD

Rearrange keywords. See Keywords.

The value of parent_id is unspecified.

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

4.3.16 Check Bookmarks ¶

The bookmark_check function is called when a “filesystem check” operation is performed on a BookmarkFS directory. See Filesystem Check.

Type of the bookmark_check function is defined as:

typedef int (bookmarkfs_bookmark_check_func) (
    void                               *backend_ctx,
    uint64_t                            parent_id,
    struct bookmarkfs_fsck_data const  *fsck_data,
    uint32_t                            flags,
    bookmarkfs_bookmark_check_cb       *callback,
    void                               *user_data,
    void                              **cookie_ptr
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

parent_id

ID of the parent directory containing the objects to be checked. It could be a bookmark ID or tag ID, depending on the value of flags.

fsck_data

Always NULL if the filesystem is mounted read-only. Otherwise, a non-NULL value indicates BOOKMARKFS_IOC_FSCK_APPLY. See Repair Bookmark.

See Filesystem-Check Data for the definition of struct bookmarkfs_fsck_data.

Value of each field:

id

ID of the object to rename.

The function should check whether the object is under the directory referred to by parent_id. If not, it should fail with ENOENT.

If the object ID was not previously passed to the callback function during a bookmark_check call with the same cookie, the function may:

• Fail with an arbitrary error code.
• Perform the rename, even if the original name is a valid filename.

name

New name for the object. The string may not be NUL-terminated.

extra

Unspecified value.

If fsck_data is not NULL, the function should only check whether the new name is valid, instead of going through the rest of the directory.

flags

A bit array of the following flags:

BOOKMARKFS_BOOKMARK_TYPE_MASK

The subsystem to operate on.

Equals to one of the following values (after shifting):

BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK

Check bookmark and bookmark folder names. See Bookmarks.

BOOKMARKFS_BOOKMARK_TYPE_TAG

Check tag names. See Tags.

The function should fail with EPERM if parent_id does not refer to the tags root directory.

BOOKMARKFS_BOOKMARK_TYPE_KEYWORD

Check keyword names. See Keywords.

The value of parent_id is unspecified.

callback

Function to be called for each object with invalid name.

A NULL value indicates BOOKMARKFS_IOC_FSCK_REWIND, in which case the function should reset the position of the current bookmark_check operation.

Type of the callback function is defined as:

typedef int (bookmarkfs_bookmark_check_cb) (
    void       *user_data,
    int         result,
    uint64_t    id,
    uint64_t    extra,
    char const *name
);

Function arguments:

user_data

Must be equal to the user_data argument for the current bookmark_check call.

result

Should be one of the values defined in enum bookmarkfs_fsck_result indicating why this name is invalid. See Filesystem-Check Result Code.

id

extra

name

Equivalent to the corresponding fields in struct bookmarkfs_fsck_data. See Filesystem-Check Data.

Return value:

0

Continue to the next entry, if one exists.

Non-zero value

Stop listing entries, and use this value as the return value for the current bookmark_check call.

user_data

An opaque pointer which should be passed as-is to the callback function.

cookie_ptr

Pointer to the “cookie” for the current bookmark_check operation. It is guaranteed not to be NULL.

Except for the position of operation, this cookie shares the same semantics as the one for bookmark_list. See Bookmark-List Cookie.

Return value:

0

The operation completes successfully.

Negated errno

An error occurred.

Arbitrary non-zero value

The function is terminated by a call to callback that returns a non-zero value.

If returning a negative value, the position of the current bookmark_check operation is unspecified.

4.3.17 Sync Bookmarks ¶

The bookmark_sync function is called to persist changes to the bookmark storage. It is never called when the filesystem is mounted read-only.

If the bookmark storage is also changed from another process, function behavior is undefined. However, the backend should try not to corrupt the bookmark storage, and prefer changes from the caller, if possible.

Type of the bookmark_sync function is defined as:

typedef int (bookmarkfs_bookmark_sync_func) (
    void *backend_ctx
);

Function arguments:

backend_ctx

The pointer referring to the backend context.

On success, the function should return 0. Otherwise, it should return a negated errno indicating the error encountered.

4.3.18 Create Bookmark Storage ¶

The backend_mkfs function is called by the mkfs.bookmarkfs program to create a new bookmark storage. It can be NULL.

The new bookmark storage should be able to be opened directly, by both backend_create and the application that owns the bookmark storage (typically a web browser).

Type of the backend_mkfs function is defined as:

typedef int (bookmarkfs_backend_mkfs_func) (
    struct bookmarkfs_backend_conf const *conf
);

Function arguments:

conf

See Backend Configuration for the definition of struct bookmarkfs_backend_conf.

Some fields should be handled differently from backend_create:

flags

A bit array of the following flags:

BOOKMARKFS_BACKEND_MKFS_FORCE

Indicates that the -o force option is given to mkfs.bookmarkfs.

store_path

Path to the bookmark storage to be created, equivalent to the store_path passed to backend_create.

The function should not overwrite existing bookmark storage, unless the BOOKMARKFS_BACKEND_MKFS_FORCE flag is given.

The function should return 0 on success, and -1 on error.

5.3.1 Get Handler Information ¶

If not NULL, the info function is called when the user instructs fsck.bookmarkfs to print information about the handler.

When this function is called, it should write a human-readable message of the corresponding information to standard output.

Type of the info function is defined as:

typedef void (bookmarkfs_fsck_handler_info_func) (
    uint32_t flags
);

Function arguments:

flags

A bit array of the following flags:

BOOKMARKFS_FSCK_HANDLER_INFO_HELP

BOOKMARKFS_FSCK_HANDLER_INFO_VERSION

Indicates that the function should print a help/version message.

These flags are analogous to the corresponding flags in the backend_info function of the backend API. See Get Backend Information.

5.3.2 Create Handler Context ¶

A filesystem-check handler context maintains internal states for handling fsck entries.

To create a handler context, the create function is called. It must not be NULL.

Type of the create function is defined as:

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

Function arguments:

opts

Linked list of handler-specific options, NULL if there are none.

Handler-specific option should be processed in the same way as backend-specific options. See Backend-Specific Options.

flags

A bit array of the following flags:

BOOKMARKFS_FSCK_HANDLER_INTERACTIVE

Indicates that the -i option is given to fsck.bookmarkfs.

BOOKMARKFS_FSCK_HANDLER_READONLY

Indicates that the -o repair option is not given to fsck.bookmarkfs.

handler_ctx_ptr

Pointer to an opaque pointer referring to the handler context.

The initial value of that pointer is unspecified. It should be set by the handler when the handler context is successfully created.

The function should return 0 on success, and -1 on error.

5.3.3 Destroy Handler Context ¶

The destroy function is called to destroy a handler context. It must not be NULL.

Upon destruction, The handler should release all system resources associated with this context.

Type of the destroy function is defined as:

typedef void (bookmarkfs_fsck_handler_destroy_func) (
    void *handler_ctx
);

Function arguments:

handler_ctx

The pointer referring to the handler context.

5.3.4 Run Handler ¶

Each time fsck.bookmarkfs finds and entry, or completes a handler-initiated operation, the run function is called. It must not be NULL.

Type of the run function is defined as:

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

Function arguments:

handler_ctx

The pointer referring to the handler context.

why

Reason code for this handler call:

Non-negative value

The fsck.bookmarkfs program has found an entry.

See Filesystem-Check Result Code for possible values. However, BOOKMARKFS_FSCK_RESULT_END is handled by fsck.bookmarkfs and never appears.

-1

Indicates that an operation instructed by the previous return value of this function is successfully performed.

If run is being called for the first time, or the previous invocation returns BOOKMARKFS_FSCK_NEXT, this value never appears.

data

Information for this handler call.

The bookmarkfs_fsck_handler_data union is defined as:

union bookmarkfs_fsck_handler_data {
    struct bookmarkfs_fsck_handler_entry entry;
    char *str;
};

entry

Information for the bookmark entry. This field is set when why is non-negative.

The bookmarkfs_fsck_handler_entry structure is defined as:

struct bookmarkfs_fsck_handler_entry {
    uint64_t parent_id;

    struct bookmarkfs_fsck_data data;
};

parent_id

ID of the bookmark folder that contains this bookmark entry.

data

See Online Filesystem Check for the definition of struct bookmarkfs_fsck_data.

str

A NUL-terminated string.

This field is set to the user input string when why is -1, and the previous invocation of run returns BOOKMARKFS_FSCK_USER_INPUT.

The string is only guaranteed to be valid until the function returns.

On success, the function should return one of the following values, indicating the operation to perform:

BOOKMARKFS_FSCK_NEXT

Continue to the next entry.

BOOKMARKFS_FSCK_APPLY

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

The function should copy the new name for the bookmark to data->entry.data.name.

BOOKMARKFS_FSCK_USER_INPUT

Request for user input. Only available in interactive mode.

The function should set data->str to a prompt string for Readline. The string must be valid until the next function call on this handler context.

BOOKMARKFS_FSCK_SAVE

Save applied changes.

BOOKMARKFS_FSCK_STOP

Save applied changes and quit.

The run function is guaranteed not to be called again for this context.

BOOKMARKFS_FSCK_REWIND

Rewind current directory.

BOOKMARKFS_FSCK_SKIP

Skip current directory.

BOOKMARKFS_FSCK_SKIP_CHILDREN

Skip current directory and all subdirectories.

BOOKMARKFS_FSCK_RESET

Rewind all.

On error, the function should return -1.