posix_fallocate(2) - NetBSD Manual Pages

FDISCARD(2)               NetBSD System Calls Manual               FDISCARD(2)


NAME

     posix_fallocate, fdiscard -- allocate or discard backing store for files


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <unistd.h>

     int
     posix_fallocate(int fd, off_t pos, off_t length);

     int
     fdiscard(int fd, off_t pos, off_t length);


DESCRIPTION

     The posix_fallocate() call allocates backing store for the file refer-
     enced 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 con-
     tinuing 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 unaf-
     fected; 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 underly-
     ing discard operation, that operation is invoked.  For example, ATA flash
     devices and solid-state disks support an operation called TRIM that dis-
     cards 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.


RESTRICTIONS

     Because there is no way for posix_fallocate() to report a partial fail-
     ure, 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, how-
     ever, 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.


RETURN VALUES

     If successful, the posix_fallocate() function will return zero.  Other-
     wise 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.


ERRORS

     [EBADF]            The file handle fd is invalid or not open for writing.

     [EDQUOT]           Allocating the requested blocks would exceed the
                        user's quota.

     [EINVAL]           The position and/or length values are negative.

     [EIO]              A hardware-level I/O error occurred.

     [EISDIR]           The selected file is a directory.

     [ENOSPC]           There was no space in the file system to complete the
                        operation.


SEE ALSO

     ftruncate(2)


HISTORY

     The 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'').

NetBSD 7.0                     February 1, 2015                     NetBSD 7.0