# HG changeset patch # Parent 9411be3550961a8267064de3dc5bc94d448d5d1b Add userlevel manifestations of fallocate and fdiscard, in unistd.h and libc, and add a man page. Also, add crossreference to that page from ftruncate(2), and remove the old BUGS entry from there that called for a generalized version that allows discarding ranges of a file: that's what fdiscard is. diff -r 9411be355096 include/unistd.h --- a/include/unistd.h Sun Mar 23 04:34:20 2014 -0400 +++ b/include/unistd.h Sun Mar 23 05:02:26 2014 -0400 @@ -327,7 +327,9 @@ int dup3(int, int, int); void endusershell(void); int exect(const char *, char * const *, char * const *); +int fallocate(int, off_t, off_t); int fchroot(int); +int fdiscard(int, off_t, off_t); int fsync_range(int, int, off_t, off_t); int getdomainname(char *, size_t); int getgrouplist(const char *, gid_t, gid_t *, int *); diff -r 9411be355096 lib/libc/sys/Makefile.inc --- a/lib/libc/sys/Makefile.inc Sun Mar 23 04:34:20 2014 -0400 +++ b/lib/libc/sys/Makefile.inc Sun Mar 23 05:02:26 2014 -0400 @@ -147,7 +147,8 @@ .endfor WEAKASM= accept.S __aio_suspend50.S close.S connect.S execve.S \ - fcntl.S fdatasync.S fsync.S fsync_range.S __kevent50.S \ + fallocate.S fcntl.S fdatasync.S fdiscard.S fsync.S \ + fsync_range.S __kevent50.S \ kill.S mq_receive.S mq_send.S __mq_timedreceive50.S __mq_timedsend50.S \ msgrcv.S msgsnd.S __msync13.S __nanosleep50.S open.S poll.S \ __pollts50.S __pselect50.S read.S readlink.S \ @@ -216,7 +217,7 @@ MAN+= accept.2 access.2 acct.2 adjtime.2 bind.2 brk.2 chdir.2 \ chflags.2 chmod.2 chown.2 chroot.2 clock_settime.2 clone.2 close.2 \ connect.2 dup.2 execve.2 _exit.2 extattr_get_file.2 \ - fcntl.2 fdatasync.2 fhopen.2 \ + fallocate.2 fcntl.2 fdatasync.2 fhopen.2 \ flock.2 fork.2 fsync.2 getcontext.2 getdents.2 \ getfh.2 getvfsstat.2 getgid.2 getgroups.2 \ getitimer.2 getlogin.2 getpeername.2 getpgrp.2 getpid.2 \ @@ -275,6 +276,7 @@ MLINKS+=access.2 faccessat.2 MLINKS+=chmod.2 fchmodat.2 MLINKS+=chown.2 fchownat.2 +MLINKS+=fallocate.2 fdiscard.2 MLINKS+=fhopen.2 fhstat.2 fhopen.2 fhstatvfs.2 fhopen.2 fhstatvfs1.2 MLINKS+=stat.2 fstatat.2 MLINKS+=fsync.2 fsync_range.2 diff -r 9411be355096 lib/libc/sys/fallocate.2 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lib/libc/sys/fallocate.2 Sun Mar 23 05:02:26 2014 -0400 @@ -0,0 +1,140 @@ +.\" $NetBSD$ +.\" +.\" Copyright (c) 2014 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David A. Holland. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 23, 2014 +.Dt FALLOCATE 2 +.Os +.Sh NAME +.Nm fallocate , +.Nm fdiscard +.Nd allocate or discard backing store for files +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn fallocate "int fd" "off_t pos" "off_t length" +.Ft int +.Fn fdiscard "int fd" "off_t pos" "off_t length" +.Sh DESCRIPTION +The +.Fn fallocate +call allocates backing store for the file referenced by +.Fa fd +in the region starting at +.Fa pos +bytes from the start of the file and continuing for +.Fa length +bytes more. +If the region extends past the current end of file, the file size is +increased to cover the region. +.Pp +The +.Fn fdiscard +call discards backing store for the file referenced by +.Fa fd +in the region starting at +.Fa pos +bytes from the start of the file and continuing for +.Fa length +bytes more. +The file size is not affected. +.Pp +Both calls operate on the basis of file system blocks, so +.Fn fallocate +may allocate more physical space than requested and +.Fn fdiscard +may discard less physical space than requested. +.Pp +When +.Fn fallocate +is applied to an unallocated region in a regular file (a +.Dq hole ), +the hole is filled and the visible contents are unaffected; both holes +and newly allocated regions read as all zeros. +If +.Fn fallocate +is applied to an already-allocated region in a regular file, +it has no effect. +.Pp +When +.Fn 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. +.Pp +If +.Fn 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. +.Pp +For both calls, the file +.Fa fd +must be open for writing and may not be a directory or socket. +.Sh RETURN VALUES +On success these calls return 0. +On error, \-1 is returned, and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The file handle +.Fa fd +is invalid or not open for writing. +.It Bq Er EINVAL +The position and/or length values are negative. +.It Bq Er EISDIR +The selected file is a directory. +.It Bq Er EIO +A hardware-level I/O error occurred. +.It Bq Er ENOSPC +There was no space in the filesystem to complete the operation. +.It Bq Er EDQUOT +Allocating the requested blocks would exceed the user's quota. +.El +.Sh SEE ALSO +.Xr ftruncate 2 +.Sh HISTORY +The +.Fn fallocate +and +.Fn fdiscard +function calls appeared in +.Nx 7.0 . +Similar functions appeared previously in Linux. diff -r 9411be355096 lib/libc/sys/truncate.2 --- a/lib/libc/sys/truncate.2 Sun Mar 23 04:34:20 2014 -0400 +++ b/lib/libc/sys/truncate.2 Sun Mar 23 05:02:26 2014 -0400 @@ -29,7 +29,7 @@ .\" .\" @(#)truncate.2 8.1 (Berkeley) 6/4/93 .\" -.Dd March 16, 2008 +.Dd March 23, 2014 .Dt TRUNCATE 2 .Os .Sh NAME @@ -129,7 +129,8 @@ is not open for writing. .El .Sh SEE ALSO -.Xr open 2 +.Xr open 2 , +.Xr fdiscard 2 .Sh STANDARDS Use of .Fn truncate @@ -147,6 +148,3 @@ .Fn ftruncate function calls appeared in .Bx 4.2 . -.Sh BUGS -These calls should be generalized to allow ranges -of bytes in a file to be discarded.