1.\" $NetBSD: fdiscard.2,v 1.3 2015/02/01 15:24:15 christos 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 February 1, 2015 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 unistd.h 41.Ft int 42.Fn posix_fallocate "int fd" "off_t pos" "off_t length" 43.Ft int 44.Fn fdiscard "int fd" "off_t pos" "off_t length" 45.Sh DESCRIPTION 46The 47.Fn posix_fallocate 48call allocates backing store for the file referenced by 49.Fa fd 50in the region starting at 51.Fa pos 52bytes from the start of the file and continuing for 53.Fa length 54bytes more. 55If the region extends past the current end of file, the file size is 56increased to cover the region. 57.Pp 58The 59.Fn fdiscard 60call discards backing store for the file referenced by 61.Fa fd 62in the region starting at 63.Fa pos 64bytes from the start of the file and continuing for 65.Fa length 66bytes more. 67The file size is not affected. 68.Pp 69Both calls operate on the basis of file system blocks, so 70.Fn posix_fallocate 71may allocate more physical space than requested and 72.Fn fdiscard 73may discard less physical space than requested. 74.Pp 75When 76.Fn posix_fallocate 77is applied to an unallocated region in a regular file (a 78.Dq hole ) , 79the hole is filled and the visible contents are unaffected; both holes 80and newly allocated regions read as all zeros. 81If 82.Fn posix_fallocate 83is applied to an already-allocated region in a regular file, 84it has no effect. 85.Pp 86When 87.Fn fdiscard 88is applied to a regular file, a hole is created and any data in the 89affected region is thrown away. 90Subsequent reads of the region return zeros. 91.Pp 92If 93.Fn fdiscard 94is applied to a device, and the device supports an underlying discard 95operation, that operation is invoked. 96For example, ATA flash devices and solid-state disks support an 97operation called TRIM that discards blocks at the device level. 98The behavior of blocks discarded at this level is 99implementation-defined; as devices vary, specific behavior should not 100be relied upon. 101Subsequent reads of the same block may return zeros; such reads may 102also, however, continue to return the previously written data, or 103return other data, or return indeterminate garbage; or may switch 104between any of these behaviors at unpredictable points later on. 105.Pp 106For both calls, the file 107.Fa fd 108must be open for writing and may not be a directory or socket. 109.Sh RESTRICTIONS 110Because there is no way for 111.Fn posix_fallocate 112to report a partial failure, errors may require some or all of the 113work it has already done to be unwound, which may be expensive. 114It is recommended to set the file length first with 115.Xr ftruncate 2 116and only then allocate space within the file using 117.Fn posix_fallocate . 118.Pp 119Depending on the implementation, even a failing call to 120.Fn posix_fallocate 121may allocate some space to the target file. 122Such a call will not, however, change the file size. 123.Pp 124Furthermore, in some implementations, the space reservations created 125by 126.Fn posix_fallocate 127may not be persistent after a crash or reboot if the space reserved 128has not yet been written to. 129.Sh RETURN VALUES 130If successful, the 131.Fn posix_fallocate 132function will return zero. 133Otherwise an error number will be returned, without setting 134.Va errno . 135.Pp 136If successful, the 137.Fn fdiscard 138function will return zero. 139Otherwise the value \-1 is returned and the global variable 140.Va errno 141is set to indicate the error. 142.Sh ERRORS 143.Bl -tag -width Er 144.It Bq Er EBADF 145The file handle 146.Fa fd 147is invalid or not open for writing. 148.It Bq Er EDQUOT 149Allocating the requested blocks would exceed the user's quota. 150.It Bq Er EINVAL 151The position and/or length values are negative. 152.It Bq Er EIO 153A hardware-level I/O error occurred. 154.It Bq Er EISDIR 155The selected file is a directory. 156.It Bq Er ENOSPC 157There was no space in the file system to complete the operation. 158.El 159.Sh SEE ALSO 160.Xr ftruncate 2 161.Sh HISTORY 162The 163.Fn posix_fallocate 164and 165.Fn fdiscard 166function calls appeared in 167.Nx 7.0 . 168Similar functions appeared previously in Linux. 169The 170.Fn posix_fallocate 171function is expected to conform to 172.St -p1003.1-2004 . 173