Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save eaglgenes101/86c0c8644853ecc1bf7fa000b3ee4873 to your computer and use it in GitHub Desktop.
Save eaglgenes101/86c0c8644853ecc1bf7fa000b3ee4873 to your computer and use it in GitHub Desktop.
ffence syscall man page mockup
# Name
ffence - Emit write barriers
# Synopsis
```
#define _GNU_SOURCE /* See feature_test_macros(7) */
#include <fcntl.h>
int ffence(int fd, unsigned int flags);
```
# Description
`ffence()` constrains the order of writes of modified in-core data of
(i.e., modified buffer cache pages for) the file referred to by the file
descriptor fd to the disk device (or other permanent storage device),
ensuring that some writes don't appear out of order in the event of a
system crash or a reboot. Specifically, `ffence()` ensures that writes to
the file referred to by `fd` from before the syscall do not visibly
reorder with writes afterwards.
The flags bit-mask argument can include any of the following values:
## FENCE_DIR
The aforementioned ordering effects also apply to the reachability of
the file referred to by `fd` from directories, and any metadata this
entails.
## FENCE_FS
The aforementioned ordering effects apply not only to the file referred
to by `fd` and directories that link to it, but also the entire
filesystem containing the file.
## FENCE_METADATA
The aforementioned ordering effects also apply to metadata associated
with the file referred to by `fd`. If `FENCE_DIR` is set, the ordering
effects also apply to directories containing the files, and if
`FENCE_FS` is set, the ordering effects extend to the filesystem
containing the file.
Writes before `ffence()` may still appear out-of-order with respect to
each other, and likewise for writes after `ffence()`, subject to the
constraints of `ffence()` calls or other file system write ordering calls.
`ffence()` also does not ensure that any particular sequence of writes is
atomic; the state of the data after a system crash or reboot may still be
torn. Nor does `ffence()` cause data to be flushed to the storage device;
for that, use `fsync()`.
# Return Value
On success, `ffence()` returns 0; on failure -1 is returned and errno is
set to indicate the error.
# Errors
## EBADF
`fd` is not a valid file descriptor.
## EINVAL
`flags` specifies an invalid bit.
## EIO
I/O error.
## ENOMEM
Out of memory.
## ENOSPC
Out of disk space.
## ESPIPE
`fd` refers to something other than a regular file, a block device, or a
directory.
# Versions
`ffence()` does not appear in the Linux kernel yet.
# Conforming To
This system call currently does not exist on any operating system, and thus
should be avoided in programs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment