mirror of
https://git.sr.ht/~cismonx/bookmarkfs
synced 2025-07-23 17:48:52 +00:00
doc: update doc for backend API
Add doc for the `backend_create` function.
This commit is contained in:
CismonX
parent
0510e5e8c0
commit
5d861f4752
1 changed files with 199 additions and 0 deletions
|
|
@ -1513,6 +1513,205 @@ These flags are mutually exclusive.
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
|
|
||||||
|
@node Create Backend Context
|
||||||
|
@subsection Create Backend Context
|
||||||
|
|
||||||
|
A backend context maintains internal states for manipulating a specific
|
||||||
|
bookmark storage.
|
||||||
|
|
||||||
|
Each BookmarkFS filesystem mounted by @command{mount.bookmarkfs} is
|
||||||
|
backed by a backend context.
|
||||||
|
The context is created before mount, and destroyed after dismount.
|
||||||
|
Operations on the filesystem, if applicable, are fulfilled by invoking
|
||||||
|
the corresponding backend functions on the context.
|
||||||
|
|
||||||
|
To create a backend context, the @code{backend_create} function is called.
|
||||||
|
It must not be @code{NULL}.
|
||||||
|
|
||||||
|
@example c
|
||||||
|
typedef int (bookmarkfs_backend_create_func) (
|
||||||
|
struct bookmarkfs_backend_conf const *conf,
|
||||||
|
struct bookmarkfs_backend_create_resp *resp
|
||||||
|
);
|
||||||
|
@end example
|
||||||
|
|
||||||
|
Function arguments:
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item conf
|
||||||
|
Backend configuration items.
|
||||||
|
|
||||||
|
The @code{bookmarkfs_backend_conf} structure is defined as:
|
||||||
|
|
||||||
|
@example c
|
||||||
|
struct bookmarkfs_backend_conf @{
|
||||||
|
uint32_t version;
|
||||||
|
uint32_t flags;
|
||||||
|
char *store_path;
|
||||||
|
|
||||||
|
struct bookmarkfs_conf_opt *opts;
|
||||||
|
@};
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item version
|
||||||
|
Version number of the frontend program, equivalent to the
|
||||||
|
@code{BOOKMARKFS_VERNUM} macro in @file{bookmarkfs/version.h}.
|
||||||
|
|
||||||
|
@item flags
|
||||||
|
A bit array of the following flags:
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item BOOKMARKFS_BACKEND_READONLY
|
||||||
|
Indicates that the filesystem is mounted read-only, and the frontend program
|
||||||
|
will not call functions that may write to the bookmark storage.
|
||||||
|
|
||||||
|
@item BOOKMARKFS_BACKEND_CTIME
|
||||||
|
Indicates that the @option{-o ctime} option is given to
|
||||||
|
@code{mount.bookmarkfs}.
|
||||||
|
|
||||||
|
@item BOOKMARKFS_BACKEND_NO_SANDBOX
|
||||||
|
Indicates that the @option{-o no_sandbox} option is given to
|
||||||
|
@code{mount.bookmarkfs}.
|
||||||
|
|
||||||
|
@item BOOKMARKFS_BACKEND_NO_LANDLOCK
|
||||||
|
Indicates that the @option{-o no_landlock} option is given to
|
||||||
|
@code{mount.bookmarkfs}.
|
||||||
|
|
||||||
|
@item BOOKMARKFS_BACKEND_FSCK_ONLY
|
||||||
|
Indicates that the backend is launched from @command{fsck.bookmarkfs}.
|
||||||
|
|
||||||
|
The backend must claim exclusive access to the bookmark storage, and only
|
||||||
|
the @code{bookmark_lookup}, @code{bookmark_list} and @code{bookmark_fsck}
|
||||||
|
functions will be called on the bookmarks.
|
||||||
|
@end table
|
||||||
|
|
||||||
|
@item store_path
|
||||||
|
Path to the bookmark storage, equivalent to the @var{src} argument passed to
|
||||||
|
@command{mount.bookmarkfs}.
|
||||||
|
|
||||||
|
The string is guaranteed to be NUL-terminated, and valid throughout
|
||||||
|
the lifetime of the current backend.
|
||||||
|
The backend is free to modify the string, however, it must not write past
|
||||||
|
the string boundary.
|
||||||
|
|
||||||
|
@item opts
|
||||||
|
Linked list of backend-specific options, @code{NULL} if there are none.
|
||||||
|
|
||||||
|
The @code{bookmarkfs_conf_opt} structure is defined as:
|
||||||
|
|
||||||
|
@example c
|
||||||
|
struct bookmarkfs_conf_opt @{
|
||||||
|
char *key;
|
||||||
|
char *val;
|
||||||
|
|
||||||
|
struct bookmarkfs_conf_opt *next;
|
||||||
|
@};
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item key
|
||||||
|
@item val
|
||||||
|
Key and value of the current option.
|
||||||
|
If the option does not have a value (no @samp{=} character present),
|
||||||
|
@code{val} is @code{NULL}.
|
||||||
|
|
||||||
|
When not @code{NULL}, the strings are guaranteed to be NUL-terminated,
|
||||||
|
and valid throughout the lifetime of the current backend context.
|
||||||
|
The backend is free to modify the strings, however, it must not write past
|
||||||
|
the string boundary.
|
||||||
|
|
||||||
|
@item next
|
||||||
|
Pointer to the next option, @code{NULL} if there are no more options.
|
||||||
|
@end table
|
||||||
|
|
||||||
|
The backend must not re-assign the fields in @code{opt}.
|
||||||
|
@end table
|
||||||
|
|
||||||
|
@item resp
|
||||||
|
Information of the new backend context.
|
||||||
|
|
||||||
|
The initial content of this argument is unspecified.
|
||||||
|
When the backend context is successfully created, the backend should
|
||||||
|
populate this argument with appropriate values.
|
||||||
|
|
||||||
|
The @code{bookmarkfs_backend_create_resp} structure is defined as:
|
||||||
|
|
||||||
|
@example c
|
||||||
|
struct bookmarkfs_backend_create_resp @{
|
||||||
|
char const *name;
|
||||||
|
void *backend_ctx;
|
||||||
|
uint64_t bookmarks_root_id;
|
||||||
|
uint64_t tags_root_id;
|
||||||
|
char const *bookmark_attrs;
|
||||||
|
uint32_t flags;
|
||||||
|
@};
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item name
|
||||||
|
Name of the backend context, used as default value for the
|
||||||
|
@option{-o fsname=@var{name}} option of @command{mount.bookmarkfs}.
|
||||||
|
|
||||||
|
Must be a NUL-terminated string valid at least until the next function call
|
||||||
|
on this backend context.
|
||||||
|
|
||||||
|
@item backend_ctx
|
||||||
|
An opaque pointer referring to the backend context.
|
||||||
|
|
||||||
|
The pointer will be passed to further function calls on this context.
|
||||||
|
|
||||||
|
@item bookmarks_root_id
|
||||||
|
ID of the bookmark root directory
|
||||||
|
(i.e. @file{@var{$@{mountpoint@}}/bookmarks}).
|
||||||
|
Must not be greater than @code{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 @code{UINT64_MAX}.
|
||||||
|
|
||||||
|
@item tags_root_id
|
||||||
|
ID of the tags root directory (i.e. @file{@var{$@{mountpoint@}}/tags}).
|
||||||
|
Must not be greater than @code{BOOKMARKFS_MAX_ID}.
|
||||||
|
|
||||||
|
This field should be left as-is or set to @code{UINT64_MAX},
|
||||||
|
if one of the following conditions is met:
|
||||||
|
|
||||||
|
@itemize @bullet{}
|
||||||
|
@item Sandboxing is requested, and the ID cannot be determined in a safe way
|
||||||
|
before entering sandbox.
|
||||||
|
@item The backend does not support tags for this context (@pxref{Tags}).
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
@item bookmark_attrs
|
||||||
|
Names of extended attributes (@pxref{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.
|
||||||
|
|
||||||
|
@item flags
|
||||||
|
A bit array of the following flags:
|
||||||
|
|
||||||
|
@table @code
|
||||||
|
@item BOOKMARKFS_BACKEND_EXCLUSIVE
|
||||||
|
Indicates that the backend claims exclusive access to the bookmark storage.
|
||||||
|
|
||||||
|
In exclusive mode, modifications to the bookmark storage only come from
|
||||||
|
the frontend, and the frontend program may perform optimizations based on
|
||||||
|
this assumption.
|
||||||
|
|
||||||
|
@item BOOKMARKFS_BACKEND_HAS_KEYWORD
|
||||||
|
Indicates that the backend supports keywords for this context
|
||||||
|
(@pxref{Keywords}).
|
||||||
|
@end table
|
||||||
|
@end table
|
||||||
|
@end table
|
||||||
|
|
||||||
|
The function should return @t{0} on success, and @t{-1} on error.
|
||||||
|
|
||||||
|
|
||||||
@node Filesystem-Check Handlers
|
@node Filesystem-Check Handlers
|
||||||
@chapter Filesystem-Check Handlers
|
@chapter Filesystem-Check Handlers
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue