Document pread() and pwrite().

Obtained from:	NetBSD (mostly)

3 files changed, 68 insertions, 11 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 6fdd867..dd065f1 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -1,5 +1,5 @@
 #	@(#)Makefile.inc	8.3 (Berkeley) 10/24/94
-#	$Id: Makefile.inc,v 1.59 1999/04/04 21:46:24 dt Exp $
+#	$Id: Makefile.inc,v 1.60 1999/04/05 07:38:07 bde Exp $
 
 # sys sources
 .PATH: ${.CURDIR}/../libc/${MACHINE_ARCH}/sys ${.CURDIR}/../libc/sys
@@ -124,7 +124,7 @@ MLINKS+=lseek.2 seek.2
 MLINKS+=mlock.2 munlock.2
 MLINKS+=mount.2 unmount.2
 MLINKS+=pathconf.2 fpathconf.2
-MLINKS+=read.2 readv.2
+MLINKS+=read.2 pread.2 read.2 readv.2
 MLINKS+=recv.2 recvfrom.2 recv.2 recvmsg.2
 MLINKS+=send.2 sendmsg.2 send.2 sendto.2
 MLINKS+=setpgid.2 setpgrp.2
@@ -135,7 +135,7 @@ MLINKS+=statfs.2 fstatfs.2
 MLINKS+=syscall.2 __syscall.2
 MLINKS+=truncate.2 ftruncate.2
 MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2
-MLINKS+=write.2 writev.2
+MLINKS+=write.2 pwrite.2 write.2 writev.2
 .if !defined(NO_P1003_1B)
 MLINKS+=sched_get_priority_max.2 sched_get_priority_min.2 \
 	sched_get_priority_max.2 sched_rr_get_interval.2
diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2
index 723c1bd..a66d5d8 100644
--- a/lib/libc/sys/read.2
+++ b/lib/libc/sys/read.2
@@ -36,7 +36,8 @@
 .Os BSD 4
 .Sh NAME
 .Nm read ,
-.Nm readv
+.Nm readv ,
+.Nm pread
 .Nd read input
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
@@ -46,6 +47,8 @@
 .Fn read "int d" "void *buf" "size_t nbytes"
 .Ft ssize_t
 .Fn readv "int d" "const struct iovec *iov" "int iovcnt"
+.Ft ssize_t
+.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset"
 .Sh DESCRIPTION
 .Fn Read
 attempts to read
@@ -61,6 +64,9 @@ into the
 buffers specified by the members of the
 .Fa iov
 array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
+.Fn Pread
+performs the same function, but reads from the specified position in
+the file without modifying the file pointer.
 .Pp
 For 
 .Fn readv ,
@@ -99,9 +105,10 @@ position.  The value of the pointer associated with such an
 object is undefined.
 .Pp
 Upon successful completion,
-.Fn read
+.Fn read ,
+.Fn readv ,
 and
-.Fn readv
+.Fn pread
 return the number of bytes actually read and placed in the buffer.
 The system guarantees to read the number of bytes requested if
 the descriptor references a normal file that has that many bytes left
@@ -162,9 +169,10 @@ Otherwise, a -1 is returned and the global variable
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
-.Fn Read
+.Fn Read ,
+.Fn readv ,
 and
-.Fn readv
+.Fn pread
 will succeed unless:
 .Bl -tag -width Er
 .It Bq Er EBADF
@@ -211,6 +219,16 @@ Part of the
 .Fa iov
 points outside the process's allocated address space.
 .El
+.Pp
+The
+.Fn pread
+call may also return the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The specified file offset is invalid.
+.It Bq Er ESPIPE
+The file descriptor is associated with a pipe, socket, or FIFO.
+.El
 .Sh SEE ALSO
 .Xr dup 2 ,
 .Xr fcntl 2 ,
@@ -224,8 +242,19 @@ The
 .Fn read
 function call is expected to conform to 
 .St -p1003.1-90 .
+The
+.Fn readv
+and
+.Fn pread
+functions are expected to conform to
+.St -xpg4.2 .
 .Sh HISTORY
 The
+.Fn pread
+function call
+appeared in
+.At V.4 .
+The
 .Fn readv
 function call
 appeared in
diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2
index f8d8063..240f970 100644
--- a/lib/libc/sys/write.2
+++ b/lib/libc/sys/write.2
@@ -36,7 +36,8 @@
 .Os BSD 4
 .Sh NAME
 .Nm write ,
-.Nm writev
+.Nm writev ,
+.Nm pwrite
 .Nd write output
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
@@ -46,6 +47,8 @@
 .Fn write "int d" "const void *buf" "size_t nbytes"
 .Ft ssize_t
 .Fn writev "int d" "const struct iovec *iov" "int iovcnt"
+.Ft ssize_t
+.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
 .Sh DESCRIPTION
 .Fn Write
 attempts to write
@@ -61,6 +64,9 @@ from the
 buffers specified by the members of the
 .Fa iov
 array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
+.Fn Pwrite
+performs the same function, but writes to the specified position in
+the file without modifying the file pointer.
 .Pp
 For 
 .Fn writev ,
@@ -168,9 +174,10 @@ is returned.  Otherwise a -1 is returned and the global variable
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
-.Fn Write
+.Fn Write ,
+.Fn writev ,
 and
-.Fn writev
+.Fn pwrite
 will fail and the file pointer will remain unchanged if:
 .Bl -tag -width Er
 .It Bq Er EBADF
@@ -229,6 +236,16 @@ values in the
 .Fa iov
 array overflowed a 32-bit integer.
 .El
+.Pp
+The
+.Fn pwrite
+call may also return the following errors:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The specified file offset is invalid.
+.It Bq Er ESPIPE
+The file descriptor is associated with a pipe, socket, or FIFO.
+.El
 .Sh SEE ALSO
 .Xr fcntl 2 ,
 .Xr lseek 2 ,
@@ -240,8 +257,19 @@ The
 .Fn write
 function call is expected to conform to 
 .St -p1003.1-90 .
+The
+.Fn writev
+and
+.Fn pwrite
+functions are expected to conform to
+.St -xpg4.2 .
 .Sh HISTORY
 The
+.Fn pwrite
+function call
+appeared in
+.At V.4 .
+The
 .Fn writev
 function call
 appeared in