usr/src/man/man9e/chpoll.9e

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH CHPOLL 9E "May 7, 2008"
   8 .SH NAME
   9 chpoll \- poll entry point for a non-STREAMS character driver
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/poll.h>
  15 #include <sys/ddi.h>
  16 #include <sys/sunddi.h>
  17
  18
  19
  20 \fBint prefix\fR\fBchpoll\fR(\fBdev_t\fR \fIdev\fR, \fBshort\fR \fIevents\fR, \fBint\fR \fIanyyet\fR,
  21      \fBshort *\fR\fIreventsp\fR, \fBstruct pollhead **\fR\fIphpp\fR);
  22 .fi
  23
  24 .SH INTERFACE LEVEL
  25 .sp
  26 .LP
  27 This entry point is optional. Architecture independent level 1 (DDI/DKI).
  28 .SH PARAMETERS
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIdev\fR\fR
  33 .ad
  34 .RS 12n
  35 The device number for the device to be polled.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIevents\fR\fR
  42 .ad
  43 .RS 12n
  44 The events that may occur. Valid events are:
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fBPOLLIN\fR\fR
  49 .ad
  50 .RS 14n
  51 Data other than high priority data may be read without blocking.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fBPOLLOUT\fR\fR
  58 .ad
  59 .RS 14n
  60 Normal data may be written without blocking.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fBPOLLPRI\fR\fR
  67 .ad
  68 .RS 14n
  69 High priority data may be received without blocking.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBPOLLHUP\fR\fR
  76 .ad
  77 .RS 14n
  78 A device hangup has occurred.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBPOLLERR\fR\fR
  85 .ad
  86 .RS 14n
  87 An error has occurred on the device.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBPOLLRDNORM\fR\fR
  94 .ad
  95 .RS 14n
  96 Normal data (priority band = 0) may be read without blocking.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBPOLLRDBAND\fR\fR
 103 .ad
 104 .RS 14n
 105 Data from a non-zero priority band may be read without blocking
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBPOLLWRNORM\fR\fR
 112 .ad
 113 .RS 14n
 114 The same as \fBPOLLOUT\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBPOLLWRBAND\fR\fR
 121 .ad
 122 .RS 14n
 123 Priority data (priority band > 0) may be written.
 124 .RE
 125
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fIanyyet\fR\fR
 132 .ad
 133 .RS 12n
 134 A flag that is non-zero if any other file descriptors in the \fBpollfd\fR array
 135 have events pending. The \fBpoll\fR(2) system call takes a pointer to an array
 136 of \fBpollfd\fR structures as one of its arguments. See the \fBpoll\fR(2)
 137 reference page for more details.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fIreventsp\fR\fR
 144 .ad
 145 .RS 12n
 146 A pointer to a bitmask of the returned events satisfied.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fIphpp\fR\fR
 153 .ad
 154 .RS 12n
 155 A pointer to a pointer to a \fBpollhead\fR structure.
 156 .RE
 157
 158 .SH DESCRIPTION
 159 .sp
 160 .LP
 161 The \fBchpoll()\fR entry point routine is used by non-STREAMS character device
 162 drivers that wish to support polling. The driver must implement the polling
 163 discipline itself. The following rules must be followed when implementing the
 164 polling discipline:
 165 .RS +4
 166 .TP
 167 1.
 168 Implement the following algorithm when the \fBchpoll()\fR entry point is
 169 called:
 170 .sp
 171 .in +2
 172 .nf
 173 if (events_are_satisfied_now) {
 174       *reventsp = satisfied_events & events;
 175 } else {
 176       *reventsp = 0;
 177       if (!anyyet)
 178             *phpp = &my_local_pollhead_structure;
 179 }
 180 return (0);
 181 .fi
 182 .in -2
 183
 184 .RE
 185 .RS +4
 186 .TP
 187 2.
 188 Allocate an instance of the \fBpollhead\fR structure. This instance may be
 189 tied to the per-minor data structure defined by the driver. The \fBpollhead\fR
 190 structure should be treated as a "black box" by the driver. Initialize the
 191 \fBpollhead\fR structure by filling it with zeroes. The size of this structure
 192 is guaranteed to remain the same across releases.
 193 .RE
 194 .RS +4
 195 .TP
 196 3.
 197 Call the \fBpollwakeup()\fR function with \fBevents\fR listed above whenever
 198 pollable \fBevents\fR which the driver should monitor occur. This function can
 199 be called with multiple events at one time. The \fBpollwakup()\fR can be called
 200 regardless of whether or not the \fBchpoll()\fR entry is called; it should be
 201 called every time the driver detects the pollable event. The driver must not
 202 hold any mutex across the call to \fBpollwakeup\fR(9F) that is acquired in its
 203 \fBchpoll()\fR entry point, or a deadlock may result.
 204 .RE
 205 .SH RETURN VALUES
 206 .sp
 207 .LP
 208 \fBchpoll()\fR should return \fB0\fR for success, or the appropriate error
 209 number.
 210 .SH SEE ALSO
 211 .sp
 212 .LP
 213 \fBpoll\fR(2), \fBnochpoll\fR(9F), \fBpollwakeup\fR(9F)
 214 .sp
 215 .LP
 216 \fIWriting Device Drivers\fR