FDISCARD(2) | System Calls Manual | FDISCARD(2) |
int
posix_fallocate(int fd, off_t pos, off_t length);
int
fdiscard(int fd, off_t pos, off_t length);
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.
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.
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.
February 1, 2015 | NetBSD 7.2 |