diff --git a/doc/bookmarkfs.texi b/doc/bookmarkfs.texi index f1d48e9..b6d886c 100644 --- a/doc/bookmarkfs.texi +++ b/doc/bookmarkfs.texi @@ -1561,7 +1561,7 @@ The @code{backend_info} function is called to print information about the backend. It can be @code{NULL}. -When this function is called, the backend should write a human-readable +When this function is called, it should write a human-readable message of the corresponding information to standard output. Type of the @code{backend_info} function is defined as: @@ -1580,14 +1580,14 @@ A bit array of the following flags: @table @code @item BOOKMARKFS_BACKEND_INFO_HELP -Indicates that the backend should print a help message. +Indicates that the function should print a help message. Mutually exclusive with @code{BOOKMARKFS_BACKEND_INFO_VERSION}. The message should contain a brief description of this backend, as well as a list of backend-specific options. @item BOOKMARKFS_BACKEND_INFO_VERSION -Indicates that the backend should print a version message. +Indicates that the function should print a version message. Mutually exclusive with @code{BOOKMARKFS_BACKEND_INFO_HELP}. In addition to the version number, the version message may also contain @@ -1730,7 +1730,7 @@ The backend must not re-assign the fields in @code{opt}. Information of the new backend context. The initial content of this argument is unspecified. -When the backend context is successfully created, the backend should +When the backend context is successfully created, the function should populate this argument with appropriate values. @anchor{Backend-Create Response} @@ -1821,8 +1821,7 @@ It must not be @code{NULL}. Upon destruction, the backend should release all system resources associated with this context. -If changes have been made to the bookmark storage, the backend should -try to persist them. +Changes made to the bookmark storage should be persisted. Type of the @code{backend_destroy} function is defined as: @@ -1980,7 +1979,7 @@ The value of @code{id} is unspecified. Attributes of the object to lookup. The initial content of this argument is unspecified. -When the object is successfully found, the backend should populate +When the object is successfully found, the function should populate this argument with appropriate values. @anchor{Bookmark Attributes} @@ -2186,7 +2185,7 @@ to be used for subsequent operations on the same directory. If the value pointed to by @code{cookie_ptr} is @code{NULL}, it indicates that this is an initial operation. -The backend should set the value to a pointer which is not @code{NULL}. +The function should set the value to a pointer which is not @code{NULL}. The backend must not change the cookie value. @end table @@ -2336,7 +2335,7 @@ When a cookie obtained from @code{bookmark_list}, the @code{cookie_free} function is called. It must not be @code{NULL}. -The backend should release all system resources associated with this cookie. +The function should release all system resources associated with this cookie. Type of the @code{cookie_free} function is defined as: @@ -2465,7 +2464,7 @@ when the bookmark content is actually modified, and always explicitly updates the mtime after a writeback. However, if the @code{BOOKMARKFS_BACKEND_CTIME} flag is set for this context, -the backend should automatically update the bookmark mtime to +the function should automatically update the bookmark mtime to the current time upon extended attribute update. @@ -2543,7 +2542,7 @@ Attributes of the new object. Except for the @code{id} field, the initial content of this argument is unspecified. -When the object is successfully found, the backend should populate +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 @@ -2559,24 +2558,125 @@ encountered. Restrictions for the new object: @table @asis -@item new bookmark +@item New bookmark Bookmark content should be empty if possible. Other reasonable values (e.g., @samp{about:blank}) are also acceptable if the bookmark storage does not allow empty bookmark content. -@item new directory +@item New directory Should not contain any entries. -@item new association +@item New association Should appear to be the same object as the associated bookmark, or at least contain the same content. @end table -When a new object is successfully created, the backend should automatically +When a new object is successfully created, the function should automatically update the last modification time of the parent directory to the current time. +@node Rename Bookmark +@subsection Rename Bookmark + +The @code{bookmark_rename} function renames and/or reparents a bookmark +or bookmark-related object. +It is never called when the filesystem is mounted read-only. + +Type of the @code{bookmark_rename} function is defined as: + +@example c +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 +); +@end example + +Function arguments: + +@table @code +@item backend_ctx +The pointer referring to the backend context. + +@item old_parent_id +ID of the parent directory containing the object to be renamed. + +@item old_name +Name of the object to be renamed. + +@item new_parent_id +ID of the new parent directory for the object. + +@item new_name +New name of the object. + +@item flags +A bit array of the following flags: + +@table @code +@item BOOKMARKFS_BOOKMARK_RENAME_NOREPLACE +If the object referred to by @code{new_name} already exists +under @code{new_parent_id}, the function should fail with @code{EEXIST} +instead of replacing the existing object. + +This flag is analogous to the @code{RENAME_NOREPLACE} flag for +@linuxmanpage{renameat2}. + +@item BOOKMARKFS_BOOKMARK_TYPE_MASK +The subsystem to operate on. + +Equals to one of the following values (after shifting): + +@table @code +@item BOOKMARKFS_BOOKMARK_TYPE_BOOKMARK +Rename a bookmark. +@xref{Bookmarks}. + +@code{old_parent_id} and @code{new_parent_id} refer to the IDs of bookmark +folders. + +@item BOOKMARKFS_BOOKMARK_TYPE_TAG +Rename a tag. +@xref{Tags}. + +Both @code{old_parent_id} and @code{new_parent_id} should be the ID of +the tags root directory. +Otherwise the function should fail with @code{EPERM}, since renaming a tag +association is not allowed. + +@item BOOKMARKFS_BOOKMARK_TYPE_KEYWORD +Rename a keyword. +@xref{Keywords}. + +Values of @code{old_parent_id} and @code{new_parent_id} are unspecified. +@end table +@end table +@end table + +On success, the function should return @t{0}. +Otherwise, it should return a negated @code{errno} indicating the error +encountered. + +When replacing an existing object: + +@itemize @bullet{} +@item The two objects should be of the same type +(e.g., a bookmark cannot replace a bookmark folder). + +@item When replacing a directory, the destination object must be empty. + +@item If two objects are the same, the function should do nothing and return +successfully. +@end itemize + +Upon successful completion, the function should automatically update the +last modification time of the two directories. + + @node Sync Bookmarks @subsection Sync Bookmarks @@ -2651,7 +2751,7 @@ Indicates that the @option{-o force} option is given to Path to the bookmark storage to be created, equivalent to the @code{store_path} passed to @code{backend_create}. -The backend should not overwrite existing bookmark storage, unless +The function should not overwrite existing bookmark storage, unless the @code{BOOKMARKFS_BACKEND_MKFS_FORCE} flag is given. @end table @end table