NAME
posix_fallocate,
fdiscard —
allocate or discard backing store for files
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#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);
DESCRIPTION
The
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.
RESTRICTIONS
Because there is no way for
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.
RETURN VALUES
If successful, the
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.
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”).