streamio(7) streamio(7)
NAME
streamio - ioctl-Kommandos für STREAMS
SYNTAX
#include <sys/types.h>
#include <stropts.h>
int ioctl(int fildes, int command, ... /* arg */);
BESCHREIBUNG
Die ioctl-Kommandos von STREAMS sind eine Untermenge der ioctl(2)-
Systemaufrufe, die eine Vielzahl von Steuerfunktionen für Datenströme
ausführen.
fildes ist eine offene Dateikennzahl, die einen Stream angibt. command
legt die Steuerfunktion fest, die ausgeführt werden soll (siehe
unten). arg stellt zusätzliche Informationen dar, die vom jeweiligen
Kommando benötigt werden. Der Typ von arg hängt vom Kommando ab, ist
aber generell ein ganzzahliger Wert oder ein Zeiger auf eine kommando-
spezifische Datenstruktur. command und arg werden vom Stream-Kopf
interpretiert. Bestimmte Kombinationen dieser Argumente können an ein
Modul oder einen Treiber im Stream weitergeleitet werden.
Da diese STREAMS-Kommandos eine Untermenge von ioctl sind, gelten für
diese alle Fehler, die dort ebenfalls gelten. Zusätzlich zu diesen
Fehlern schlägt der Aufruf mit errno gleich EINVAL fehl, ohne daß die
Steuerfunktion ausgeführt wird, wenn der Stream, auf den fildes ver-
weist, unterhalb eines Multiplexers angebunden ist, oder wenn command
kein gültiger Wert für einen Stream ist.
Zusätzlich können, wie unter ioctl beschrieben, STREAMS-Module und
-Treiber Fehler erkennen. In diesem Fall sendet das Modul oder der
Treiber eine Fehler-Nachricht an den Stream-Kopf, die eine Fehlernum-
mer enthält. Dadurch schlagen nachfolgende Systemaufrufe fehl, wobei
errno gleich diesem Wert gesetzt ist.
KOMMANDO-FUNKTIONEN
Die folgenden ioctl-Kommandos, mit den jeweils angegebenen Fehlernum-
mern, können auf alle STREAMS-Dateien angewendet werden:
IPUSH Klinkt das Modul, auf dessen Name arg zeigt, in den
Anfang des aktuellen Streams ein, direkt unterhalb des
Stream-Kopfs. Ist der Stream eine Pipe, dann wird das
Modul zwischen den Stream-Köpfen beider Enden der Pipe
eingeklinkt. Danach ruft dieses Kommando die open-Routine
des neu eingeklinkten Moduls auf. Im Fehlerfall nimmt
errno einen der folgenden Werte an:
EINVAL Ungültiger Modulname.
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
ENXIO Die open-Routine des neuen Moduls schlug
fehl.
ENXIO Verbindungsabbruch für fildes empfangen.
IPOP Klinkt das Modul direkt unterhalb des Stream-Kopfs aus
dem Stream aus, auf den fildes verweist. Damit ein Modul
aus einer Pipe ausgeklinkt werden kann, muß das Modul von
der Seite her ausgeklinkt werden, von der es eingeklinkt
worden ist. arg sollte in diesem Fall gleich 0 sein. Im
Fehlerfall nimmt errno einen der folgenden Werte an:
EINVAL Kein Modul Stream vorhanden.
ENXIO Verbindungsabbruch für fildes empfangen.
ILOOK Ermittelt den Namen des Moduls unmittelbar unterhalb des
Stream-Kopfs in dem Stream, der durch fildes angegeben
wird, und legt ihn in einer mit dem Nullbyte abgeschlos-
senen Zeichenkette ab, auf die arg zeigt. Der Puffer, auf
den arg zeigt, sollte mindestens FMNAMESZ+1 Bytes lang
sein. Eine (#include <sys/conf.h>)-Anweisung ist notwen-
dig. Im Fehlerfall nimmt errno einen der folgenden Werte
an:
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums.
EINVAL Kein Modul im Stream vorhanden.
IFLUSH Dieses Kommando leert alle Lese- und/oder Schreib-Queues,
je nachdem, welchen Wert arg hat. Zulässige Werte für arg
sind:
FLUSHR Lese-Queues leeren.
FLUSHW Schreib-Queues leeren.
FLUSHRW Lese- und Schreib-Queues leeren.
Sind in einer Pipe oder FIFO keine Module eingeklinkt,
dann wird die Lese-Queue des Stream-Kopfs an einem der
beiden Enden geleert, je nach Wert von arg.
Ist FLUSHR gesetzt und fildes eine Pipe, dann wird die
Lese-Queue des aktuellen Endes der Pipe und die Schreib-
Queue des anderen Endes geleert. Ist fildes eine FIFO, so
werden beide Queues geleert.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
Ist FLUSHW gesetzt und fildes eine Pipe und existiert das
andere Ende der Pipe, dann wird die Lese-Queue des ande-
ren Endes und die Schreib-Queue dieses Endes der Pipe
geleert. Ist fildes eine FIFO, so werden beide Queues
geleert.
Ist FLUSHRW gesetzt, so werden alle Lese-Queues geleert,
d. h. die Lese-Queue der FIFO und die Lese-Queues an bei-
den Enden der Pipe werden geleert.
Das korrekte Pufferleeren für eine Pipe oder FIFO mit
eingeklinkten Modulen wird durch das pipemod-Modul
erreicht. Dieses Modul sollte das erste Modul sein, das
in eine Pipe eingeklinkt wird, so daß es sich am Mittel-
punkt der Pipe befindet.
Im Fehlerfall nimmt errno einen der folgenden Werte an:
ENOSR Es konnte kein Puffer für die flush-Nach-
richt reserviert werden, da nicht genügend
STREAMS-Speicherplatz verfügbar war.
EINVAL Ungültiger wert für arg.
ENXIO Verbindungsabbruch für fildes empfangen.
IFLUSHBAND Leert ein bestimmtes Band von Nachrichten. arg zeigt auf
eine bandinfo-Struktur, die folgende Komponenten besitzt:
unsigned char bipri;
int biflag;
Die biflag-Komponente kann gleich FLUSHR, FLUSHW oder
FLUSHRW sein (siehe oben).
ISETSIG Informiert den Stream-Kopf darüber, daß der Benutzer
will, daß der Systemkern das SIGPOLL-Signal auslöst
[siehe signal(2)], wenn ein bestimmtes Ereignis für den
dem fildes zugeordneten Stream eintritt. ISETSIG unter-
stützt die Fähigkeit zur asynchronen Verarbeitung unter
STREAMS. Der Wert von arg ist eine Bitmaske, die angibt,
bei welchen Ereignissen das Signal ausgelöst werden soll.
Es handelt sich dabei um das bitweise ODER einer beliebi-
gen Kombination der folgenden Konstanten:
SINPUT Irgendeine Nachricht ungleich MPCPROTO traf
in der Lese-Queue des Stream-Kopfs ein. Die-
ses Ereignis wird aus Gründen der Kompatibi-
lität zu früheren Versionen von UNIX System
V angeboten. Dieses Ereignis wird auch dann
gesetzt, wenn die Nachricht die Länge 0 hat.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
SRDNORM Eine Nachricht normaler Priorität befindet
sich an der Spitze der Lese-Queue des
Stream-Kopfs.
SRDBAND Eine Nachricht im Prioritätsband > 0 befin-
det sich an der Spitze der Lese-Queue des
Stream-Kopfs.
SHIPRI Eine Nachricht mit hoher Priorität
(MPCPROTO) befindet sich an der Spitze der
Lese-Queue des Stream-Kopfs.
SOUTPUT Eine Schreib-Queue für normale Daten (Prio-
ritätsband == 0) ist nicht länger voll (ohne
Flußkontrolle). Dies informiert den Benut-
zer, daß Platz in der Queue vorhanden ist,
normale Daten in Richtung strom-abwärts zu
senden oder zu schreiben.
SWRNORM Genau wie SOUTPUT.
SWRBAND Ein Prioritätsband > 0 existiert in einer
strom-abwärts gelegenen Queue und ist
beschreibbar. Dies informiert einen Benut-
zer, daß Platz in der Queue vorhanden ist,
Daten mit Priorität in Richtung strom-
abwärts zu senden oder zu schreiben.
SMSG Eine MSIG- oder MPCSIG-Nachricht, die das
SIGPOLL-Kennzeichen enthält, hat die Spitze
der Lese-Queue des Stream-Kopfs erreicht.
SERROR Eine MERROR-Nachricht erreicht den Stream-
Kopf.
SHANGUP Eine MHANGUP-Nachrichten erreicht den
Stream-Kopf.
SBANDURG Wird dieses Ereignis zusammen mit SRDBAND
verwendet, dann wird SIGURG statt SIGPOLL
erzeugt, wenn eine Nachricht hoher Priorität
die Spitze der Lese-Queue des Stream-Kopfs
erreicht.
Ein Benutzerprozeß kann entscheiden, nur im Fall von
Nachrichten hoher Priorität ein Signal zugestellt zu
bekommen, wenn er die Bitmaske arg auf den Wert SHIPRI
setzt.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
Prozesse, die das Signal SIGPOLL erhalten wollen, müssen
sich explizit für den Empfang anmelden, indem sie
ISETSIG verwenden. Wenn sich mehrere Prozesse für dieses
Signal anmelden und dabei das gleiche Ereignis für den-
selben Stream anfordern, dann erhält jeder Prozeß das
Signal, wenn das Ereignis eintritt.
Ist der Wert von arg gleich 0, dann meldet sich der auf-
rufende Prozeß wieder ab und er erhält keine weiteren
SIGPOLL-Signale mehr. Im Fehlerfall nimmt errno einen der
folgenden Werte an:
EINVAL Der Wert von arg ist ungültig oder arg ist
gleich 0 und der Prozeß nicht für den Emp-
fang des SIGPOLL-Signals angemeldet.
EAGAIN Die Reservierung einer Datenstruktur für die
Signal-Anforderung schlug fehl.
IGETSIG Liefert die Ereignisse, für die sich der aufrufende Pro-
zeß derzeit angemeldet hat, um ein SIGPOLL-Signal zu
erhalten. Die Ereignisse werden in der Bitmaske zurückge-
liefert, auf die arg zeigt, wobei die Ereignisse die in
der Beschreibung von ISETSIG spezifizierten sind [siehe
oben]. Im Fehlerfall nimmt errno einen der folgenden
Werte an:
EINVAL Der Prozeß ist nicht für den Empfang des
SIGPOLL-Signals angemeldet.
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums.
IFIND Vergleicht die Namen aller Module, die sich derzeit im
Stream befinden, mit dem Namen, auf den arg zeigt. Es
liefert den Wert 1 zurück, wenn das angegebene Modul im
Stream vorhanden ist. Es liefert den Wert 0, wenn das
angegebene Modul nicht eingeklinkt ist. Im Fehlerfall
nimmt errno einen der folgenden Werte an:
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums.
EINVAL arg enthält keinen gültigen Modulnamen.
IPEEK Erlaubt einem Benutzer, die Informationen in der ersten
Nachricht in der Lese-Queue des Stream-Kopfs zu lesen,
ohne die Nachricht aus der Queue zu entfernen. IPEEK
arbeitet analog zu getmsg(2), außer daß dieses Kommando
die Nachricht nicht aus der Queue entfernt. arg zeigt auf
eine strpeek-Struktur, die folgende Komponenten enthält:
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
Die maxlen-Komponente in den strbuf-Strukturen ctlbuf und
databuf [siehe getmsg(2)] muß gleich der Anzahl der Bytes
gesetzt sein, die als Steuer- oder Daten-Informationen
gelesen werden sollen. flags kann gleich RSHIPRI oder
gleich 0 gesetzt sein. Ist RSHIPRI gesetzt, dann sucht
IPEEK eine Nachricht hoher Priorität in der Lese-Queue
des Stream-Kopfs. Andernfalls sucht IPEEK nach der
ersten Nachricht in der Lese-Queue des Stream-Kopfs.
IPEEK liefert den Wert 1, wenn eine Nachricht gefunden
wurde und den Wert 0, wenn keine Nachricht in der Lese-
Queue des Stream-Kopfs gefunden werden konnte. Dieses
Kommando wartet nicht darauf, daß eine Nachricht ein-
trifft. Nach der Rückkehr liefert ctlbuf die Information
aus dem Steuerteil, databuf die Informationen aus dem
Datenteil und flags enthält den Wert RSHIPRI oder 0. Im
Fehlerfall nimmt errno einen der folgenden Werte an:
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums oder der Pufferbe-
reich, der in ctlbuf oder databuf angegeben
wurde, befindet sich außerhalb des reser-
vierten Adreßraums.
EBADMSG Zu lesende eingereihte Nachricht ist für
IPEEK ungültig.
EINVAL flags hat einen ungültigen Wert.
ISRDOPT Setzt die Einstellung für das Lesen [siehe read(2)],
wobei es den Wert des Arguments arg verwendet. Zulässige
Werte für arg sind:
RNORM Betriebsart "Bytestrom" (Voreinstellung).
RMSGD Betriebsart "Nachricht verwerfen".
RMSGN Betriebsart "Nachricht nicht verwerfen".
Zusätzlich kann die Behandlung von Steuer-Nachrichten
durch den Stream-Kopf durch folgende Kennzeichen für arg
geändert werden:
RPROTNORM read() schlägt mit EBADMSG fehl, wenn sich
eine Steuer-Nachricht am Anfang der Lese-
Queue des Stream-Kopfs befindet. Dies ist
das Standard-Verhalten.
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
RPROTDAT Liefert den Steuerteil einer Nachricht als
Daten, wenn ein Benutzer read() aufruft.
RPROTDIS Verwirft den Steuerteil einer Nachricht und
liefert einen vorhandenen Datenteil aus,
wenn ein Benutzer read() aufruft.
Im Fehlerfall nimmt errno den folgenden Wert an:
EINVAL arg hat keinen der oben genannten legalen
Werte.
IGRDOPT Liefert die derzeit gültige Einstellung für das Lesen in
der int-Variablen, auf die arg zeigt. Die Einstellungen
für das Lesen werden unter read(2) beschrieben. Im Feh-
lerfall nimmt errno den folgenden Wert an:
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums.
INREAD Zählt die Anzahl der Datenbytes in den Datenblöcken der
ersten Nachricht in der Lese-Queue des Stream-Kopfs und
legt diese Anzahl in der Variablen ab, auf die arg zeigt.
Das Ergebnis für dieses Kommando ist die Anzahl der Nach-
richten in der Lese-Queue des Stream-Kopfs. Wird z. B. in
arg der Wert 0 zurückgeliefert, aber der ioctl-Aufruf
liefert ein Ergebnis größer als 0, dann zeigt dies an,
daß die nächste Nachricht in der Queue die Länge 0 hat.
Im Fehlerfall nimmt errno den folgenden Wert an:
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums.
IFDINSERT Erzeugt eine Nachricht aus benutzer-definierten Puffern,
fügt Informationen über einen anderen Stream hinzu und
sendet die Nachricht strom-abwärts. Die Nachricht enthält
einen Steuer- und einen optionalen Datenteil. Die zu sen-
denden Daten- und Steuerteile werden dadurch unterschie-
den, daß sie in eigenen Puffern abgelegt werden (siehe
unten).
arg zeigt auf eine strfdinsert-Struktur, die folgende
Komponenten besitzt:
struct strbuf ctlbuf;
struct strbuf databuf;
long flags;
int fildes;
int offset;
Seite 7 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
Die len-Komponente in der strbuf-Struktur ctlbuf [siehe
putmsg(2)] muß gleich der Größe eines Zeigers plus der
Anzahl von Bytes für die Steuer-Informationen dieser
Nachricht sein. fildes in der strfdinsert-Struktur gibt
die Dateikennzahl des anderen Streams an. offset muß an
der Wortgrenze ausgerichtet sein und gibt die Anzahl der
Bytes an, nach der IFDINSERT einen Zeiger hinter dem
Anfang des Steuerpuffers ablegt. Dieser Zeiger ist die
Adresse der Lese-Queue-Struktur des Treibers für den
Stream, der fildes in der strfdinsert-Struktur ent-
spricht. Die len-Komponente in der strbuf-Struktur
databuf muß gleich der Anzahl der Bytes gesetzt sein, die
als Daten-Informationen mit der Nachricht gesendet werden
sollen, oder 0, wenn kein Datenteil gesendet werden soll.
flags gibt an, welche Art von Nachricht erzeugt werden
soll. Eine einfache Nachricht wird erzeugt, wenn flags
gleich 0 ist, eine Nachricht hoher Priorität wird
erzeugt, wenn flags gleich RSHIPRI ist. Bei einfachen
Nachrichten blockiert IFDINSERT, wenn die Schreib-Queue
des Streams aufgrund der internen Flußkontrolle voll ist.
Bei Nachrichten hoher Priorität blockiert IFDINSERT in
diesem Fall nicht. Bei einfachen Nachrichten blockiert
IFDINSERT dann nicht, wenn die Schreib-Queue voll ist,
aber ONDELAY oder ONONBLOCK gesetzt ist. Statt dessen
schlägt der Aufruf fehl und errno ist dann gleich EAGAIN.
IFDINSERT blockiert auch, wenn der Aufruf auf die Ver-
fügbarkeit von Nachrichten-Blöcken wartet und nicht durch
ein Fehlen interner Betriebsmittel daran gehindert wird.
Dabei ist es gleichgültig, ob ONDELAY oder ONONBLOCK
angegeben wurden. Es werden keine Teil-Nachricht gesen-
det. Im Fehlerfall nimmt errno einen der folgenden Werte
an:
EAGAIN Es wurde ein Nachricht ohne Priorität ange-
geben, ONDELAY oder ONONBLOCK ist gesetzt
und die Schreib-Queue des Streams ist auf-
grund der internen Flußkontrolle voll.
ENOSR Es konnten keine Puffer für die zu erzeu-
gende Nachricht reserviert werden, da zu
wenig Speicherplatz unter STREAMS verfügbar
war.
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums oder der Pufferbe-
reich, der in ctlbuf oder databuf angegeben
wurde, befindet sich außerhalb des reser-
vierten Adreßraums.
Seite 8 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
EINVAL Es liegt einer der folgenden Gründe vor:
fildes in der strfdinsert-Struktur ist keine
gültige offene Dateikennzahl für einen
Stream; die Größe eines Zeigers plus offset
ist größer als die len-Komponente des Puf-
fers, der durch ctlptr angegeben wurde;
offset gibt keinen korrekt ausgerichteten
Ort im Datenpuffer an; flags hat einen unde-
finierten Wert.
ENXIO Ein Verbindungsabbruch wurde für fildes im
ioctl-Aufruf oder für fildes in der
strfdinsert-Struktur empfangen.
ERANGE Die len-Komponente für den durch databuf
angegebenen Puffer liegt nicht in dem
Bereich, der durch die Werte für die maxi-
male und minimale Paketgröße des obersten
Moduls im Stream festgelegt ist. Oder die
len-Komponente für den durch databuf angege-
benen Puffer ist größer als die konfigu-
rierte maximale Größe des Datenteils einer
Nachricht. Oder die len-Komponente für den
durch ctlbuf angegebenen Puffer ist größer
als die konfigurierte maximale Größe des
Steuerteils einer Nachricht.
IFDINSERT kann auch dann fehlschlagen, wenn eine
Fehler-Nachricht vom Stream-Kopf des Streams empfangen
wird, der zu fildes in der strfdinsert-Struktur gehört.
In diesem Fall besitzt errno den Wert aus der Nachricht.
ISTR Erzeugt eine interne ioctl-Nachricht aus den Daten, auf
die arg zeigt und sendet diese Nachricht strom-abwärts.
Dieser Mechanismus wird angeboten, um benutzer-definierte
ioctl-Anforderungen strom-abwärts an Module und Treiber
zu senden. Er erlaubt, daß Informationen mit dem ioctl
gesendet werden und liefert dem Benutzer alle Informatio-
nen zurück, die vom strom-abwärtigen Empfänger strom-
aufwärts gesendet werden. ISTR blockiert, bis das System
mit einer positiven oder negativen Bestätigung antwortet,
oder bis nach einer bestimmten Zeitspanne ein Timeout
erfolgt. Wenn ein Timeout erfolgt, dann schlägt der Auf-
ruf mit errno gleich ETIME fehl.
Es kann immer höchstens ein ISTR-Aufruf in einem Stream
aktiv sein. Weitere ISTR-Aufrufe blockieren, bis der
aktive ISTR-Aufruf sich am Stream-Kopf beendet. Die Vor-
einstellung für einen Timeout bei diesen Anforderungen
beträgt 15 Sekunden. ONDELAY und ONONBLOCK [siehe
open(2)] haben keinen Einfluß auf diesen Aufruf.
Seite 9 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
Um Anforderungen strom-abwärts zu senden, muß arg auf
eine strioctl-Struktur zeigen, die folgende Komponenten
enthält:
int iccmd;
int ictimout;
int iclen;
char *icdp;
iccmd ist das interne ioctl-Kommando, das an ein strom-
abwärts liegendes Modul (oder einen Treiber) gesendet
werden soll und ictimout ist die Zahl der Sekunden für
ein Timeout (-1 = unendlich, 0 = Voreinstellung, > 0 =
wie angegeben). iclen ist die Anzahl der Bytes im
Daten-Argument und icdp ist ein Zeiger auf das Daten-
Argument. Die iclen-Komponente besitzt zwei Verwendun-
gen: bei der Eingabe enthält sie die Länge des übergebe-
nen Daten-Arguments, bei der Rückkehr vom Kommando ent-
hält sie die Anzahl der an den Benutzer zurückgelieferten
Bytes (der Puffer, auf den icdp zeigt, sollte groß genug
sein, die möglicherweise von einem Modul oder Treiber
zurückzuliefernden Daten aufnehmen zu können).
Der Stream-Kopf wandelt die Informationen in der
strioctl-Struktur in eine interne ioctl-Nachricht um und
sendet diese strom-abwärts. Im Fehlerfall nimmt errno
einen der folgenden Werte an:
ENOSR Aufgrund fehlenden Speicherplatzes konnte
kein Puffer für die ioctl-Nachricht reser-
viert werden.
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums oder der Pufferbe-
reich, der von icdp und iclen angegeben
wurde (getrennt für gesendete und empfangene
Daten), befindet sich außerhalb des reser-
vierten Adreßraums.
EINVAL iclen ist kleiner als 0, oder iclen ist
größer als die konfigurierte maximale Größe
des Datenteils einer Nachricht, oder
ictimout ist kleiner als -1.
ENXIO Verbindungsabbruch wurde für fildes empfan-
gen.
ETIME Ein strom-abwärtiger ioctl-Aufruf erhielt
ein Timeout bevor eine Bestätigung empfangen
wurde.
Ein ISTR-Aufruf kann auch dann fehlschlagen, wenn eine
Seite 10 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
Fehler- oder Verbindungsabbruch-Nachricht vom Stream-Kopf
des Streams empfangen wird, während dieser auf eine
Bestätigung wartet. Zusätzlich kann eine Fehlernummer in
der positiven oder negativen Nachricht zurückgeliefert
werden, in dem Fall, daß das ioctl-Kommando weiter
strom-abwärts fehlschlägt. In diesem Fall besitzt errno
den Wert aus der Nachricht.
ISWROPT Legt die Einstellungen für das Schreiben fest, wobei der
Wert des Arguments arg benutzt wird. Zulässige Werte für
arg sind:
SNDZERO Sendet eine Nachricht der Länge 0 strom-
abwärts, wenn ein Aufruf von write mit 0
Bytes erfolgt.
Soll in diesem Fall keine Nachricht der Länge 0 gesendet
werden, dann darf dieses Bit in arg nicht gesetzt sein.
Im Fehlerfall nimmt errno einen der folgenden Werte an:
EINVAL arg ist größer als der zulässige Wert.
IGWROPT Liefert die aktuell gültige Einstellung für das Schreiben
in der int-Variablen zurück, auf die arg zeigt (siehe
unter ISWROPT).
ISENDFD Fordert den Stream, der fildes zugeordnet ist, auf, eine
Nachricht, die einen Dateizeiger enthält, an den Stream-
Kopf am anderen Ende der Pipe zu senden. Der Dateizeiger
entspricht dem Argument arg, das eine offene Dateikenn-
zahl sein muß.
ISENDFD wandelt arg in den entsprechenden Dateizeiger
um. Das Kommando reserviert einen Nachrichten-Block und
fügt den Dateizeiger in diesen Block ein. Benutzernummer
und Gruppennummer des sendenden Prozesses werden eben-
falls eingefügt. Diese Nachricht wird direkt in die
Lese-Queue des Stream-Kopfs am anderen Ende der Pipe ein-
getragen. Im Fehlerfall nimmt errno einen der folgenden
Werte an:
EAGAIN Der sendende Stream ist nicht in der Lage,
einen Nachrichten-Block zu reservieren, der
den Dateizeiger aufnehmen kann.
EAGAIN Die Lese-Queue des empfangenden Stream-Kopfs
ist voll und kann die von ISENDFD gesendete
Nachricht nicht aufnehmen.
EBADF arg ist keine gültige, offene Dateikennzahl.
Seite 11 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
EINVAL fildes ist nicht mit einer Pipe verbunden.
ENXIO Verbindungsabbruch für fildes empfangen.
IRECVFD Ermittelt die Dateikennzahl, die der Nachricht zugeordnet
ist, die mit dem Kommando ISENDFD für ioctl über eine
Pipe gesendet wurde. arg ist ein Zeiger auf einen Daten-
puffer, der groß genug ist, eine strrecvfd-Datenstruktur
mit den folgenden Komponenten aufzunehmen:
int fd;
uidt uid;
gidt gid;
char fill[8];
fd ist eine Dateikennzahl. uid und gid sind die Benutzer-
und die Gruppennummer des sendenden Streams.
Wenn ONDELAY und ONONBLOCK nicht gesetzt ist [siehe
open(2)], dann blockiert IRECVFD, bis eine Nachricht am
Stream-Kopf vorhanden ist. Ist ONDELAY oder ONONBLOCK
gesetzt, so schlägt IRECVFD fehl, wobei errno gleich
EAGAIN ist, wenn keine Nachricht am Stream-Kopf vorhanden
ist.
Wenn die Nachricht am Stream-Kopf eine Nachricht ist, die
von ISENDFD gesendet wurde, dann wird eine neue
Benutzer-Dateikennzahl für den in der Nachricht enthalte-
nen Dateizeiger reserviert. Die neue Dateikennzahl wird
in der fd-Komponente der strrecvfd-Struktur abgelegt. Die
Struktur wird in den Datenpuffer des Benutzers kopiert,
auf den arg zeigt. Im Fehlerfall nimmt errno einen der
folgenden Werte an:
EAGAIN Es befindet sich keine Nachricht in der
Lese-Queue des Stream-Kopfs und ONDELAY
oder ONONBLOCK ist gesetzt.
EBADMSG Die Nachricht in der Lese-Queue des Stream-
Kopfs ist keine Nachricht, die eine überge-
bene Dateikennzahl enthält.
EFAULT arg zeigt auf einen Punkt außerhalb des
reservierten Adreßraums.
EMFILE NOFILES Dateikennzahlen sind bereits geöff-
net.
ENXIO Verbindungsabbruch für fildes empfangen.
Seite 12 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
EOVERFLOW uid oder gid ist zu groß, um in der Struktur
abgelegt werden zu können, auf die arg
zeigt.
ILIST Erlaubt es einem Benutzer, alle Modulnamen im Stream aus-
zugeben, einschließlich des obersten Treibers. Ist arg
gleich NULL, so ist das Ergebnis des Aufrufs die Anzahl
der Module (einschließlich Treiber), die sich in dem
Stream befinden, auf den fildes verweist. Dies erlaubt
dem Benutzer dann genügend Platz für die Modulnamen zu
reservieren. Ist arg ungleich NULL, dann sollte dieses
Argument auf eine strlist-Struktur zeigen, die folgende
Komponenten besitzt:
int slnmods;
struct strmlist *slmodlist;
Die strmlist-Struktur besitzt folgende Komponente:
char lname[FMNAMESZ+1];
slnmods gibt die Anzahl der Einträge an, die der Benut-
zer im Vektor reserviert hat. Nach der Rückkehr enthält
slmodlist die Liste der Modulnamen. Das Ergebnis des
Aufrufs gibt die Anzahl der eingetragenen Namen an. Im
Fehlerfall kann errno einen der folgenden Werte annehmen:
EINVAL Die Komponente slnmods ist kleiner als 1.
EAGAIN Puffer konnte nicht reserviert werden.
IATMARK Erlaubt es dem Benutzer, zu überprüfen, ob die aktuelle
Nachricht in der Lese-Queue des Stream-Kopfs von einem
Modul weiter strom-abwärts "markiert" wurde. arg legt
fest, wie die Überprüfung durchgeführt wird, wenn es
mehrfach "markierte" Nachrichten in der Lese-Queue des
Stream-Kopfs geben kann. Es kann folgende Werte annehmen:
ANYMARK Prüfen, ob Nachricht markiert ist.
LASTMARK Prüfen, ob die Nachricht die letzte mar-
kierte in der Queue ist.
Das Ergebnis hat den Wert 1, wenn die entsprechende
Markierungs-Bedingung erfüllt ist. Andernfalls hat es den
Wert 0. Im Fehlerfall kann errno den folgenden Wert
annehmen:
EINVAL Der Wert von arg ist ungültig.
Seite 13 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
ICKBAND Dieses Kommando prüft, ob eine Nachricht in einem gegebe-
nen Prioritätsband in der Lese-Queue des Stream-Kopfs
existiert. Das Ergebnis ist 1, wenn eine solche Nachricht
existiert, oder -1 bei einem Fehler. arg sollte eine
ganze Zahl sein, die den Wert des zu überprüfenden Prio-
ritätsbands enthält. Im Fehlerfall kann errno den folgen-
den Wert annehmen:
EINVAL Der Wert von arg ist nicht gültig.
IGETBAND Dieses Kommando liefert das Prioritätsband der ersten
Nachricht in der Lese-Queue des Stream-Kopfs in dem ganz-
zahligen Wert zurück, auf den arg zeigt. Im Fehlerfall
kann errno den folgenden Wert annehmen:
ENODATA Es befindet sich keine Nachricht in der
Lese-Queue des Stream-Kopfs.
ICANPUT Prüft, ob ein bestimmtes Band beschreibbar ist. arg ist
gleich dem zu überprüfenden Prioritätsband. Das Ergebnis
ist 0, wenn das Prioritätsband arg der Flußkontrolle
unterliegt, 1, wenn das Band beschreibbar ist oder -1 bei
einem Fehler. Im Fehlerfall kann errno den folgenden Wert
annehmen:
EINVAL Der Wert von arg ist nicht gültig.
ISETCLTIME Erlaubt es einem Benutzer, festzulegen, wie lange der
Stream-Kopf wartet, wenn ein Stream geschlossen wird und
sich noch Daten in den Schreib-Queues befinden. Bevor er
jedes Modul und jeden Treiber schließt, wartet der
Stream-Kopf die angegebene Zeit, damit die Daten noch
übertragen werden können. Sind nach der Wartezeit immer
noch Daten vorhanden, so werden diese verworfen. arg ist
ein Zeiger auf die Anzahl der Millisekunden, die gewartet
werden sollen, jeweils auf den nächsthöheren gültigen
Wert im System gerundet. Die Voreinstellung ist 15 Sekun-
den. Im Fehlerfall kann errno den folgenden Wert anneh-
men:
EINVAL Der Wert von arg ist nicht gültig.
IGETCLTIME Liefert die Wartezeit beim Schließen in der long-Varia-
blen zurück, auf die arg zeigt.
Seite 14 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
Die folgenden vier Kommandos werden dazu verwendet, Multiplex-Konfigu-
rationen unter STREAMS auf- und abzubauen.
ILINK Verbindet zwei Datenströme, wobei fildes die Dateikenn-
zahl des Streams ist, der mit dem Multiplex-Treiber ver-
bunden ist und arg ist die Dateikennzahl des Streams, der
mit einem anderen Treiber verbunden ist. Der Stream, der
mit arg angegeben wird, wird unterhalb des Multiplex-
Treibers verbunden. ILINK erwartet, daß der Multiplex-
Treiber eine Bestätigung an den Stream-Kopf sendet. Die-
ser Aufruf liefert eine Multiplexer-Kennzahl (eine Kenn-
zahl, die für den Abbau des Multiplexers benötigt wird,
siehe IUNLINK) bei Erfolg und -1 bei einem Fehler. Im
Fehlerfall nimmt errno einen der folgenden Werte an:
ENXIO Verbindungsabbruch für fildes empfangen.
ETIME Timeout erfolgte, bevor Bestätigung vom
Stream-Kopf empfangen wurde.
EAGAIN Zeitweise nicht genügend Speicher für die
Ausführung von ILINK verfügbar.
ENOSR Nicht genügend Speicher unter STREAMS ver-
fügbar, um ILINK ausführen zu können.
EBADF arg ist keine gültige, offene Dateikennzahl.
EINVAL Der fildes zugeordnete Stream unterstützt
das Multiplexen nicht.
EINVAL arg ist kein Stream, oder bereits unter
einem Multiplexer verbunden.
EINVAL Die angegebene Verbindung würde eine
Schleife in der sich ergebenden Konfigura-
tion erzeugen, d. h. ein gegebener Treiber
ist in einer Multiplex-Konfiguration an mehr
als einer Stelle vorhanden.
EINVAL fildes ist die Dateikennzahl einer Pipe oder
FIFO.
Die Operation ILINK kann auch fehlschlagen, wenn sie
darauf wartet, daß der Multiplex-Treiber die Verbindungs-
anforderung bestätigt. Dies kann dann geschehen, wenn
eine Nachricht am Stream-Kopf von fildes eintrifft, die
einen Fehler oder einen Verbindungsabbruch anzeigt.
Zusätzlich kann eine Fehlernummer in der positiven oder
negativen Bestätigung enthalten sein. In diesen Fällen
schlägt ILINK fehl, wobei errno gleich dem Wert in der
Nachricht ist.
Seite 15 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
IUNLINK Löst die Verbindung zwischen den beiden durch fildes und
arg angegebenen Datenströmen. fildes ist die Dateikenn-
zahl des mit dem Multiplex-Treiber verbundenen Streams.
arg ist die Multiplexer-Kennzahl, die von ILINK zurück-
geliefert worden ist. Ist arg gleich -1, dann werden alle
Datenströme abgehängt, die mit fildes verbunden waren.
Ebenso wie ILINK erwartet auch dieses Kommando, daß der
Multiplex-Treiber die Auflösung der Verbindung bestätigt.
Im Fehlerfall nimmt errno einen der folgenden Werte an:
ENXIO Verbindungsabbruch für fildes empfangen.
ETIME Timeout erfolgte, bevor eine Bestätigung vom
Stream-Kopf empfangen wurde.
ENOSR Nicht genügend Speicher unter STREAMS ver-
fügbar, um ILINK ausführen zu können.
EINVAL arg ist keine gültige Multiplexer-Kennzahl
oder fildes ist nicht der Stream für den die
ILINK-Operation ausgeführt wurde, die arg
geliefert hat.
EINVAL fildes ist die Dateikennzahl einer Pipe oder
FIFO.
Die Operation IUNLINK kann auch fehlschlagen, wenn sie
darauf wartet, daß der Multiplex-Treiber die Verbindungs-
anforderung bestätigt. Dies kann dann geschehen, wenn
eine Nachricht am Stream-Kopf von fildes eintrifft, die
einen Fehler oder einen Verbindungsabbruch anzeigt.
Zusätzlich kann eine Fehlernummer in der positiven oder
negativen Bestätigung enthalten sein. In diesen Fällen
schlägt IUNLINK fehl, wobei errno gleich dem Wert in der
Nachricht ist.
IPLINK Verbindet zwei Datenströme, wobei fildes die Dateikenn-
zahl des Streams ist, der mit dem Multiplex-Treiber ver-
bunden ist und arg ist die Dateikennzahl des Streams, der
mit einem anderen Treiber verbunden ist. Der Stream, der
mit arg angegeben wird, wird unterhalb des Multiplex-
Treibers über einen ständigen Verweis verbunden. IPLINK
erwartet, daß der Multiplex-Treiber eine Bestätigung an
den Stream-Kopf sendet. Dieser Aufruf erzeugt einen stän-
digen Verweis, der auch dann existieren kann, wenn die
Dateikennzahl fildes, die dem oberen Stream zum
Multiplex-Treiber zugeordnet ist, geschlossen wird. Die-
ser Aufruf liefert eine Multiplexer-Kennzahl (eine Kenn-
zahl, die für den Abbau des Multiplexers benötigt wird,
siehe IPUNLINK) bei Erfolg und -1 bei einem Fehler. Im
Fehlerfall nimmt errno einen der folgenden Werte an:
Seite 16 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
ENXIO Verbindungsabbruch für fildes empfangen.
ETIME Timeout erfolgte, bevor eine Bestätigung vom
Stream-Kopf empfangen wurde.
EAGAIN STREAMS-Speicher für die Ausführung von
IPLINK konnte nicht reserviert werden.
EBADF arg ist keine gültige, offene Dateikennzahl.
EINVAL fildes unterstützt das Multiplexen nicht.
EINVAL arg ist kein Stream oder bereits unter einem
Multiplexer angehängt.
EINVAL Die angegebene Verbindung würde eine
Schleife in der sich ergebenden Konfigura-
tion erzeugen, d. h. ein gegebener Treiber
ist in einer Multiplex-Konfiguration an mehr
als einer Stelle vorhanden.
EINVAL fildes ist die Dateikennzahl einer Pipe oder
FIFO.
Die Operation IPLINK kann auch fehlschlagen, wenn sie
darauf wartet, daß der Multiplex-Treiber die Verbindungs-
anforderung bestätigt. Dies kann dann geschehen, wenn
eine Nachricht am Stream-Kopf von fildes eintrifft, die
einen Fehler oder einen Verbindungsabbruch anzeigt.
Zusätzlich kann eine Fehlernummer in der positiven oder
negativen Bestätigung enthalten sein. In diesen Fällen
schlägt IPLINK fehl, wobei errno gleich dem Wert in der
Nachricht ist.
IPUNLINK Löst die ständige Verbindung zwischen den beiden durch
fildes und arg angegebenen Datenströmen. fildes ist die
Dateikennzahl des mit dem Multiplex-Treiber verbundenen
Streams. arg ist die Multiplexer-Kennzahl, die von
IPLINK zurückgeliefert worden ist, als ein Stream unter
dem Multiplex-Treiber eingehängt worden ist. Ist arg
gleich MUXIDALL, dann werden alle Datenströme abgehängt,
die mit fildes über ständige Verweise verbunden waren.
Ebenso wie IPLINK erwartet auch dieses Kommando, daß der
Multiplex-Treiber die Auflösung der Verbindung bestätigt.
Im Fehlerfall nimmt errno einen der folgenden Werte an:
ENXIO Verbindungsabbruch für fildes empfangen.
ETIME Timeout erfolgte, bevor eine Bestätigung vom
Stream-Kopf empfangen wurde.
Seite 17 Reliant UNIX 5.44 Gedruckt 11/98
streamio(7) streamio(7)
EAGAIN Puffer für die Bestätigung konnte nicht
reserviert werden.
EINVAL Ungültige Multiplexer-Kennzahl.
EINVAL fildes ist die Dateikennzahl einer Pipe oder
FIFO.
Die Operation IPUNLINK kann auch fehlschlagen, wenn sie
darauf wartet, daß der Multiplex-Treiber die Verbindungs-
anforderung bestätigt. Dies kann dann geschehen, wenn
eine Nachricht am Stream-Kopf von fildes eintrifft, die
einen Fehler oder einen Verbindungsabbruch anzeigt.
Zusätzlich kann eine Fehlernummer in der positiven oder
negativen Bestätigung enthalten sein. In diesen Fällen
schlägt IPUNLINK fehl, wobei errno gleich dem Wert in
der Nachricht ist.
DIAGNOSE
Sofern oben nicht anderes angegeben wurde, liefert ioctl bei Erfolg
den Wert 0 und im Fehlerfall den Wert -1, wobei errno wie angegeben
gesetzt ist.
SIEHE AUCH
close(2), fcntl(2), getmsg(2), introprm2(2), ioctl(2), open(2),
poll(2), putmsg(2), read(2), signal(2), write(2), signal(5).
Leitfaden für Programmierer: STREAMS
Seite 18 Reliant UNIX 5.44 Gedruckt 11/98