pollbunch(3C) pollbunch(3C)
NAME
pollbunch, pollwhich - Ein-/Ausgabe multiplexen: leistungsfähigere
Version des Systemaufrufs poll(2)
SYNTAX
#include <stropts.h>
#include <poll.h>
int pollbunch(int cmd, struct nppollfd *fds);
int pollwhich(struct nppollfd *fds, sizet nfds, int timeout);
BESCHREIBUNG
pollbunch und pollwhich bieten dem Benutzer einen performanten Mecha-
nismus für das Multiplexen der Ein-/Ausgabe über einen Satz von Datei-
deskriptoren, die auf offene Dateien verweisen. Der Einsatz von
pollbunch/pollwhich gegenüber poll(2) empfiehlt sich für Anwendungen
mit einer großen Anzahl zu multiplexender Dateien bei gleichzeitig
relativ geringer Ereignisrate auf den einzelnen Dateien.
Der neue Mechanismus ermöglicht gegenüber poll(2) eine effizientere
Ereignis-Statusabfrage. Beim poll(2) muß jedesmal die gesamte Liste
der Dateideskriptoren als Argument übergeben werden, auch wenn sich
diese Liste meist nur selten und dann wenig verändert. Eine gleich
große Liste wird vom poll(2) als Ergebnis zurückgeliefert, auch wenn
darin eventuell nur wenige Dateideskriptoren mit "aktiven" Ereignissen
enthalten sind. Die Anwendung muß dann auch noch durch sequentielles
Nachsehen herausfinden, wo sich diese Dateideskriptoren in der Liste
befinden.
Die Aufteilung des poll(2)-Systemaufrufs in die zwei Systemaufrufe
pollbunch und pollwhich trennt den administrativen Teil von der
eigentlichen Ereignis-Statusabfrage ab und ermöglicht durch Ausnutzung
der Asynchronität der Ereignisse, den synchronen Zeitanteil während
der eigentlichen Ereignis-Statusabfrage auf diejenigen Dateideskripto-
ren zu beschränken, für die bereits ein Ereignis eingetroffen ist. Nur
diese Dateideskriptoren werden als Ergebnis zurückgeliefert. Programm-
technisch spart das Kopierzeit zwischen Kern und Anwendung ein und
vermeidet die langen, sequentiellen Programmabläufe über alle spezifi-
zierten Dateideskriptoren sowohl im Kern als auch in der Anwendung.
Daraus ergeben sich bessere Antwortzeiten in der Anwendung und eine
CPU-Entlastung.
Die Ergebnisliste der Ereignis-Statusabfrage liefert zusätzlich die
Ereignisse in der zeitlichen Reihenfolge ihres Eintreffens. Damit wird
eine Sonderbehandlung von Seiten der Anwendung, die sicherstellt, daß
keine Dateideskriptoren benachteiligt werden, überflüssig.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
pollbunch(3C) pollbunch(3C)
Zur Übergabe von Dateideskriptoren und Ereignissen dient in Anlehnung
an poll(2) die nppollfd-Struktur, die folgendes enthält:
int fd; /* Dateideskriptor */
short events; /* angeforderte bzw. gemeldete Ereignisse */
unsigned short userref; /* transparentes Benutzer-Argument */
fd spezifiziert einen geöffneten Dateideskriptor und das Ereignisfeld
events ist eine Bitmaske, die wie beim poll(2) durch ODER-Verknüpfung
beliebiger Kombinationen nachstehender Ereignisanzeiger aufgebaut wer-
den:
POLLIN
Daten von nicht höchster Priorität können nichtblockierend gele-
sen werden. Für STREAMS wird diese Option auch gesetzt, wenn die
Nachricht die Länge 0 hat.
POLLRDNORM
Gewöhnliche Daten (Priorität = 0) können nichtblockierend gelesen
werden. Für STREAMS wird diese Option auch gesetzt, wenn die
Nachricht die Länge 0 hat.
POLLRDBAND
Daten mit einer Priorität ungleich 0 können nichtblockierend
gelesen werden. Für STREAMS wird diese Option auch gesetzt, wenn
die Nachricht die Länge 0 hat.
POLLPRI
Daten mit höchster Priorität können nichtblockierend empfangen
werden. Für STREAMS wird diese Option auch gesetzt, wenn die
Nachricht die Länge 0 hat.
POLLOUT
Normale Daten können nichtblockierend geschrieben werden.
POLLWRNORM
Wie POLLOUT.
POLLWRBAND
Daten mit einer Prioritätsklasse ungleich 0 können geschrieben
werden. Dieses Ereignis untersucht nur Klassen, die mindestens
einmal geschrieben wurden.
POLLMSG
Eine MSIG- oder MPCSIG-Nachricht, die ein ASIGPOLL-Signal ent-
hält, hat den Anfang der Stream-Kopf-Warteschlange erreicht.
POLLERR
Eine Fehlermeldung liegt am Stream oder Gerät an. Dieser Schalter
ist nur in der events-Bitmaske bei pollwhich gültig; er wird
nicht im events-Feld bei pollbunch verwendet.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
pollbunch(3C) pollbunch(3C)
POLLHUP
Ein Hangup ist im Stream aufgetreten. Dieses Ereignis und POLLOUT
schließen sich gegenseitig aus; auf einen Stream kann niemals
geschrieben werden, wenn ein Hangup aufgetreten ist. Jedoch
schließen sich dieses Ereignis und POLLIN bzw. POLLPRI nicht
gegenseitig aus. Dieser Schalter ist nur in der events-Bitmaske
bei pollwhich gültig; er wird nicht im events-Feld bei pollbunch
verwendet.
POLLNVAL
Der angegebene fd-Wert gehört nicht zu einer offenen Datei. Die-
ser Schalter ist nur im events-Feld bei pollwhich gültig; er wird
nicht im events-Feld bei pollbunch verwendet.
Die jeweilige Belegung des events-Feldes ist für pollbunch und für
pollwhich unterschiedlich.
POLLBUNCH
pollbunch dient zum Aufbau und zur Manipulation einer kern-internen
Liste der interessierenden Dateideskriptoren und deren jeweiligen
Ereignisse. Mit einem pollbunch kann genau ein Dateideskriptor einge-
fügt, gelöscht oder dessen Ereignisse modifiziert werden. Die jewei-
lige Aktion wird durch cmd spezifiziert. fds ist ein Zeiger auf die
nppollfd-Struktur, die den Dateideskriptor und die Ereignisse ent-
hält:
Zulässige Werte für cmd sind:
NPBADD
Aufnahme des Dateideskriptors fd mit den Ereignissen events in
die Liste der interessierenden Dateideskriptoren. Damit werden
nachfolgend asynchron eintreffende Ereignisse für diesen Dateide-
skriptor vermerkt und von pollwhich angezeigt. Der Inhalt von
userref in der nppollfd-Struktur wird transparent übernommen und
intern zu diesem Dateideskriptor gespeichert. Die nppollfd-
Struktur ist nach Rückkehr von pollbunch unverändert.
NPBREM
Löschen des Dateideskriptors fd aus der Liste der interessieren-
den Dateideskriptoren. Damit werden nachfolgend keine eintreffen-
den Ereignisse mehr für diesen Dateideskriptor vermerkt und der
Dateideskriptor von pollwhich nicht mehr angezeigt. Die Felder
events und userref in der nppollfd-Struktur werden nicht ausge-
wertet. Die nppollfd-Struktur ist nach Rückkehr von pollbunch
unverändert.
NPBMODIFY
Ändern der Ereignisse für den bereits existierenden Dateideskrip-
tor fd. Der Wert events aus der nppollfd-Struktur überschreibt
den kern-intern vorhandenen Wert. Das Feld userref in der
nppollfd-Struktur wird nicht ausgewertet. Die nppollfd-Struktur
ist nach Rückkehr von pollbunch unverändert.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
pollbunch(3C) pollbunch(3C)
pollbunch ist erfolglos, wenn einer oder mehrere der nachstehenden
Punkte zutreffen:
EAGAIN Zuweisung einer internen Datenstrukturen war erfolglos,
Anforderung sollte jedoch erneut versucht werden.
EBADF fd in der nppollfd-Struktur ist kein gültiger Dateide-
skriptor.
EEXIST fd in der nppollfd-Struktur (NPBADD) spezifiziert einen
Dateideskriptor, der bereits in der Liste der interessie-
renden Dateideskriptoren enthalten ist.
EFAULT Ein Argument zeigt auf einen Speicherplatz außerhalb des
zugewiesenen Adreßraums.
EINVAL cmd enthält eine unzulässige Aktion.
events in der nppollfd-Struktur (NPBADD, NPBMODIFY)
enthält keine oder ungültige Ereignisse.
ENOENT fd in der nppollfd-Struktur (NPBREM, NPBMODIFY) spe-
zifiziert einen Dateideskriptor, der nicht in der Liste
der interessierenden Dateideskriptoren enthalten ist.
ERGEBNIS
Nach erfolgreicher Beendigung von pollbunch wird der Wert 0 zurückge-
geben. Ansonsten wird -1 zurückgegeben, und errno wird zur Anzeige des
Fehlers gesetzt.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
pollbunch(3C) pollbunch(3C)
POLLWHICH
pollwhich liefert die Dateideskriptoren, auf denen ein oder mehrere
Ereignisse eingetreten sind. Die Ergebnisse der pollwhich Anfrage wer-
den im events-Feld in der nppollfd-Struktur gespeichert. Zur Anzeige,
welche der angeforderten Ereignisse wahr sind, werden Bits in der
events-Bitmaske gesetzt.
Von pollwhich werden im Vektor fds maximal soviele nppollfd-
Strukturen angezeigt, wie durch nfds spezifiziert wurde. fds ist ein
Zeiger auf einen Adreßbereich der Größe von mindestens nfds
nppollfd-Strukturen.
Werden in fds mehrere Dateideskriptoren angezeigt, entspricht die Rei-
henfolge der nppollfd-Strukturen der zeitlichen Reihenfolge des Ein-
treffens der jeweiligen Ereignisse. Wurden für einen Dateideskriptor
mehrere Ereignisse spezifiziert und liegen mehrere Ereignisse parallel
vor, so wird die Position der entsprechenden nppollfd-Struktur inner-
halb von fds vom Zeitpunkt des Eintreffens des ersten Ereignisses für
diesen Dateideskriptor bestimmt.
Die Ereignisanzeiger POLLHUP, POLLERR und POLLNVAL werden stets im
events-Feld gesetzt, wenn die von ihnen angezeigten Bedingungen wahr
sind; dies geschieht auch, wenn sie nicht im events-Feld im pollbunch
vorhanden waren.
Von pollwhich werden nur die Dateideskriptoren berücksichtigt, die
vorher durch pollbunch spezifiziert wurden.
Das Feld userref enthält den Wert, der im dazugehöigen pollbunch spe-
zifiziert wurde.
Wenn keines der definierten Ereignisse bei einem der jeweils ausge-
wählten Dateideskriptoren auftritt, wartet pollwhich wenigstens
timeout Millisekunden auf das Auftreten eines Ereignisses bei einem
der gewählten Dateideskriptoren. Bei einem Rechner, bei dem die Genau-
igkeit auf Millisekunden nicht zur Verfügung steht, wird timeout auf
den nächsten zulässigen Wert aufgerundet, der in diesem System zur
Verfügung steht. Wenn der Wert von timeout 0 ist, kehrt pollwhich
sofort zurück. Ist der Wert von timeout gleich INFTIM (oder -1)
bewirkt pollwhich eine Blockierung, bis ein abgefragtes Ereignis auf-
tritt, oder bis der Aufruf unterbrochen wird. pollwhich wird von den
Schaltern ONDELAY und ONONBLOCK nicht betroffen.
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
pollbunch(3C) pollbunch(3C)
pollwhich ist erfolglos, wenn einer oder mehrere der nachstehenden
Punkte zutreffen:
EAGAIN Zuweisung einer internen Datenstrukturen war erfolglos,
Anforderung sollte jedoch erneut versucht werden.
EFAULT Ein Argument zeigt auf einen Speicherplatz außerhalb des
zugewiesenen Adreßraums.
EINTR Ein Signal wurde während des Systemaufrufs pollwhich abge-
fangen.
EINVAL Das Argument nfds ist kleiner als 0 oder größer als
OPENMAX.
ENOENT Es existiert keine Liste von interessierenden Dateideskrip-
toren. Es wurde wahrscheinlich kein pollbunch vorher durch-
geführt.
ERGEBNIS
Nach erfolgreicher Beendigung von pollwhich wird ein nicht negativer
Wert zurückgegeben. Ein positiver Wert zeigt die Gesamtanzahl der gül-
tigen (d. h. auswertbaren) nppollfd-Strukturen an. Alle weiteren
Strukturen (bis maximal nfds) enthalten dann undefinierte (bzw. die
alten) Werte.
0 zeigt an, daß die Zeit für den Aufruf abgelaufen ist und keine
Dateideskriptoren gewählt wurden.
Ist der Vorgang erfolglos, wird -1 zurückgegeben, und errno wird zur
Anzeige des Fehlers gesetzt.
SIEHE AUCH
getmsg(2), getrlimit(2), poll(2), putmsg(2), read(2), write(2).
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98