ffence syscall man page mockup

gistfile1.txt

# 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.