# 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.