NetBSD/share/man/man9/dofileread.9

.\"     $NetBSD: dofileread.9,v 1.9 2010/12/02 12:54:13 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" 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 December 20, 2005
.Dt DOFILEREAD 9
.Os
.Sh NAME
.Nm dofileread ,
.Nm dofilereadv ,
.Nm dofilewrite ,
.Nm dofilewritev
.Nd high-level file operations
.Sh SYNOPSIS
.In sys/file.h
.Ft int
.Fn dofileread "struct lwp *l" "int fd" "struct file *fp" "void *buf" \
"size_t nbyte" "off_t *offset" "int flags" "register_t *retval"
.Ft int
.Fn dofilewrite "struct lwp *l" "int fd" "struct file *fp" \
"const void *buf" "size_t nbyte" "off_t *offset" "int flags" \
"register_t *retval"
.Ft int
.Fn dofilereadv "struct lwp *l" "int fd" "struct file *fp" \
"const struct iovec *iovp" "int iovcnt" "off_t *offset" "int flags" \
"register_t *retval"
.Ft int
.Fn dofilewritev "struct lwp *l" "int fd" "struct file *fp" \
"const struct iovec *iovp" "int iovcnt" "off_t *offset" "int flags" \
"register_t *retval"
.Sh DESCRIPTION
The functions implement the underlying functionality of the
.Xr read 2 ,
.Xr write 2 ,
.Xr readv 2 ,
and
.Xr writev 2
system calls.
They are also used throughout the kernel as high-level access routines
for file I/O.
.Pp
The
.Fn dofileread
function attempts to read
.Fa nbytes
of data from the object referenced by file entry
.Fa fp
into the buffer pointed to by
.Fa buf .
The
.Fn dofilewrite
function attempts to write
.Fa nbytes
of data to the object referenced by file entry
.Fa fp
from the buffer pointed to by
.Fa buf .
.Pp
The
.Fn dofilereadv
and
.Fn dofilewritev
functions perform the same operations, but scatter the data with the
.Fa iovcnt
buffers specified by the members of the
.Fa iov
array.
.Pp
The offset of the file operations is explicitly specified by
.Fa *offset .
The new file offset after the file operation is returned in
.Fa *offset .
If the FOF_UPDATE_OFFSET flag is specified in the
.Fa flags
argument, the file offset in the file entry
.Fa fp
is updated to reflect the new file offset, otherwise it remains
unchanged after the operation.
.Pp
The file descriptor
.Fa fd
is largely unused except for use by the ktrace framework for reporting
to userlevel the process's file descriptor.
.Pp
Upon successful completion the number of bytes which were transferred
is returned in
.Fa *retval .
.Sh RETURN VALUES
Upon successful completion zero is returned, otherwise an appropriate
error is returned.
.Sh CODE REFERENCES
The framework for these file operations is implemented within the file
.Pa sys/kern/sys_generic.c .
.Sh SEE ALSO
.Xr file 9