.\" $OpenBSD: poll.2,v 1.11 2001/08/11 08:13:18 fgsch Exp $
|
.\" $OpenBSD: poll.2,v 1.11 2001/08/11 08:13:18 fgsch Exp $
|
.\"
|
.\"
|
.\" Copyright (c) 1994 Jason R. Thorpe
|
.\" Copyright (c) 1994 Jason R. Thorpe
|
.\" All rights reserved.
|
.\" All rights reserved.
|
.\"
|
.\"
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
.\" are met:
|
.\" are met:
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" documentation and/or other materials provided with the distribution.
|
.\" documentation and/or other materials provided with the distribution.
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" must display the following acknowledgement:
|
.\" must display the following acknowledgement:
|
.\" This product includes software developed by Jason R. Thorpe.
|
.\" This product includes software developed by Jason R. Thorpe.
|
.\" 4. The name of the author may not be used to endorse or promote products
|
.\" 4. The name of the author may not be used to endorse or promote products
|
.\" derived from this software without specific prior written permission.
|
.\" derived from this software without specific prior written permission.
|
.\"
|
.\"
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\"
|
.\"
|
.Dd December 13, 1994
|
.Dd December 13, 1994
|
.Dt POLL 2
|
.Dt POLL 2
|
.Os
|
.Os
|
.Sh NAME
|
.Sh NAME
|
.Nm poll
|
.Nm poll
|
.Nd synchronous I/O multiplexing
|
.Nd synchronous I/O multiplexing
|
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
.Fd #include
|
.Fd #include
|
.Ft int
|
.Ft int
|
.Fn poll "struct pollfd *fds" "int nfds" "int timeout"
|
.Fn poll "struct pollfd *fds" "int nfds" "int timeout"
|
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
.Fn poll
|
.Fn poll
|
provides a mechanism for reporting I/O conditions across a set of file
|
provides a mechanism for reporting I/O conditions across a set of file
|
descriptors.
|
descriptors.
|
.Pp
|
.Pp
|
The arguments are as follows:
|
The arguments are as follows:
|
.Bl -tag -width timeout
|
.Bl -tag -width timeout
|
.It Pa fds
|
.It Pa fds
|
Points to an array of
|
Points to an array of
|
.Nm pollfd
|
.Nm pollfd
|
structures, which are defined as:
|
structures, which are defined as:
|
.Bd -literal -offset indent
|
.Bd -literal -offset indent
|
struct pollfd {
|
struct pollfd {
|
int fd;
|
int fd;
|
short events;
|
short events;
|
short revents;
|
short revents;
|
};
|
};
|
.Ed
|
.Ed
|
.Pp
|
.Pp
|
The
|
The
|
.Pa fd
|
.Pa fd
|
member is an open file descriptor.
|
member is an open file descriptor.
|
The
|
The
|
.Pa events
|
.Pa events
|
and
|
and
|
.Pa revents
|
.Pa revents
|
members are bitmasks of conditions to monitor and conditions found,
|
members are bitmasks of conditions to monitor and conditions found,
|
respectively.
|
respectively.
|
.It Pa nfds
|
.It Pa nfds
|
The number of
|
The number of
|
.Nm pollfd
|
.Nm pollfd
|
structures in the array.
|
structures in the array.
|
.It Pa timeout
|
.It Pa timeout
|
Maximum interval to wait for the poll to complete, in milliseconds.
|
Maximum interval to wait for the poll to complete, in milliseconds.
|
If this value is 0, then
|
If this value is 0, then
|
.Fn poll
|
.Fn poll
|
will return immediately.
|
will return immediately.
|
If this value is INFTIM (-1),
|
If this value is INFTIM (-1),
|
.Fn poll
|
.Fn poll
|
will block indefinitely until a condition is found.
|
will block indefinitely until a condition is found.
|
.El
|
.El
|
.Pp
|
.Pp
|
The calling process sets the
|
The calling process sets the
|
.Pa events
|
.Pa events
|
bitmask and
|
bitmask and
|
.Fn poll
|
.Fn poll
|
sets the
|
sets the
|
.Pa revents
|
.Pa revents
|
bitmask.
|
bitmask.
|
Each call to
|
Each call to
|
.Fn poll
|
.Fn poll
|
resets the
|
resets the
|
.Pa revents
|
.Pa revents
|
bitmask for accuracy.
|
bitmask for accuracy.
|
The condition flags in the bitmasks are defined as:
|
The condition flags in the bitmasks are defined as:
|
.Bl -tag -width POLLRDNORM
|
.Bl -tag -width POLLRDNORM
|
.It Nm POLLIN
|
.It Nm POLLIN
|
Data is available on the file descriptor for reading.
|
Data is available on the file descriptor for reading.
|
.It Nm POLLNORM
|
.It Nm POLLNORM
|
Same as
|
Same as
|
.Nm POLLIN .
|
.Nm POLLIN .
|
.It Nm POLLPRI
|
.It Nm POLLPRI
|
Same as
|
Same as
|
.Nm POLLIN .
|
.Nm POLLIN .
|
.It Nm POLLOUT
|
.It Nm POLLOUT
|
Data can be written to the file descriptor without blocking.
|
Data can be written to the file descriptor without blocking.
|
.It Nm POLLERR
|
.It Nm POLLERR
|
This flag is not used in this implementation and is provided only for source
|
This flag is not used in this implementation and is provided only for source
|
code compatibility.
|
code compatibility.
|
.It Nm POLLHUP
|
.It Nm POLLHUP
|
The file descriptor was valid before the polling process and invalid after.
|
The file descriptor was valid before the polling process and invalid after.
|
Presumably, this means that the file descriptor was closed sometime during
|
Presumably, this means that the file descriptor was closed sometime during
|
the poll.
|
the poll.
|
.It Nm POLLNVAL
|
.It Nm POLLNVAL
|
The corresponding file descriptor is invalid.
|
The corresponding file descriptor is invalid.
|
.It Nm POLLRDNORM
|
.It Nm POLLRDNORM
|
Same as
|
Same as
|
.Nm POLLIN .
|
.Nm POLLIN .
|
.It Nm POLLRDBAND
|
.It Nm POLLRDBAND
|
Same as
|
Same as
|
.Nm POLLIN .
|
.Nm POLLIN .
|
.It Nm POLLWRNORM
|
.It Nm POLLWRNORM
|
Same as
|
Same as
|
.Nm POLLOUT .
|
.Nm POLLOUT .
|
.It Nm POLLWRBAND
|
.It Nm POLLWRBAND
|
Same as
|
Same as
|
.Nm POLLOUT .
|
.Nm POLLOUT .
|
.It Nm POLLMSG
|
.It Nm POLLMSG
|
This flag is not used in this implementation and is provided only for source
|
This flag is not used in this implementation and is provided only for source
|
code compatibility.
|
code compatibility.
|
.El
|
.El
|
.Pp
|
.Pp
|
All flags except
|
All flags except
|
.Nm POLLIN ,
|
.Nm POLLIN ,
|
.Nm POLLOUT ,
|
.Nm POLLOUT ,
|
and their synonyms are for use only in the
|
and their synonyms are for use only in the
|
.Pa revents
|
.Pa revents
|
member of the
|
member of the
|
.Nm pollfd
|
.Nm pollfd
|
structure.
|
structure.
|
An attempt to set any of these flags in the
|
An attempt to set any of these flags in the
|
.Pa events
|
.Pa events
|
member will generate an error condition.
|
member will generate an error condition.
|
.Pp
|
.Pp
|
In addition to I/O multiplexing,
|
In addition to I/O multiplexing,
|
.Fn poll
|
.Fn poll
|
can be used to generate simple timeouts.
|
can be used to generate simple timeouts.
|
This functionality may be achieved by passing a null pointer for
|
This functionality may be achieved by passing a null pointer for
|
.Pa fds .
|
.Pa fds .
|
.Sh WARNINGS
|
.Sh WARNINGS
|
The
|
The
|
.Nm POLLHUP
|
.Nm POLLHUP
|
flag is only a close approximation and may not always be accurate.
|
flag is only a close approximation and may not always be accurate.
|
.Sh RETURN VALUES
|
.Sh RETURN VALUES
|
Upon error,
|
Upon error,
|
.Fn poll
|
.Fn poll
|
returns a \-1 and sets the global variable
|
returns a \-1 and sets the global variable
|
.Va errno
|
.Va errno
|
to indicate the error.
|
to indicate the error.
|
If the timeout interval was reached before any events occurred,
|
If the timeout interval was reached before any events occurred,
|
a 0 is returned.
|
a 0 is returned.
|
Otherwise,
|
Otherwise,
|
.Fn poll
|
.Fn poll
|
returns the number of file descriptors for which
|
returns the number of file descriptors for which
|
.Pa revents
|
.Pa revents
|
is non-zero.
|
is non-zero.
|
.Sh ERRORS
|
.Sh ERRORS
|
.Fn poll
|
.Fn poll
|
will fail if:
|
will fail if:
|
.Bl -tag -width "EINVAL "
|
.Bl -tag -width "EINVAL "
|
.It Bq Er EINVAL
|
.It Bq Er EINVAL
|
.Pa nfds
|
.Pa nfds
|
was either a negative number or greater than the number of available
|
was either a negative number or greater than the number of available
|
file descriptors.
|
file descriptors.
|
.It Bq Er EINVAL
|
.It Bq Er EINVAL
|
An invalid flags was set in the
|
An invalid flags was set in the
|
.Pa events
|
.Pa events
|
member of the
|
member of the
|
.Nm pollfd
|
.Nm pollfd
|
structure.
|
structure.
|
.It Bq Er EINVAL
|
.It Bq Er EINVAL
|
The timeout passed to
|
The timeout passed to
|
.Fn poll
|
.Fn poll
|
was too large.
|
was too large.
|
.It Bq Er EAGAIN
|
.It Bq Er EAGAIN
|
Resource allocation failed inside of
|
Resource allocation failed inside of
|
.Fn poll .
|
.Fn poll .
|
Subsequent calls to
|
Subsequent calls to
|
.Fn poll
|
.Fn poll
|
may succeed.
|
may succeed.
|
.It Bq Er EINTR
|
.It Bq Er EINTR
|
.Fn poll
|
.Fn poll
|
caught a signal during the polling process.
|
caught a signal during the polling process.
|
.El
|
.El
|
.Sh SEE ALSO
|
.Sh SEE ALSO
|
.Xr poll 2 ,
|
.Xr poll 2 ,
|
.Xr select 2 ,
|
.Xr select 2 ,
|
.Xr sysconf 3
|
.Xr sysconf 3
|
.Sh HISTORY
|
.Sh HISTORY
|
A
|
A
|
.Fn poll
|
.Fn poll
|
system call appeared in
|
system call appeared in
|
.At V .
|
.At V .
|
|
|