Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add userlevel manifestations of posix_fallocate and fdiscard...
details: https://anonhg.NetBSD.org/src/rev/3014bd9c1313
branches: trunk
changeset: 797675:3014bd9c1313
user: dholland <dholland%NetBSD.org@localhost>
date: Fri Jul 25 08:30:47 2014 +0000
description:
Add userlevel manifestations of posix_fallocate and fdiscard, in
unistd.h and libc, and add a man page.
Allow wiggle room in the man page for implementations of fallocate
that either (a) don't fully unwind on failure, leaving new blocks
allocated without changing the file size, or (b) create only in-memory
transient reservations that disappear when crashing or rebooting.
Also, add crossreference to fdiscard 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.
diffstat:
include/unistd.h | 4 +-
lib/libc/sys/Makefile.inc | 13 ++-
lib/libc/sys/fdiscard.2 | 164 ++++++++++++++++++++++++++++++++++++++++++++++
lib/libc/sys/truncate.2 | 10 +-
4 files changed, 179 insertions(+), 12 deletions(-)
diffs (278 lines):
diff -r eeb261604e90 -r 3014bd9c1313 include/unistd.h
--- a/include/unistd.h Fri Jul 25 08:30:10 2014 +0000
+++ b/include/unistd.h Fri Jul 25 08:30:47 2014 +0000
@@ -1,4 +1,4 @@
-/* $NetBSD: unistd.h,v 1.141 2014/06/18 17:48:22 christos Exp $ */
+/* $NetBSD: unistd.h,v 1.142 2014/07/25 08:30:47 dholland Exp $ */
/*-
* Copyright (c) 1998, 1999, 2008 The NetBSD Foundation, Inc.
@@ -173,6 +173,7 @@
*/
#if (_POSIX_C_SOURCE - 0) >= 200112L || (_XOPEN_SOURCE - 0) >= 600 || \
defined(_NETBSD_SOURCE)
+int posix_fallocate(int, off_t, off_t);
int setegid(gid_t);
int seteuid(uid_t);
#endif
@@ -328,6 +329,7 @@
void endusershell(void);
int exect(const char *, char * const *, char * const *);
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 eeb261604e90 -r 3014bd9c1313 lib/libc/sys/Makefile.inc
--- a/lib/libc/sys/Makefile.inc Fri Jul 25 08:30:10 2014 +0000
+++ b/lib/libc/sys/Makefile.inc Fri Jul 25 08:30:47 2014 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile.inc,v 1.223 2014/01/31 20:45:49 christos Exp $
+# $NetBSD: Makefile.inc,v 1.224 2014/07/25 08:30:47 dholland Exp $
# @(#)Makefile.inc 8.3 (Berkeley) 10/24/94
# sys sources
@@ -147,10 +147,11 @@
.endfor
WEAKASM= accept.S __aio_suspend50.S close.S connect.S execve.S \
- fcntl.S fdatasync.S fsync.S fsync_range.S __kevent50.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 \
+ __pollts50.S posix_fallocate.S __pselect50.S read.S readlink.S \
readv.S _sched_setparam.S _sched_getparam.S _sched_setaffinity.S \
_sched_getaffinity.S sched_yield.S \
__select50.S setcontext.S __sigprocmask14.S __sigsuspend14.S sysarch.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 \
+ fcntl.2 fdatasync.2 fdiscard.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 \
@@ -235,7 +236,8 @@
mount.2 \
mprotect.2 mremap.2 msgctl.2 msgget.2 msgrcv.2 msgsnd.2 msync.2 \
munmap.2 nanosleep.2 nfssvc.2 ntp_adjtime.2 open.2 pathconf.2 pipe.2 \
- pmc_control.2 poll.2 posix_fadvise.2 profil.2 ptrace.2 __quotactl.2 \
+ pmc_control.2 poll.2 posix_fadvise.2 \
+ profil.2 ptrace.2 __quotactl.2 \
rasctl.2 read.2 readlink.2 \
reboot.2 recv.2 rename.2 revoke.2 rmdir.2 \
select.2 semctl.2 \
@@ -275,6 +277,7 @@
MLINKS+=access.2 faccessat.2
MLINKS+=chmod.2 fchmodat.2
MLINKS+=chown.2 fchownat.2
+MLINKS+=fdiscard.2 posix_fallocate.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 eeb261604e90 -r 3014bd9c1313 lib/libc/sys/fdiscard.2
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/sys/fdiscard.2 Fri Jul 25 08:30:47 2014 +0000
@@ -0,0 +1,164 @@
+.\" $NetBSD: fdiscard.2,v 1.1 2014/07/25 08:30:47 dholland Exp $
+.\"
+.\" 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 July 25, 2014
+.Dt FDISCARD 2
+.Os
+.Sh NAME
+.Nm posix_fallocate ,
+.Nm fdiscard
+.Nd allocate or discard backing store for files
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In unistd.h
+.Ft int
+.Fn posix_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 posix_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 posix_fallocate
+may allocate more physical space than requested and
+.Fn fdiscard
+may discard less physical space than requested.
+.Pp
+When
+.Fn posix_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 posix_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 RESTRICTIONS
+Because there is no way for
+.Fn posix_fallocate
+to report a partial failure, errors may require some or all of the
+work it has already done to be unwound, which may be expensive.
+It is recommended to set the file length first with
+.Xr ftruncate 2
+and only then allocate space within the file using
+.Fn posix_fallocate .
+.Pp
+Depending on the implementation, even a failing call to
+.Fn posix_fallocate
+may allocate some space to the target file.
+Such a call will not, however, change the file size.
+.Pp
+Furthermore, in some implementations, the space reservations created
+by
+.Fn posix_fallocate
+may not be persistent after a crash or reboot if the space reserved
+has not yet been written to.
+.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 posix_fallocate
+and
+.Fn fdiscard
+function calls appeared in
+.Nx 7.0 .
+Similar functions appeared previously in Linux.
+The
+.Fn posix_fallocate
+function is expected to conform to
+.St -p1003.1-2004 .
diff -r eeb261604e90 -r 3014bd9c1313 lib/libc/sys/truncate.2
--- a/lib/libc/sys/truncate.2 Fri Jul 25 08:30:10 2014 +0000
+++ b/lib/libc/sys/truncate.2 Fri Jul 25 08:30:47 2014 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: truncate.2,v 1.28 2014/06/14 19:02:29 wiz Exp $
+.\" $NetBSD: truncate.2,v 1.29 2014/07/25 08:30:47 dholland Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -29,7 +29,7 @@
.\"
.\" @(#)truncate.2 8.1 (Berkeley) 6/4/93
.\"
-.Dd June 14, 2014
+.Dd July 23, 2014
.Dt TRUNCATE 2
.Os
.Sh NAME
@@ -133,7 +133,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
@@ -151,6 +152,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.
Home |
Main Index |
Thread Index |
Old Index