| FDISCARD(2) | System Calls Manual | FDISCARD(2) | 
posix_fallocate, fdiscard
  —
#include <fcntl.h>
int
  
  posix_fallocate(int
    fd, off_t pos,
    off_t length);
#include
    <unistd.h>
int
  
  fdiscard(int
    fd, off_t pos,
    off_t length);
posix_fallocate() call allocates backing store for
  the file referenced by fd in the region starting at
  pos bytes from the start of the file and continuing for
  length bytes more. If the region extends past the
  current end of file, the file size is increased to cover the region.
The fdiscard() call discards backing store
    for the file referenced by fd in the region starting
    at pos bytes from the start of the file and continuing
    for length bytes more. The file size is not
  affected.
Both calls operate on the basis of file system blocks, so
    posix_fallocate() may allocate more physical space
    than requested and fdiscard() may discard less
    physical space than requested.
When posix_fallocate() is applied to an
    unallocated region in a regular file (a “hole”), the hole is
    filled and the visible contents are unaffected; both holes and newly
    allocated regions read as all zeros. If
    posix_fallocate() is applied to an already-allocated
    region in a regular file, it has no effect.
When fdiscard() is applied to a regular
    file, a hole is created and any data in the affected region is thrown away.
    Subsequent reads of the region return zeros.
If fdiscard() is applied to a device, and
    the device supports an underlying discard operation, that operation is
    invoked. For example, ATA flash devices and solid-state disks support an
    operation called TRIM that discards blocks at the device level. The behavior
    of blocks discarded at this level is implementation-defined; as devices
    vary, specific behavior should not be relied upon. Subsequent reads of the
    same block may return zeros; such reads may also, however, continue to
    return the previously written data, or return other data, or return
    indeterminate garbage; or may switch between any of these behaviors at
    unpredictable points later on.
For both calls, the file fd must be open for writing and may not be a directory or socket.
posix_fallocate() to report
  a partial failure, errors may require some or all of the work it has already
  done to be unwound, which may be expensive. It is recommended to set the file
  length first with
  ftruncate(2) and only then
  allocate space within the file using
  posix_fallocate().
Depending on the implementation, even a failing call to
    posix_fallocate() may allocate some space to the
    target file. Such a call will not, however, change the file size.
Furthermore, in some implementations, the space reservations
    created by posix_fallocate() may not be persistent
    after a crash or reboot if the space reserved has not yet been written
  to.
posix_fallocate() function will
  return zero. Otherwise an error number will be returned, without setting
  errno.
If successful, the fdiscard() function
    will return zero. Otherwise the value -1 is returned and the global variable
    errno is set to indicate the error.
EBADF]EDQUOT]EINVAL]EIO]EISDIR]ENOSPC]posix_fallocate() and
  fdiscard() function calls appeared in
  NetBSD 7.0. Similar functions appeared previously in
  Linux. The posix_fallocate() function is expected to
  conform to IEEE Std 1003.1-2004
  (“POSIX.1”).
| June 30, 2016 | NetBSD 10.0 |