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
@node Permute Directory Entries
@section Permute Directory Entries
@node Directory Entry Ordering
@section Directory Entry Ordering
POSIX does not specify the ordering of the directory entries retrieved from
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.
@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
@section Check for Errors