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 9.0 |