.\" fwait.2 .\" .\" Created: 27 June, 1994 by Philip Homburg .TH fwait 2 .SH NAME fwait \- wait for asynchronous I/O operations to complete .SH SYNOPSIS .nf .ft B #define _MINIX_SOURCE 1 #include #include int fwait(struct fwait *\fIfwp\fP) .ft R .fi .SH DESCRIPTION .B Fwait allows a program to wait for the completion of asynchronous I/O operations, and to get the results of completed operations. Asynchronous I/O operations are started by marking a file descriptor asynchronous with \fBfcntl\fR(2). After that \fBread\fR(2), \fBwrite\fR(2), and \fBioctl\fR(2) system calls are asynchronous. .PP .B Fwait takes one argument, a pointer to an .I fwait structure, which is defined in .I as follows: .PP .nf typedef struct fwait { int fw_flags; unsigned char (*fw_bits)[4]; int fw_maxfd; int fw_result; int fw_errno; int fw_fd; int fw_operation; } fwait_t; .fi .PP The first three fields (\fIfw_flags\fR, \fIfw_bits\fR, and \fIfw_maxfd\fR) have to be filled-in by the user. Results are returned in the last four fields (\fIfw_result\fR, \fIfw_errno\fR, \fIfw_fd\fR, and \fIfw_operation\fR) and in the \fIfw_flags\fR field. The following flags are defined for the \fIfw_flags\fR field: .PP .nf #define FWF_NONBLOCK 1 #define FWF_MORE 2 .fi .PP If the \fIFWF_NONBLOCK\fR flag is present, \fBfwait\fR does not block but returns immediately. In this case, if no completed I/O operations are available, \fBfwait\fR sets \fBerrno\fR(2) to \fIEAGAIN\fR. If \fIFWF_NONBLOCK\fR is not set, \fBfwait\fR blocks until a result can be reported, or until the process gets a signal. .PP The \fIFWF_MORE\fR flag is ignored by \fBfwait\fR, but instead, \fBfwait\fR sets this flag when more results are available, i.e. the next call to \fBfwait\fR will not block. The user program can use this flag to retrieve all available results in a loop. .PP The second field, \fIfw_bits\fR contains a pointer to a 2-dimensional bit-array. Bits set in the array specify about which file descriptor/operation combinations \fBfwait\fR should report completion results. The easiest way to create such an array is with the \fIasio_fd_set_t\fR datatype and the macros \fIASIO_FD_SET\fR, \fIASIO_FD_CLR\fR, \fIASIO_FD_ISSET\fR, and \fIASIO_FD_ZERO\fR. \fIasio_fd_set_t\fR is defined as follows: .PP .nf #define ASIO_FD_SETSIZE 64 typedef unsigned char asio_fd_mask; typedef struct asio_fd_set { asio_fd_mask afds_bits[howmany(ASIO_FD_SETSIZE, ASIO_NFDBITS)][4]; } asio_fd_set_t; .fi .PP \fIASIO_FD_ZERO\fR(p), with \fIp\fR a pointer to a \fIasio_fd_set\fR structure, clears all bits. \fIASIO_FD_SET\fR(n,o,p) and \fIASIO_FD_CLR\fR(n,o,p) set respectively reset bits in the \fIasio_fd_set\fR pointed to by \fIp\fR. \fIN\fR specifies the file descriptor and \fIo\fR takes one of the following values depending on the operation: .PP .nf #define ASIO_READ 0 #define ASIO_WRITE 1 #define ASIO_IOCTL 2 .fi .PP There is also \fIASIO_FD_ISSET\fR(n,o,p) to test whether a certain bit is set. .PP Using an \fIasio_fd_set\fR, the \fIfw_bits\fR field is filled in as follows: .PP .nf fw.fw_bits= afds.afds_bits; .fi .PP Finally, \fIfw_maxfd\fR is to be filled-in with the size of the bit-array. Normally this is the value of the macro \fIASIO_FD_SETSIZE\fR. .PP \fBFwait\fR will examine the bits set in the bit-array to see whether .IP - The file descriptor refers to an open file. If not \fBerrno\fR is set to \fIEBADF\fR. .IP - The specified operation is in progress, or has completed without reporting it's status. If not \fBerrno\fR is set to \fIEINVAL\fR. .IP - For the first completed operation, \fBfwait\fR fills in the fields \fIfw_result\fR, \fIfw_errno\fR, \fIfw_fd\fR, and \fIfw_operation\fR with resp. the return value, the error code, the file descriptor number and the operation code. .IP - If a second completed operation is found, \fBfwait\fR sets the \fIFWF_MORE\fR more flag, \fIand updates the bit-array\fR to reflect it's internal state. The nonblocking behavior of the \fIFWF_MORE\fR is only guaranteed if the bit-array is left unmodified. .SH "RETURN VALUES" \fBFwait\fR returns 0 upon success and -1 upon failure. .SH ERRORS .IP EFAULT Either the pointer to the fwait structure or the pointer to the bit-array is invalid. .IP EINVAL \fIFw_maxfd\fR is invalid, or a bit is set for a file descriptor/operation combination without a pending reult or a call in progress. .IP EAGAIN \fIFWF_NONBLOCK\fR was set but there was no result to report. .IP EINTR \fBFwait\fR is interrupted by a signal. .SH "SEE ALSO" .BR asynchio (3), .BR errno (2), .BR fcntl (2), .BR ioctl (2), .BR read (2), .BR write (2). .SH AUTHOR Philip Homburg (philip@cs.vu.nl) .\" .\" $PchId: fwait.2,v 1.3 1995/11/27 19:38:40 philip Exp $