1.\" $NetBSD: fdiscard.2,v 1.5 2016/06/30 18:43:43 wiz Exp $ 2.\" 3.\" Copyright (c) 2014 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by David A. Holland. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 30, 2016 31.Dt FDISCARD 2 32.Os 33.Sh NAME 34.Nm posix_fallocate , 35.Nm fdiscard 36.Nd allocate or discard backing store for files 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In fcntl.h 41.Ft int 42.Fn posix_fallocate "int fd" "off_t pos" "off_t length" 43.In unistd.h 44.Ft int 45.Fn fdiscard "int fd" "off_t pos" "off_t length" 46.Sh DESCRIPTION 47The 48.Fn posix_fallocate 49call allocates backing store for the file referenced by 50.Fa fd 51in the region starting at 52.Fa pos 53bytes from the start of the file and continuing for 54.Fa length 55bytes more. 56If the region extends past the current end of file, the file size is 57increased to cover the region. 58.Pp 59The 60.Fn fdiscard 61call discards backing store for the file referenced by 62.Fa fd 63in the region starting at 64.Fa pos 65bytes from the start of the file and continuing for 66.Fa length 67bytes more. 68The file size is not affected. 69.Pp 70Both calls operate on the basis of file system blocks, so 71.Fn posix_fallocate 72may allocate more physical space than requested and 73.Fn fdiscard 74may discard less physical space than requested. 75.Pp 76When 77.Fn posix_fallocate 78is applied to an unallocated region in a regular file (a 79.Dq hole ) , 80the hole is filled and the visible contents are unaffected; both holes 81and newly allocated regions read as all zeros. 82If 83.Fn posix_fallocate 84is applied to an already-allocated region in a regular file, 85it has no effect. 86.Pp 87When 88.Fn fdiscard 89is applied to a regular file, a hole is created and any data in the 90affected region is thrown away. 91Subsequent reads of the region return zeros. 92.Pp 93If 94.Fn fdiscard 95is applied to a device, and the device supports an underlying discard 96operation, that operation is invoked. 97For example, ATA flash devices and solid-state disks support an 98operation called TRIM that discards blocks at the device level. 99The behavior of blocks discarded at this level is 100implementation-defined; as devices vary, specific behavior should not 101be relied upon. 102Subsequent reads of the same block may return zeros; such reads may 103also, however, continue to return the previously written data, or 104return other data, or return indeterminate garbage; or may switch 105between any of these behaviors at unpredictable points later on. 106.Pp 107For both calls, the file 108.Fa fd 109must be open for writing and may not be a directory or socket. 110.Sh RESTRICTIONS 111Because there is no way for 112.Fn posix_fallocate 113to report a partial failure, errors may require some or all of the 114work it has already done to be unwound, which may be expensive. 115It is recommended to set the file length first with 116.Xr ftruncate 2 117and only then allocate space within the file using 118.Fn posix_fallocate . 119.Pp 120Depending on the implementation, even a failing call to 121.Fn posix_fallocate 122may allocate some space to the target file. 123Such a call will not, however, change the file size. 124.Pp 125Furthermore, in some implementations, the space reservations created 126by 127.Fn posix_fallocate 128may not be persistent after a crash or reboot if the space reserved 129has not yet been written to. 130.Sh RETURN VALUES 131If successful, the 132.Fn posix_fallocate 133function will return zero. 134Otherwise an error number will be returned, without setting 135.Va errno . 136.Pp 137If successful, the 138.Fn fdiscard 139function will return zero. 140Otherwise the value \-1 is returned and the global variable 141.Va errno 142is set to indicate the error. 143.Sh ERRORS 144.Bl -tag -width Er 145.It Bq Er EBADF 146The file handle 147.Fa fd 148is invalid or not open for writing. 149.It Bq Er EDQUOT 150Allocating the requested blocks would exceed the user's quota. 151.It Bq Er EINVAL 152The position and/or length values are negative. 153.It Bq Er EIO 154A hardware-level I/O error occurred. 155.It Bq Er EISDIR 156The selected file is a directory. 157.It Bq Er ENOSPC 158There was no space in the file system to complete the operation. 159.El 160.Sh SEE ALSO 161.Xr ftruncate 2 162.Sh HISTORY 163The 164.Fn posix_fallocate 165and 166.Fn fdiscard 167function calls appeared in 168.Nx 7.0 . 169Similar functions appeared previously in Linux. 170The 171.Fn posix_fallocate 172function is expected to conform to 173.St -p1003.1-2004 . 174