- Remove unnecessary macro argument quoting.
- Variables, pathnames in italics.
- Keywords in bold.
- Man page references in bold, followed by the man page number.
- Fix TP/TQ macro usage.
Signed-off-by: Guillem Jover <guillem@hadrons.org>
Gbp-Pq: Name 0012-man-Fix-markup.patch
.sp
.fi
.SH DESCRIPTION
-The libaio library defines a new set of I/O operations which can
+The
+.B libaio
+library defines a new set of I/O operations which can
significantly reduce the time an application spends waiting at I/O. The
new functions allow a program to initiate one or more I/O operations and
then immediately resume normal work while the I/O operations are
executed in parallel.
These functions are part of the library with realtime functions named
-.IR libaio .
+.BR libaio .
They are not actually part of the
-.IR "libc"
+.B libc
binary.
The implementation of these functions can be done using support in the
kernel.
All IO operations operate on files which were opened previously. There
might be arbitrarily many operations running for one file. The
asynchronous I/O operations are controlled using a data structure named
-.IR "struct iocb"
+.B struct iocb
It is defined in
-.IR "libaio.h"
+.I libaio.h
as follows.
.nf
.fi
.TP
-.IR "int aio_fildes"
+.BI int " aio_fildes"
This element specifies the file descriptor to be used for the
operation. It must be a legal descriptor, otherwise the operation will
fail.
The device on which the file is opened must allow the seek operation.
I.e., it is not possible to use any of the IO operations on devices
like terminals where an
-.IR "lseek"
+.BR lseek (2)
call would lead to an error.
.TP
-.IR "long u.c.offset"
+.BI long " u.c.offset"
This element specifies the offset in the file at which the operation (input
or output) is performed. Since the operations are carried out in arbitrary
order and more than one operation for one file descriptor can be
started, one cannot expect a current read/write position of the file
descriptor.
.TP
-.IR "void *buf"
+.BI "void *" buf
This is a pointer to the buffer with the data to be written or the place
where the read data is stored.
.TP
-.IR "long u.c.nbytes"
+.BI long " u.c.nbytes"
This element specifies the length of the buffer pointed to by
.IR io_buf .
.TP
-.IR "int aio_reqprio"
+.BI int " aio_reqprio"
Is not currently used.
.TP
.B "IO_CMD_PREAD"
Start a read operation. Read from the file at position
-.IR "u.c.offset"
+.I u.c.offset
and store the next
-.IR "u.c.nbytes"
+.I u.c.nbytes
bytes in the
buffer pointed to by
.IR buf .
.TP
.B "IO_CMD_PWRITE"
Start a write operation. Write
-.IR "u.c.nbytes"
+.I u.c.nbytes
bytes starting at
-.IR "buf"
+.I buf
into the file starting at position
.IR u.c.offset .
.TP
.B "IO_CMD_NOP"
Do nothing for this control block. This value is useful sometimes when
an array of
-.IR "struct iocb"
+.B struct iocb
values contains holes, i.e., some of the
values must not be handled although the whole array is presented to the
-.IR "io_submit"
+.BR io_submit (3)
function.
.TP
.B "IO_CMD_FSYNC"
-.TP
+.TQ
.B "IO_CMD_POLL"
This is experimental.
.SH EXAMPLE
.B #include <libaio.h>
.sp
.br
-.BI "int io_cancel(io_context_t ctx, struct iocb *iocb)"
+.BI "int io_cancel(io_context_t " ctx ", struct iocb *" iocb ");"
.br
.sp
struct iocb {
};
.fi
.SH DESCRIPTION
-Attempts to cancel an iocb previously passed to io_submit. If
-the operation is successfully cancelled, the resulting event is
+Attempts to cancel an
+.I iocb
+previously passed to
+.BR io_submit (3).
+If the operation is successfully cancelled, the resulting event is
copied into the memory pointed to by result without being placed
into the completion queue.
.PP
writes data in files in a situation where new incoming data would have
to be written in a file which will be updated by an enqueued request.
.SH "RETURN VALUES"
-0 is returned on success, otherwise returns errno.
+\fI0\fP is returned on success, otherwise returns \fIerrno\fP.
.SH ERRORS
.TP
.B EFAULT
If any of the data structures pointed to are invalid.
.TP
.B EINVAL
-If aio_context specified by ctx_id is
-invalid.
+If
+.I aio_context
+specified by
+.I ctx_id
+is invalid.
.TP
.B EAGAIN
-If the iocb specified was not
-cancelled.
+If the
+.I iocb
+specified was not cancelled.
.TP
.B ENOSYS
If not implemented.
.B #include <libaio.h>
.sp
.br
-.BI "int io_fsync(io_context_t ctx, struct iocb *iocb, io_callback_t cb, int fd)"
+.BI "int io_fsync(io_context_t " ctx ", struct iocb *" iocb ", io_callback_t " cb ", int " fd ");"
.sp
struct iocb {
void *data;
time of the function call operating on the file descriptor
.IR "iocb->io_fildes"
into the synchronized I/O completion state. The
-.IR "io_fsync"
+.BR io_fsync ()
function returns
immediately but the notification through the method described in
.IR "io_callback"
means that requests for this very same file descriptor which are queued
after the synchronization request are not affected.
.SH "RETURN VALUES"
-Returns 0, otherwise returns errno.
+Returns
+.BR 0 ,
+otherwise returns
+.IR errno .
.SH ERRORS
.TP
.B EFAULT
unsigned PADDED(res2, __pad4);
};
.sp
-.BI "int io_getevents(io_context_t " ctx ", long " nr ", struct io_event *" events "[], struct timespec *" timeout ");"
-.BI "int io_pgetevents(io_context_t " ctx ", long " nr ", struct io_event *" events "[], struct timespec *" timeout ", sigset_t *" sigmask ");"
+.BI "int io_getevents(io_context_t " ctx ", long " nr ", struct io_event *" events "[], struct timespec *" timeout ");"
+.BI "int io_pgetevents(io_context_t " ctx ", long " nr ", struct io_event *" events "[], struct timespec *" timeout ", sigset_t *" sigmask ");"
.fi
.SH DESCRIPTION
-Attempts to read up to nr events from
-the completion queue for the aio_context specified by ctx.
+Attempts to read up to
+.I nr
+events from the completion queue for the aio_context specified by
+.IR ctx .
.SH "RETURN VALUES"
May return
-0 if no events are available and the timeout specified
-by when has elapsed, where when == NULL specifies an infinite
+.B 0
+if no events are available and the timeout specified
+by when has elapsed, where
+.I when
+== NULL specifies an infinite
timeout. Note that the timeout pointed to by when is relative and
-will be updated if not NULL and the operation blocks. Will fail
-with ENOSYS if not implemented.
+will be updated if not NULL and the operation blocks. Will fail with
+.B ENOSYS
+if not implemented.
.SS io_pgetevents()
The relationship between
.BR io_getevents ()
.SH ERRORS
.TP
.B EINVAL
-If ctx_id is invalid, if min_nr is out of range,
-if nr is out of range, if when is out of range.
+If
+.I ctx_id
+is invalid, if
+.I min_nr
+is out of range, if
+.I nr
+is out of range, if
+.I when
+is out of range.
.TP
.B EFAULT
If any of the memory specified to is invalid.
.B #include <libaio.h>
.br
.sp
-.BI "static inline void io_prep_fsync(struct iocb *iocb, int fd)"
+.BI "static inline void io_prep_fsync(struct iocb *" iocb ", int " fd ");"
.sp
struct iocb {
void *data;
.sp
.fi
.SH DESCRIPTION
-This is an inline convenience function for setting up an iocbv for a FSYNC request.
-.br
+This is an inline convenience function for setting up an
+.I iocbv
+for a
+.B FSYNC
+request.
+.
+.PP
The file for which
-.TP
+.nf
.IR "iocb->aio_fildes = fd"
+.fi
is a descriptor is set up with
the command
-.TP
-.IR "iocb->aio_lio_opcode = IO_CMD_FSYNC:
+.nf
+.IR "iocb->aio_lio_opcode = IO_CMD_FSYNC"
+.fi
.
.PP
-The io_prep_fsync() function shall set up an IO_CMD_FSYNC operation
-to asynchronously force all I/O
+The
+.BR io_prep_fsync ()
+function shall set up an
+.B IO_CMD_FSYNC
+operation to asynchronously force all I/O
operations associated with the file indicated by the file
-descriptor aio_fildes member of the iocb structure referenced by
+descriptor
+.I aio_fildes
+member of the
+.I iocb
+structure referenced by
the iocb argument and queued at the time of the call to
-io_submit() to the synchronized I/O completion state. The function
+.BR io_submit ()
+to the synchronized I/O completion state. The function
call shall return when the synchronization request has been
initiated or queued to the file or device (even when the data
cannot be synchronized immediately).
All currently queued I/O operations shall be completed as if by a call
-to fsync(); that is, as defined for synchronized I/O file
+to
+.BR fsync (2);
+that is, as defined for synchronized I/O file
integrity completion. If the
-operation queued by io_prep_fsync() fails, then, as for fsync(),
+operation queued by
+.BR io_prep_fsync ()
+fails, then, as for
+.BR fsync (2),
outstanding I/O operations are not guaranteed to have
been completed.
-If io_prep_fsync() succeeds, then it is only the I/O that was queued
-at the time of the call to io_submit() that is guaranteed to be
+If
+.BR io_prep_fsync ()
+succeeds, then it is only the I/O that was queued
+at the time of the call to
+.BR io_submit (3)
+that is guaranteed to be
forced to the relevant completion state. The completion of
subsequent I/O on the file descriptor is not guaranteed to be
completed in a synchronized fashion.
.PP
This function returns immediately. To schedule the operation, the
function
-.IR io_submit
+.BR io_submit (3)
must be called.
.PP
-Simultaneous asynchronous operations using the same iocb produce
-undefined results.
+Simultaneous asynchronous operations using the same
+.I iocb
+produce undefined results.
.SH "RETURN VALUES"
None.
.SH ERRORS
.B #include <libaio.h>
.br
.sp
-.BI "inline void io_prep_pread(struct iocb *iocb, int fd, void *buf, size_t count, long long offset)
+.BI "inline void io_prep_pread(struct iocb *" iocb ", int " fd ", void *" buf ", size_t " count ", long long " offset ");"
.
.sp
struct iocb {
};
.fi
.SH DESCRIPTION
-.IR io_prep_pread
+.BR io_prep_pread ()
is an inline convenience function designed to facilitate the initialization of
the iocb for an asynchronous read operation.
The first
-.TP
-.IR "iocb->u.c.nbytes = count"
+.I iocb->u.c.nbytes = count
bytes of the file for which
-.TP
-.IR "iocb->aio_fildes = fd"
+.I iocb->aio_fildes = fd
is a descriptor are written to the buffer
starting at
-.TP
.IR "iocb->u.c.buf = buf" .
-.br
Reading starts at the absolute position
-.TP
-.IR "ioc->u.c.offset = offset"
+.I ioc->u.c.offset = offset
in the file.
.PP
This function returns immediately. To schedule the operation, the
function
-.IR io_submit
+.BR io_submit (3)
must be called.
.PP
-Simultaneous asynchronous operations using the same iocb produce
+Simultaneous asynchronous operations using the same \fIiocb\fP produce
undefined results.
.SH "RETURN VALUES"
None.
.B #include <libaio.h>
.br
.sp
-.BI "inline void io_prep_pwrite(struct iocb *iocb, int fd, void *buf, size_t count, long long offset)
-"
+.BI "inline void io_prep_pwrite(struct iocb *" iocb ", int " fd ", void *" buf ", size_t " count ", long long " offset ");"
+.
.sp
struct iocb {
void *data;
};
.fi
.SH DESCRIPTION
-io_prep_write is a convenience function for setting up parallel writes.
+.BR io_prep_write ()
+is a convenience function for setting up parallel writes.
The first
-.TP
.IR "iocb->u.c.nbytes = count"
bytes of the file for which
-.TP
.IR "iocb->aio_fildes = fd"
is a descriptor are written from the buffer
starting at
-.TP
.IR "iocb->u.c.buf = buf" .
-.br
Writing starts at the absolute position
-.TP
.IR "ioc->u.c.offset = offset"
in the file.
.PP
This function returns immediately. To schedule the operation, the
function
-.IR io_submit
+.BR io_submit (3)
must be called.
.PP
Simultaneous asynchronous operations using the same iocb produce
.B #include <libaio.h>
.br
.sp
-.BI "int io_queue_init(int maxevents, io_context_t *ctx );"
+.BI "int io_queue_init(int " maxevents ", io_context_t *" ctx ");"
.sp
.fi
.SH DESCRIPTION
-.B io_queue_init
-Attempts to create an aio context capable of receiving at least
-.IR maxevents
+.BR io_queue_init ()
+attempts to create an aio context capable of receiving at least
+.I maxevents
events.
-.IR ctx
+.I ctx
must point to an aio context that already exists and must be initialized
to
-.IR 0
+.B 0
before the call.
-If the operation is successful, *cxtp is filled with the resulting handle.
+If the operation is successful,
+.I *cxtp
+is filled with the resulting handle.
.SH "RETURN VALUES"
On success,
-.B io_queue_init
-returns 0. Otherwise, -error is return, where
-error is one of the Exxx values defined in the Errors section.
+.BR io_queue_init ()
+returns
+.BR 0 .
+Otherwise, -error is return, where
+error is one of the Exxx values defined in the
+.B ERRORS
+section.
.SH ERRORS
.TP
.B EFAULT
.TP
.B EINVAL
.I maxevents
-is <= 0 or
+is <=
+.B 0
+or
.IR ctx
is an invalid memory location.
.TP
.TP
.B EAGAIN
.IR "maxevents > max_aio_reqs"
-where max_aio_reqs is a tunable value.
+where
+.I max_aio_reqs
+is a tunable value.
.SH "SEE ALSO"
.BR io (3),
.BR io_cancel (3),
.B #include <libaio.h>
.br
.sp
-.BI "int io_queue_release(io_context_t ctx)"
+.BI "int io_queue_release(io_context_t " ctx ");"
.sp
.SH DESCRIPTION
.B io_queue_release
.
.SH "RETURN VALUES"
On success,
-.B io_queue_release
-returns 0. Otherwise, -error is return, where
+.BR io_queue_release ()
+returns
+.BR 0 .
+Otherwise, -error is return, where
error is one of the Exxx values defined in the Errors section.
.SH ERRORS
.TP
.B EINVAL
.I ctx
-refers to an uninitialized aio context, the iocb pointed to by
+refers to an uninitialized aio context, the
+.I iocb
+pointed to by
.I iocbs
-contains an improperly initialized iocb,
+contains an improperly initialized
+.IR iocb .
.TP
.B ENOSYS
Not implemented.
.BR io_set_callback (3),
.BR io_submit (3),
.BR errno (3).
-
.B #include <libaio.h>
.br
.sp
-.BI "int io_queue_run(io_context_t ctx );"
+.BI "int io_queue_run(io_context_t " ctx ");"
.sp
.fi
.SH DESCRIPTION
-.B io_queue_run
-Attempts to read all the events from
-the completion queue for the aio_context specified by ctx_id.
+.BR io_queue_run ()
+attempts to read all the events from
+the completion queue for the aio_context specified by
+.IR ctx_id .
.SH "RETURN VALUES"
May return
-0 if no events are available.
-Will fail with -ENOSYS if not implemented.
+.B 0
+if no events are available.
+Will fail with -\fBENOSYS\fP if not implemented.
.SH ERRORS
.TP
.B EFAULT
.TP
.B EINVAL
.I ctx
-refers to an uninitialized aio context, the iocb pointed to by
+refers to an uninitialized aio context, the
+.I iocb
+pointed to by
.I iocbs
contains an improperly initialized iocb.
.TP
.B #include <libaio.h>
.br
.sp
-.BI "int io_queue_wait(io_context_t ctx, const struct timespec *timeout);"
+.BI "int io_queue_wait(io_context_t " ctx ", const struct timespec *" timeout ");"
.fi
.SH DESCRIPTION
-Attempts to read an event from
-the completion queue for the aio_context specified by ctx_id.
+.BR io_queue_wait ()
+attempts to read an event from
+the completion queue for the aio_context specified by
+.IR ctx_id .
.SH "RETURN VALUES"
May return
-0 if no events are available and the timeout specified
+.B 0
+if no events are available and the timeout specified
by when has elapsed, where when == NULL specifies an infinite
-timeout. Note that the timeout pointed to by when is relative and
+\fItimeout\fP. Note that the \fItimeout\fP pointed to by when is relative and
will be updated if not NULL and the operation blocks. Will fail
-with -ENOSYS if not implemented.
+with -\fBENOSYS\fP if not implemented.
.SH "RETURN VALUES"
On success,
-.B io_queue_wait
-returns 0. Otherwise, -error is return, where
+.BR io_queue_wait ()
+returns
+.BR 0 .
+Otherwise, -error is return, where
error is one of the Exxx values defined in the Errors section.
.SH ERRORS
.TP
.TP
.B EINVAL
.I ctx
-refers to an uninitialized aio context, the iocb pointed to by
+refers to an uninitialized aio context, the
+.I iocb
+pointed to by
.I iocbs
contains an improperly initialized iocb.
.TP
.B #include <libaio.h>
.br
.sp
-.BI "static inline void io_set_callback(struct iocb *iocb, io_callback_t cb)"
+.BI "static inline void io_set_callback(struct iocb *" iocb ", io_callback_t " cb ");"
.sp
struct iocb {
void *data;
.fi
.SH DESCRIPTION
The callback is not done if the caller uses raw events from
-io_getevents, only with the library helpers.
+.BR io_getevents (3),
+only with the library helpers.
.SH "RETURN VALUES"
None.
.SH ERRORS
};
.fi
.SH DESCRIPTION
-.B io_submit
+.BR io_submit ()
submits
.I nr
iocbs for processing for a given io context ctx.
The
-.IR "io_submit"
+.BR io_submit ()
function can be used to enqueue an arbitrary
number of read and write requests at one time. The requests can all be
meant for the same file, all for different files or every solution in
between.
-.IR "io_submit"
+.BR io_submit ()
gets the
-.IR "nr"
+.I nr
requests from the array pointed to
by
.IR "iocbs" .
.IR "iocbs"
is simply ignored. This
``operation'' is useful in situations where one has a fixed array of
-.IR "struct iocb"
+.B struct iocb
elements from which only a few need to be handled at
a time. Another situation is where the
-.IR "io_submit"
+.BR io_submit (3)
call was
canceled before all requests are processed and the remaining requests have to be reissued.
.IR "iocbs"
must have values suitable for the operation as described in
the documentation for
-.IR "io_prep_pread"
+.BR io_prep_pread (3)
and
-.IR "io_prep_pwrite"
+.BR io_prep_pwrite (3)
above.
The function returns immediately after
having enqueued all the requests.
On success,
-.B io_submit
+.BR io_submit ()
returns the number of iocbs submitted successfully. Otherwise, -error is return, where
error is one of the Exxx values defined in the Errors section.
.PP
contains an improperly initialized iocb,
.TP
.B EBADF
-The iocb contains a file descriptor that does not exist.
+The
+.I iocb
+contains a file descriptor that does not exist.
.TP
.B EINVAL
-The file specified in the iocb does not support the given io operation.
+The file specified in the
+.I iocb
+does not support the given io operation.
.SH "SEE ALSO"
.BR io (3),
.BR io_cancel (3),
projects / libaio.git / commitdiff