Add a manual page for the lio_listio() syscall. Still needs a bit

of polishing.

2 files changed, 177 insertions, 1 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 257ef7a..122d4ae 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -67,7 +67,8 @@ MAN+=	_exit.2 accept.2 access.2 acct.2 adjtime.2 \
 	getsockopt.2 gettimeofday.2 getuid.2 \
 	intro.2 ioctl.2 issetugid.2 jail.2 kenv.2 kill.2 \
 	kldfind.2 kldfirstmod.2 kldload.2 kldnext.2 kldstat.2 kldsym.2 \
-	kldunload.2 kqueue.2 kse.2 ktrace.2 link.2 listen.2 lseek.2 \
+	kldunload.2 kqueue.2 kse.2 ktrace.2 link.2 lio_listio.2 listen.2 \
+	lseek.2 \
 	madvise.2 mincore.2 minherit.2 mkdir.2 mkfifo.2 mknod.2 mlock.2 mmap.2 \
 	modfind.2 modnext.2 modstat.2 \
 	mount.2 mprotect.2 msync.2 munmap.2 nanosleep.2 \
diff --git a/lib/libc/sys/lio_listio.2 b/lib/libc/sys/lio_listio.2
new file mode 100644
index 0000000..fdb09f7
--- /dev/null
+++ b/lib/libc/sys/lio_listio.2
@@ -0,0 +1,175 @@
+.\" Copyright (c) 2003 Tim J. Robbins
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 12, 2003
+.Dt LIO_LISTIO 2
+.Os
+.Sh NAME
+.Nm lio_listio
+.Nd "list directed I/O (REALTIME)"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In aio.h
+.Ft int
+.Fo lio_listio
+.Fa "int mode"
+.Fa "struct aiocb * const [] list"
+.Fa "int nent"
+.Fa "struct sigevent *sig"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn lio_listio
+function initiates a list of I/O requests with a single function call.
+The
+.Fa list
+argument is an array of pointers to
+.Vt aiocb
+structures describing each operation to perform,
+with
+.Fa nent
+elements.
+.Dv NULL
+elements are ignored.
+.Pp
+The
+.Va aio_lio_opcode
+field of each
+.Vt aiocb
+specifies the operation to be performed.
+The following operations are supported:
+.Bl -tag -width ".Dv LIO_WRITE"
+.It Dv LIO_READ
+Read data as if by a call to
+.Xr aio_read 2 .
+.It Dv LIO_NOP
+No operation.
+.It Dv LIO_WRITE
+Write data as if by a call to
+.Xr aio_write 2 .
+.El
+.Pp
+If the
+.Fa mode
+argument is
+.Dv LIO_WAIT ,
+.Fn lio_listio
+does not return until all the requested operations have been completed.
+If
+.Fa mode
+is
+.Dv LIO_NOWAIT ,
+the requests are processed asynchronously and the signal specified by
+.Fa sig
+is sent when all operations have completed.
+If
+.Fa sig
+is
+.Dv NULL ,
+the calling process is not notified of I/O completion.
+.Pp
+The order in which the requests are carried out is not specified;
+in particular, there is no guarantee that they will be executed in
+the order 0, 1, ...,
+.Fa nent Ns \&-1 .
+.Sh RETURN VALUES
+If
+.Fa mode
+is
+.Dv LIO_WAIT ,
+the
+.Fn lio_listio
+function returns 0 if the operations completed successfully,
+otherwise -1.
+.Pp
+If
+.Fa mode
+is
+.Dv LIO_NOWAIT ,
+the
+.Fn lio_listio
+function 0 if the operations are successfully queued,
+otherwise -1.
+.Sh ERRORS
+The
+.Fn lio_listio
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EAGAIN
+There are not enough resources to enqueue the requests.
+.It Bq Er EAGAIN
+The request would cause the system-wide limit
+.Dv AIO_MAX
+to be exceeded.
+.It Bq Er EINVAL
+The
+.Fa mode
+argument is neither
+.Dv LIO_WAIT
+nor
+.Dv LIO_NOWAIT ,
+or
+.Fa nent
+is greater than
+.Dv AIO_LISTIO_MAX .
+.It Bq Er EINTR
+A signal interrupted the system call before it could be completed.
+.It Bq Er EIO
+One or more requests failed.
+.El
+.Pp
+In addition, the
+.Fn lio_listio
+function may fail for any of the reasons listed for
+.Xr aio_read 2
+and
+.Xr aio_write 2 .
+.Pp
+If
+.Fn lio_listio
+succeeds, or fails with an error code of
+.Er EAGAIN ,
+.Er EINTR ,
+or
+.Er EIO ,
+some of the requests may have been initiated.
+The caller should check the error status of each
+.Vt aiocb
+structure individually by calling
+.Xr aio_error 2 .
+.Sh SEE ALSO
+.Xr aio_error 2 ,
+.Xr aio_read 2 ,
+.Xr aio_write 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr aio 4
+.Sh STANDARDS
+The
+.Fn lio_listio
+function is expected to conform to
+.St -p1003.1-2001 .