From b1cbb2de59b90140ec521dec062c4959dc9fab75 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 24 Sep 2007 21:35:19 +0000 Subject: 2007-09-24 Joel Sherrill PR 1262/filesystem * posix_users/io.t: Add support for readv() and writev() including documentation and test case. --- doc/posix_users/io.t | 149 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 141 insertions(+), 8 deletions(-) (limited to 'doc/posix_users/io.t') diff --git a/doc/posix_users/io.t b/doc/posix_users/io.t index 570772c543..c40c9f38d9 100644 --- a/doc/posix_users/io.t +++ b/doc/posix_users/io.t @@ -28,6 +28,8 @@ The directives provided by the input and output primitives manager are: @item @code{sync} - Schedule file system updates @item @code{mount} - Mount a file system @item @code{unmount} - Unmount file systems +@item @code{readv} - Vectored read from a file +@item @code{writev} - Vectored write to a file @item @code{aio_read} - Asynchronous Read @item @code{aio_write} - Asynchronous Write @item @code{lio_listio} - List Directed I/O @@ -178,7 +180,7 @@ and tried to open a new one. @subheading DESCRIPTION: -@code{Dup2} creates a copy of the file descriptor @code{oldfd}. +@code{dup2} creates a copy of the file descriptor @code{oldfd}. The old and new descriptors may be used interchangeably. They share locks, file position pointers and flags; for example, if the file position is modified by using @@ -192,7 +194,7 @@ NONE @c @c @page -@subsection close - Closes a file. +@subsection close - Closes a file @findex close @cindex closes a file. @@ -238,10 +240,10 @@ may or may not be closed. @c @c @page -@subsection read - Reads from a file. +@subsection read - Reads from a file @findex read -@cindex reads from a file. +@cindex reads from a file @subheading CALLING SEQUENCE: @@ -279,6 +281,9 @@ Function was interrupted by a signal. @item EIO Input or output error +@item EINVAL +Bad buffer pointer + @end table @subheading DESCRIPTION: @@ -387,6 +392,9 @@ No space left on disk. @item EPIPE Attempt to write to a pope or FIFO with no reader. +@item EINVAL +Bad buffer pointer + @end table @subheading DESCRIPTION: @@ -575,13 +583,13 @@ int lseek( @table @b @item EBADF -@code{Fildes} is not an open file descriptor. +@code{fildes} is not an open file descriptor. @item ESPIPE -@code{Fildes} is associated with a pipe, socket or FIFO. +@code{fildes} is associated with a pipe, socket or FIFO. @item EINVAL -@code{Whence} is not a proper value. +@code{whence} is not a proper value. @end table @@ -673,7 +681,7 @@ NONE @c @c @page -@subsection fdatasync - Synchronize file in-core data with that on disk. +@subsection fdatasync - Synchronize file in-core data with that on disk @findex fdatasync @cindex synchronize file in @@ -855,6 +863,131 @@ by @code{mount_path}. NONE +@c +@c +@c +@page +@subsection readv - Vectored read from a file + +@findex readv +@cindex vectored read from a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include + +ssize_t readv( + int fd, + const struct iovec *iov, + int iovcnt +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +In addition to the errors detected by +@code{Input and Output Primitives Manager read - Reads from a file, read()}, +this routine may return -1 and sets @code{errno} based upon the following +errors: + +@table @b +@item EINVAL +The sum of the @code{iov_len} values in the iov array overflowed an +@code{ssize_t}. + +@item EINVAL +The @code{iovcnt} argument was less than or equal to 0, or greater +than @code{IOV_MAX}. + +@end table + +@subheading DESCRIPTION: + +The @code{readv()} function is equivalent to @code{read()} +except as described here. The @code{readv()} function shall place +the input data into the @code{iovcnt} buffers specified by the +members of the @code{iov} array: @code{iov[0], iov[1], ..., iov[iovcnt-1]}. + +Each @code{iovec} entry specifies the base address and length of an area +in memory where data should be placed. The @code{readv()} function +always fills an area completely before proceeding to the next. + +@subheading NOTES: + +NONE + +@c +@c +@c +@page +@subsection writev - Vectored write to a file + +@findex writev +@cindex vectored write to a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include + +ssize_t writev( + int fd, + const struct iovec *iov, + int iovcnt +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +In addition to the errors detected by +@code{Input and Output Primitives Manager write - Write to a file, write()}, +this routine may return -1 and sets @code{errno} based upon the following +errors: + +@table @b +@item EINVAL +The sum of the @code{iov_len} values in the iov array overflowed an +@code{ssize_t}. + +@item EINVAL +The @code{iovcnt} argument was less than or equal to 0, or greater +than @code{IOV_MAX}. + +@end table + +@subheading DESCRIPTION: + +The @code{writev()} function is equivalent to @code{write()}, +except as noted here. The @code{writev()} function gathers output +data from the @code{iovcnt} buffers specified by the members of +the @code{iov array}: @code{iov[0], iov[1], ..., iov[iovcnt-1]}. +The @code{iovcnt} argument is valid if greater than 0 and less +than or equal to @code{IOV_MAX}. + +Each @code{iovec} entry specifies the base address and length of +an area in memory from which data should be written. The @code{writev()} +function always writes a complete area before proceeding to the next. + +If @code{fd} refers to a regular file and all of the @code{iov_len} +members in the array pointed to by @code{iov} are 0, @code{writev()} +returns 0 and has no other effect. For other file types, the behavior +is unspecified by POSIX. + +@subheading NOTES: + +NONE + @c @c @c -- cgit v1.2.3