makary/bookmarkfs
1
0
Fork 0
mirror of https://git.sr.ht/~cismonx/bookmarkfs synced 2025-06-07 19:58:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: add subsection "permute directory entries"

Browse source
This commit is contained in:
CismonX 2025-01-02 18:43:31 +08:00
parent 3d56aa560f
commit 486bd6b36e
No known key found for this signature in database
GPG key ID: 3094873E29A482FB
1 changed files with 60 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
doc/bookmarkfs.texi
View file

@ -289,8 +289,8 @@ len = extattr_get_fd(fd, EXTATTR_NAMESPACE_USER, "bookmarkfs.guid",
@end example @end example
@node Permute Directory Entries @node Directory Entry Ordering
@section Permute Directory Entries @section Directory Entry Ordering
POSIX does not specify the ordering of the directory entries retrieved from POSIX does not specify the ordering of the directory entries retrieved from
the directory stream using @posixfuncmanpage{readdir}. the directory stream using @posixfuncmanpage{readdir}.
@ -317,6 +317,64 @@ New entries are appended to the end; removed entries do not affect
the order of other entries. the order of other entries.
@node Permute Directory Entries
@subsection Permute Directory Entries
BookmarkFS provides an I/O control for rearranging directory entries:
@example
#include <bookmarkfs/ioctl.h>
int ioctl (int @var{dirfd}, BOOKMARKFS_IOC_PERMD,
struct bookmarkfs_permd_data const *@var{argp});
@end example
The @code{bookmarkfs_permd_data} structure is defined as:
@example
struct bookmarkfs_permd_data @{
enum bookmarkfs_permd_op @var{op};
char @var{name1}[NAME_MAX + 1];
char @var{name2}[NAME_MAX + 1];
@};
@end example
The @code{op} field denotes the operation to perform on @code{dirfd}:
@table @code
@item BOOKMARKFS_PERMD_OP_SWAP
Exchange the positions of the directory entries represented by @code{name1}
and @code{name2}.
@item BOOKMARKFS_PERMD_OP_MOVE_BEFORE
Move the directory entry represented by @code{name1} to the position just
@emph{before} the one represented by @code{name2}.
@item BOOKMARKFS_PERMD_OP_MOVE_AFTER
Move the directory entry represented by @code{name1} to the position just
@emph{after} the one represented by @code{name2}.
@end table
On success, @code{ioctl()} returns @code{0}.
Otherwise, it returns @code{-1} and sets @code{errno}:
@table @code
@item EACCES
Write or search permission is denied for the directory.
@item EINVAL
@code{op} is not one of the values defined in enum @code{bookmarkfs_permd_op}.
@item EINVAL
@code{name1} or @code{name2} is not a valid filename
(e.g. empty string; contains slash character, ...).
@item ENOENT
The directory does not contain @code{name1} or @code{name2}.
@item EPERM
The backend does not support rearranging entries for this directory.
@end table
To ensure that the order change is visible to further @code{readdir()} calls,
call @code{fsync()} or @code{close()} on @code{dirfd}.
@node Check for Errors @node Check for Errors
@section Check for Errors @section Check for Errors