Subversion Repositories openrisc_me

.\"     $OpenBSD: poll.2,v 1.11 2001/08/11 08:13:18 fgsch Exp $

.\"

.\" Copyright (c) 1994 Jason R. Thorpe

.\" 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.

.\" 3. All advertising materials mentioning features or use of this software

.\"    must display the following acknowledgement:

.\"     This product includes software developed by Jason R. Thorpe.

.\" 4. The name of the author may not be used to endorse or promote products

.\"    derived from this software without specific prior written permission.

.\"

.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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

.\"

.Dd December 13, 1994

.Dt POLL 2

.Os

.Sh NAME

.Nm poll

.Nd synchronous I/O multiplexing

.Sh SYNOPSIS

.Fd #include 

.Ft int

.Fn poll "struct pollfd *fds" "int nfds" "int timeout"

.Sh DESCRIPTION

.Fn poll

provides a mechanism for reporting I/O conditions across a set of file

descriptors.

.Pp

The arguments are as follows:

.Bl -tag -width timeout

.It Pa fds

Points to an array of

.Nm pollfd

structures, which are defined as:

.Bd -literal -offset indent

struct pollfd {

        int fd;

        short events;

        short revents;

};

.Ed

.Pp

The

.Pa fd

member is an open file descriptor.

The

.Pa events

and

.Pa revents

members are bitmasks of conditions to monitor and conditions found,

respectively.

.It Pa nfds

The number of

.Nm pollfd

structures in the array.

.It Pa timeout

Maximum interval to wait for the poll to complete, in milliseconds.

If this value is 0, then

.Fn poll

will return immediately.

If this value is INFTIM (-1),

.Fn poll

will block indefinitely until a condition is found.

.El

.Pp

The calling process sets the

.Pa events

bitmask and

.Fn poll

sets the

.Pa revents

bitmask.

Each call to

.Fn poll

resets the

.Pa revents

bitmask for accuracy.

The condition flags in the bitmasks are defined as:

.Bl -tag -width POLLRDNORM

.It Nm POLLIN

Data is available on the file descriptor for reading.

.It Nm POLLNORM

Same as

.Nm POLLIN .

.It Nm POLLPRI

Same as

.Nm POLLIN .

.It Nm POLLOUT

Data can be written to the file descriptor without blocking.

.It Nm POLLERR

This flag is not used in this implementation and is provided only for source

code compatibility.

.It Nm POLLHUP

The file descriptor was valid before the polling process and invalid after.

Presumably, this means that the file descriptor was closed sometime during

the poll.

.It Nm POLLNVAL

The corresponding file descriptor is invalid.

.It Nm POLLRDNORM

Same as

.Nm POLLIN .

.It Nm POLLRDBAND

Same as

.Nm POLLIN .

.It Nm POLLWRNORM

Same as

.Nm POLLOUT .

.It Nm POLLWRBAND

Same as

.Nm POLLOUT .

.It Nm POLLMSG

This flag is not used in this implementation and is provided only for source

code compatibility.

.El

.Pp

All flags except

.Nm POLLIN ,

.Nm POLLOUT ,

and their synonyms are for use only in the

.Pa revents

member of the

.Nm pollfd

structure.

An attempt to set any of these flags in the

.Pa events

member will generate an error condition.

.Pp

In addition to I/O multiplexing,

.Fn poll

can be used to generate simple timeouts.

This functionality may be achieved by passing a null pointer for

.Pa fds .

.Sh WARNINGS

The

.Nm POLLHUP

flag is only a close approximation and may not always be accurate.

.Sh RETURN VALUES

Upon error,

.Fn poll

returns a \-1 and sets the global variable

.Va errno

to indicate the error.

If the timeout interval was reached before any events occurred,

a 0 is returned.

Otherwise,

.Fn poll

returns the number of file descriptors for which

.Pa revents

is non-zero.

.Sh ERRORS

.Fn poll

will fail if:

.Bl -tag -width "EINVAL   "

.It Bq Er EINVAL

.Pa nfds

was either a negative number or greater than the number of available

file descriptors.

.It Bq Er EINVAL

An invalid flags was set in the

.Pa events

member of the

.Nm pollfd

structure.

.It Bq Er EINVAL

The timeout passed to

.Fn poll

was too large.

.It Bq Er EAGAIN

Resource allocation failed inside of

.Fn poll .

Subsequent calls to

.Fn poll

may succeed.

.It Bq Er EINTR

.Fn poll

caught a signal during the polling process.

.El

.Sh SEE ALSO

.Xr poll 2 ,

.Xr select 2 ,

.Xr sysconf 3

.Sh HISTORY

A

.Fn poll

system call appeared in

.At V .