From 03c44ce523664be71df5825c6048b5e05ec4856a Mon Sep 17 00:00:00 2001 From: yamt Date: Sun, 19 Feb 2006 22:27:47 +0000 Subject: [PATCH] document posix_fadvise. --- distrib/sets/lists/comp/mi | 4 +- lib/libc/sys/Makefile.inc | 6 +- lib/libc/sys/posix_fadvise.2 | 108 +++++++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+), 4 deletions(-) create mode 100644 lib/libc/sys/posix_fadvise.2 diff --git a/distrib/sets/lists/comp/mi b/distrib/sets/lists/comp/mi index 3602914140e3..237771fa41cf 100644 --- a/distrib/sets/lists/comp/mi +++ b/distrib/sets/lists/comp/mi @@ -1,4 +1,4 @@ -# $NetBSD: mi,v 1.852 2006/02/14 19:07:30 he Exp $ +# $NetBSD: mi,v 1.853 2006/02/19 22:30:20 yamt Exp $ ./etc/mtree/set.comp comp-sys-root ./usr/bin/addr2line comp-debug-bin bfd ./usr/bin/ar comp-util-bin bfd @@ -4069,6 +4069,7 @@ ./usr/share/man/cat3/pnoutrefresh.0 comp-c-catman .cat ./usr/share/man/cat3/popen.0 comp-c-catman .cat ./usr/share/man/cat3/pos_form_cursor.0 comp-c-catman .cat +./usr/share/man/cat3/posix_fadvise.0 comp-c-catman .cat ./usr/share/man/cat3/posix_openpt.0 comp-c-catman .cat ./usr/share/man/cat3/post_form.0 comp-c-catman .cat ./usr/share/man/cat3/pow.0 comp-c-catman .cat @@ -8021,6 +8022,7 @@ ./usr/share/man/man3/pnoutrefresh.3 comp-c-man .man ./usr/share/man/man3/popen.3 comp-c-man .man ./usr/share/man/man3/pos_form_cursor.3 comp-c-man .man +./usr/share/man/man3/posix_fadvise.3 comp-c-man .man ./usr/share/man/man3/posix_openpt.3 comp-c-man .man ./usr/share/man/man3/post_form.3 comp-c-man .man ./usr/share/man/man3/pow.3 comp-c-man .man diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index e3d0e247c205..90b5bd6c54a4 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -1,4 +1,4 @@ -# $NetBSD: Makefile.inc,v 1.162 2006/01/20 22:03:23 christos Exp $ +# $NetBSD: Makefile.inc,v 1.163 2006/02/19 22:27:47 yamt Exp $ # @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 # sys sources @@ -169,8 +169,8 @@ MAN+= accept.2 access.2 acct.2 adjtime.2 bind.2 brk.2 chdir.2 \ madvise.2 mincore.2 minherit.2 mlock.2 mlockall.2 mmap.2 mount.2 \ mprotect.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 profil.2 ptrace.2 quotactl.2 rasctl.2 \ - read.2 readlink.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 \ sa_register.2 sa_stacks.2 sa_enable.2 sa_setconcurrency.2 sa_yield.2 \ select.2 semctl.2 \ diff --git a/lib/libc/sys/posix_fadvise.2 b/lib/libc/sys/posix_fadvise.2 new file mode 100644 index 000000000000..f83cfa00ea33 --- /dev/null +++ b/lib/libc/sys/posix_fadvise.2 @@ -0,0 +1,108 @@ +.\" $NetBSD: posix_fadvise.2,v 1.1 2006/02/19 22:27:48 yamt Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" 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 AUTHOR 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 AUTHOR 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 February 20, 2006 +.Dt POSIX_FADVISE 2 +.Os +.Sh NAME +.Nm posix_fadvise +.Nd give a hint about a future access pattern of a file +.\" ------------------------------------------------------------ +.Sh LIBRARY +.Lb libc +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/fcntl.h +.Ft int +.Fn posix_fadvise "int fd" "off_t offset" "off_t size" "int hint" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Fn posix_fadvise +gives a hint about the application's access pattern to the range +given by +the file descriptor, +.Fa fd , +and +.Fa offset +and +.Fa size . +If +.Fa size +is zero, it means to the end of file. +.Pp +.Fa hint +should be one of the followings. +.Pp +.Bl -tag -offset indent -width POSIX_FADV_SEQUENTIAL -compact +.It POSIX_FADV_NORMAL +No hint. +(default) +.It POSIX_FADV_RANDOM +Random access. +.It POSIX_FADV_SEQUENTIAL +Sequential access. +(from lower offset to higher offset.) +.It POSIX_FADV_WILLNEED +Will be accessed. +.It POSIX_FADV_DONTNEED +Will not be accessed. +.It POSIX_FADV_NOREUSE +Will be accessed just once. +.El +.Pp +Calling +.Fn posix_fadvise +doesn't alter semantics of operations. +It's only a matter of the performance. +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +On success, +.Fn posix_fadvise +returns 0. +Otherwise, it returns an error number. +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr errno 2 , +.Xr madvise 2 +.\" ------------------------------------------------------------ +.Sh BUGS +.Dv POSIX_FADV_WILLNEED , +.Dv POSIX_FADV_DONTNEED , +and +.Dv POSIX_FADV_NOREUSE +are not implemented. +.Pp +For +.Dv POSIX_FADV_NORMAL , +.Dv POSIX_FADV_RANDOM , +and +.Dv POSIX_FADV_SEQUENTIAL , +the current implemetation ignores +.Fa offset +and +.Fa size , +and applies the hint to the whole file.