ioctl(2) ioctl(2)
NAME
ioctl - Geräte und STREAMS steuern
SYNTAX
#include <unistd.h>
int ioctl(int fildes, int request, ... /* arg */);
BESCHREIBUNG
Die Funktion ioctl() führt eine Vielzahl an Steuerfunktionen für
STREAMS-Geräte aus. Bei Nicht-STREAMS-Geräten sind die von diesem Auf-
ruf ausgeführten Funktionen nicht definiert. Das Argument request und
ein optionales drittes Argument (mit variierendem Typ) werden an den
Stream, auf den fildes verweist, weitergeleitet und vom entsprechenden
Teil des Stream interpretiert.
Das Argument fildes ist ein offener Dateideskriptor, der auf ein Gerät
verweist.
Das Argument request wählt die auszuführende Steuerfunktion aus und
ist von dem jeweiligen adressierten STREAMS-Gerät abhängig.
Das Argument arg enthält zusätzliche Informationen, die vom jeweiligen
STREAMS-Gerät für die Ausführung der angeforderten Funktion benötigt
werden. Der Typ von arg hängt von der entsprechenden Steueranforderung
ab, ist jedoch entweder eine ganze Zahl oder ein Zeiger auf eine gerä-
tespezifische Datenstruktur.
Die auf STREAMS anwendbaren ioctl()-Kommandos, deren Argumente und die
Fehlerstatus für die einzelnen Kommandos werden im folgenden beschrie-
ben.
Die folgenden ioctl()-Kommandos mit den angegebenen Fehlerwerten gel-
ten für alle STREAMS-Dateien:
IPUSH Stellt das Modul, auf dessen Namen arg zeigt, an den
Anfang des aktuellen Stream, direkt unter den Stream-Kopf,
und ruft anschließend die Funktion open() des neu plazier-
ten Moduls auf.
Die Funktion ioctl() mit dem Kommando IPUSH schlägt bei
folgenden Bedingungen fehl:
EINVAL Ungültiger Modulname.
ENXIO Die Funktion open() des neuen Moduls ist fehlge-
schlagen.
ENXIO Hangup bei fildes erhalten.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
IPOP Entfernt das Modul, das direkt unter dem Stream-Kopf des
Stream steht, auf den fildes verweist. Das Argument arg in
einer IPOP-Anforderung sollte 0 sein.
Die Funktion ioctl() mit dem Kommando IPOP schlägt bei
folgenden Bedingungen fehl:
EINVAL Der Stream enthält kein Modul.
ENXIO Hangup bei fildes erhalten.
ILOOK Ruft den Namen des Moduls ab, das direkt unter dem
Stream-Kopf des Stream steht, auf den fildes verweist, und
stellt ihn in eine Zeichenkette, auf die arg zeigt. Der
Puffer, auf den das Argument arg zeigt, sollte eine Größe
von mindestens FMNAMESZ+1 Byte aufweisen. FMNAMESZ ist in
<stropts.h> definiert.
Die Funktion ioctl() mit dem Kommando ILOOK schlägt bei
folgenden Bedingungen fehl:
EINVAL Der Stream enthält kein Modul.
IFLUSH Diese Anforderung leert abhängig vom Wert des Arguments
arg die Lese- und/oder Schreibwarteschlangen. Gültige
Werte für arg sind:
FLUSHR Leert alle Lesewarteschlangen.
FLUSHW Leert alle Schreibwarteschlangen.
FLUSHRW Leert alle Lese- und alle Schreibwarteschlangen.
Die Funktion ioctl() mit dem Kommando IFLUSH schlägt bei
folgenden Bedingungen fehl:
EINVAL Ungültiger Wert für arg.
EAGAIN oder ENOSR
Für die Meldung zum Leeren der Warteschlangen
können keine Puffer zugewiesen werden.
ENXIO Hangup bei fildes erhalten.
IFLUSHBAND Leert einen bestimmten Bereich von Meldungen. Das Argument
arg zeigt auf eine bandinfo-Struktur. Die Komponente
biflag kann eine der oben beschriebenen Angaben FLUSHR,
FLUSHW oder FLUSHRW sein. Die Komponente bipri legt den
Prioritätsbereich fest, dessen Inhalt gelöscht werden
soll.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
ISETSIG Fordert an, daß die STREAMS-Implementierung das Signal
SIGPOLL an den aufrufenden Prozeß sendet, wenn ein
bestimmtes Ereignis im Stream auftritt, der fildes
zugeordnet ist. ISETSIG unterstützt eine asynchrone Ver-
arbeitung in STREAMS. Der Wert von arg ist eine Bitmaske,
die das Ereignis angibt, für das der Prozeß das Signal
erhalten sollte. Hierbei handelt es sich um die bitweise
OR-Verknüpfung einer beliebigen Kombination aus folgenden
Konstanten:
SRDNORM Eine normale Meldung (Prioritätsbereich auf 0
gesetzt) ist oben in der Lesewarteschlange für
den Stream-Kopf eingegangen. Auch bei leeren
Meldungen (Meldungen mit Nullänge) wird ein Sig-
nal erzeugt.
SRDBAND Eine Meldung mit einem Prioritätsbereich
ungleich Null ist oben in der Lesewarteschlange
für den Stream-Kopf eingegangen. Auch bei leeren
Meldungen wird ein Signal erzeugt.
SINPUT Eine Meldung, die keine hohe Priorität aufweist,
ist oben in der Lesewarteschlange für den
Stream-Kopf eingegangen. Auch bei leeren Meldun-
gen wird ein Signal erzeugt.
SHIPRI Eine Meldung mit hoher Priorität liegt in der
Lesewarteschlange für den Stream-Kopf vor. Auch
bei leeren Meldungen (Meldungen mit Nullänge)
wird ein Signal erzeugt.
SOUTPUT Die Schreibwarteschlange für normale Daten
(Prioritätsbereich 0) direkt unter dem Stream-
Kopf ist nicht mehr voll. Hierüber wird dem Pro-
zeß mitgeteilt, daß in der Warteschlange wieder
Platz ist, um normale Daten downstream zu senden
(bzw. zu schreiben).
SWRNORM Entspricht SOUTPUT.
SWRBAND Die Schreibwarteschlange für einen Prioritätsbe-
reich ungleich Null direkt unter dem Stream-Kopf
ist nicht mehr voll. Hierüber wird dem Prozeß
mitgeteilt, daß in der Warteschlange wieder
Platz ist, um normale Daten downstream zu senden
(bzw. zu schreiben).
SMSG Eine STREAMS-Signalmeldung mit dem Signal
SIGPOLL hat den Anfang der Lesewarteschlange für
den Stream-Kopf erreicht.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
SERROR Eine Benachrichtigung über eine Fehlerbedingung
ist im Stream-Kopf eingegangen.
SHANGUP Eine Benachrichtigung über ein Hangup ist im
Stream-Kopf eingegangen.
SBANDURG Bei gemeinsamer Verwendung mit SRDBAND wird das
Signal SIGURG anstelle von SIGPOLL ausgegeben,
wenn eine Prioritätsmeldung den Anfang der Lese-
warteschlange für den Stream-Kopf erreicht.
Ist arg gleich 0, wird der aufrufende Prozeß nicht regi-
striert und erhält keine weiteren SIGPOLL-Signale für den
Stream, auf den fildes verweist.
Prozesse, die SIGPOLL-Signale erhalten sollen, müssen
explizit für den Empfang dieser Signale über ISETSIG
registriert sein. Sind mehrere Prozesse zum Empfang dieses
Signals für dasselbe Ereignis im selben Stream regi-
striert, erhält jeder Prozeß ein Signal, wenn das Ereignis
eintritt.
Die Funktion ioctl() mit dem Kommando ISETSIG schlägt bei
folgenden Bedingungen fehl:
EINVAL Der Wert von arg ist ungültig.
EINVAL Der Wert von arg ist 0, und der aufrufende Pro-
zeß ist nicht für den Empfang des SIGPOLL-Sig-
nals registriert.
EAGAIN Es sind nicht genügend Ressourcen zum Speichern
der Signalanforderung verfügbar.
IGETSIG Gibt die Ereignisse zurück, für die der aufrufende Prozeß
derzeit ein SIGPOLL-Signal senden soll. Die Ereignisse,
die in der Beschreibung von ISETSIG weiter oben angegeben
sind, werden als Bitmaske in einer ganzen Zahl int, auf
die arg zeigt, zurückgegeben.
Die Funktion ioctl() mit dem Kommando IGETSIG schlägt bei
folgenden Bedingungen fehl:
EINVAL Der Prozeß ist nicht zum Empfang des SIGPOLL-
Signals registriert.
IFIND Diese Anforderung vergleicht die Namen aller im Stream
vorliegenden Module mit dem Namen, auf den das Argument
arg zeigt, und gibt 1 zurück, wenn das angegebene Modul im
Stream enthalten ist. Andernfalls wird 0 zurückgegeben.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
Die Funktion ioctl() mit dem Kommando IFIND schlägt bei
folgenden Bedingungen fehl:
EINVAL arg enthält keinen gültigen Modulnamen.
IPEEK Mit dieser Anforderung kann ein Prozeß die Informationen
aus der ersten Meldung in der Lesewarteschlange für den
Stream-Kopf abrufen, ohne die Meldung aus der Warte-
schlange zu entfernen. Das Kommando wird analog zu
getmsg() verwendet, nur daß bei IPEEK die Meldung nicht
aus der Warteschlange entfernt wird. Das Argument arg
zeigt auf eine strpeek-Struktur.
Die Komponente maxlen in den Strukturen ctlbuf und databuf
strbuf müssen auf die Anzahl der Byte für Steuer- und/oder
Dateninformationen gesetzt sein, die abgerufen werden sol-
len. Die Komponente flags kann als RSHIPRI oder 0 mar-
kiert sein, wie von getmsg() beschrieben. Setzt der Prozeß
flags auf RSHIPRI, sucht das Kommando IPEEK in der Lese-
warteschlange für den Stream-Kopf beispielsweise nur nach
einer Meldung mit hoher Priorität.
IPEEK gibt 1 zurück, wenn eine Meldung abgerufen wurde,
und 0, wenn keine Meldung in der Lesewarteschlange des
Stream-Kopfes gefunden wurde, oder wenn das RSHIPRI-Flag
in flags gesetzt wurde und in der Lesewarteschlange für
den Stream-Kopf keine Meldung mit hoher Priorität enthal-
ten war. Hierbei wird nicht auf den Eingang einer Meldung
gewartet. Bei der Rückgabe gibt ctlbuf Informationen aus
dem Steuerungspuffer und databuf Informationen aus dem
Datenpuffer an. flags enthält den Wert RSHIPRI oder 0.
ISRDOPT Setzt den Lesemodus und verwendet dazu den Wert aus dem
Argument arg. Lesemodi werden in read() beschrieben. Gül-
tige Flags für arg sind:
RNORM Byte-Stream-Modus (der Standardwert).
RMSGD Modus für Meldung löschen (message-discard).
RMSGN Modus für Meldung nicht löschen (message-nondis-
card).
Die bitweise über logisches OR verknüpften Modi RMSGD und
RMSGN (jeweils inklusiv) geben den Wert EINVAL zurück. Bei
den bitweise über logisches OR verknüpften Modi RNORM und
entweder RMSGD oder RMSGN (jeweils inklusiv) überschreibt
das jeweils andere Flag den Standardwert RNORM.
Ferner kann die Behandlung von Steuermeldungen durch den
Stream-Kopf durch Setzen eines der folgenden Flags in arg
geändert werden:
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
RPROTNORM read() schlägt mit EBADMSG fehl, wenn sich eine
Meldung, die einen Steuerteil enthält, am Anfang
der Lesewartschlange für den Stream-Kopf befin-
det.
RPROTDAT Der Steuerteil einer Meldung wird als Daten
zurückgegeben, wenn ein Prozeß eine read()-Funk-
tion ausgibt.
RPROTDIS Der Steuerteil einer Meldung wird gelöscht, und
nur ein eventuell vorhandener Datenteil wird
zurückgegeben, wenn ein Prozeß eine read()-Funk-
tion ausgibt.
Die Funktion ioctl() mit dem Kommando ISRDOPT schlägt bei
folgender Bedingung fehl:
EINVAL Das Argument arg ist ungültig.
IGRDOPT Gibt die aktuelle Einstellung des Lesemodus wie oben
beschrieben in einer ganzen Zahl int zurück, auf die das
Argument arg zeigt. Lesemodi werden in read() beschrieben.
INREAD Zählt die Anzahl der Datenbytes im Datenteil der ersten
Meldung in der Lesewarteschlange für den Stream-Kopf und
stellt diesen Wert in die Ganzzahl int, auf die arg zeigt.
Der Rückgabewert für das Kommando ist die Anzahl der Mel-
dungen in der Lesewarteschlange für den Stream-Kopf. Wenn
beispielsweise 0 in arg zurückgegeben wird, der Rückgabe-
wert von ioctl() jedoch größer als 0 ist, bedeutet dies,
daß die nächste Meldung in der Warteschlange eine leere
Meldung ist.
IFDINSERT Erstellt eine Meldung aus dem/den angegebenen Puffer(n),
fügt Informationen über einen anderen Stream hinzu und
sendet die Meldung downstream. Die Meldung enthält einen
Steuerteil und einen optionalen Datenteil. Die zu senden-
den Daten- und Steuerteile werden wie weiter unten
beschrieben in separate Puffer gestellt. Das Argument arg
zeigt auf eine strfdinsert-Struktur.
Die Komponente len in der Struktur ctlbuf strbuf muß auf
die Größe eines Zeigers plus der Anzahl Bytes für Steue-
rinformationen gesetzt werden, die mit der Meldung gesen-
det werden sollen. Die Komponente fildes gibt den Dateide-
skriptor des anderen Stream an, und die Komponente offset
(die so ausgerichtet sein muß, daß sie als ein Zeiger ver-
wendet werden kann) gibt die relative Position (den Off-
set) vom Anfang des Steuerpuffers an, in dem IFDINSERT
einen Zeiger speichert, dessen Interpretation für das
Stream-Ende spezifisch ist. Die Komponente len in der
Struktur databuf strbuf muß auf die Anzahl Bytes für
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
Dateninformationen gesetzt werden, die mit der Meldung
gesendet werden sollen, oder auf 0, wenn kein Datenteil
gesendet werden soll.
Die Komponente flags gibt den zu erstellenden Meldungstyp
an. Eine normale Meldung wird erstellt, wenn flags auf 0
gesetzt wird, und eine Meldung mit hoher Priorität wird
erstellt, wenn flags auf RSHIPRI gesetzt wird. Bei Mel-
dungen ohne Priorität blockiert IFDINSERT, wenn die
Stream-Schreibwarteschlange aufgrund interner Flußsteue-
rungsbedingungen voll ist. Bei Prioritätsmeldungen blok-
kiert IFDINSERT den Prozeß bei einer solchen Bedingung
nicht. Bei Meldungen ohne Priorität blockiert IFDINSERT
nicht, wenn die Schreibwarteschlange voll und ONONBLOCK
gesetzt ist. Statt dessen schlägt das Kommando fehl und
setzt errno auf EAGAIN.
IFDINSERT blockiert den Prozeß auch, sofern dies nicht
durch fehlende interne Ressourcen verhindert wird, wenn
auf die Verfügbarkeit von Meldungsblöcken im Stream gewar-
tet wird, und zwar unabhängig von der Priorität und davon,
ob ONONBLOCK angegeben ist. Es wird keine Teilmeldung
gesendet.
Die Funktion ioctl() mit dem Kommando IFDINSERT schlägt
bei folgenden Bedingungen fehl:
EAGAIN Eine Meldung ohne Priorität ist angegeben, das
Flag ONONBLOCK ist gesetzt und die Stream-
Schreibwarteschlange ist aufgrund interner Fluß-
steuerungsbedingungen voll.
EAGAIN oder ENOSR
Für die zu erstellende Meldung können keine Puf-
fer zugeordnet werden.
EINVAL Eine der folgenden Bedingungen liegt vor:
- Die Komponente fd der Struktur strfdinsert
bezeichnet einen ungültigen offenen Stream-
Dateideskriptor.
- Die Größe eines Zeigers plus offset ist grö-
ßer als die Komponente len für den durch
ctlptr angegebenen Puffer.
- Die Komponente offset gibt keine korrekt aus-
gerichtete Position im Datenpuffer an.
- In flags ist ein nicht definierter Wert
gespeichert.
Seite 7 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
ENXIO Hangup bei fd oder fildes erhalten.
ERANGE Die Komponente len für den durch databuf angege-
benen Puffer liegt nicht innerhalb des durch die
maximale und die minimale Paketgröße des ober-
sten Stream-Moduls angegebenen Bereichs, oder
die Komponente len für den durch databuf angege-
benen Puffer überschreitet die maximal konfigu-
rierte Größe des Datenteils einer Meldung; oder
die Komponente len für den durch ctlbuf angege-
benen Puffer überschreitet die maximal konfigu-
rierte Größe des Steuerteils einer Meldung.
ISTR Erstellt eine interne STREAMS-ioctl()-Meldung aus den Daten,
auf die arg zeigt, und sendet diese Meldung downstream.
Dieser Mechanismus dient zum Senden von ioctl()-Anforde-
rungen an Downstream-Module und -Treiber. Hiermit können
Informationen mit ioctl() gesendet werden und an den Pro-
zeß werden alle upstream gesendeten Informationen vom
Downstream-Empfänger zurückgegeben. ISTR blockiert den
Prozeß so lange, bis das System entweder mit einer positi-
ven oder einer negativen Bestätigungsmeldung antwortet
oder eine bestimmte Zeitdauer überschritten wird. Bei
einer Zeitüberschreitung schlägt die Anforderung fehl,
wobei errno auf ETIME gesetzt wird.
In einem Stream kann maximal ein ISTR-Aufruf aktiv sein.
Weitere ISTR-Aufrufe werden blockiert, bis der aktive
ISTR-Aufruf am Stream-Kopf beendet ist. Das Standardin-
tervall für die Zeitüberschreitung für diese Anforderungen
beträgt 15 Sekunden. Das Flag ONONBLOCK hat keine Auswir-
kungen auf diesen Aufruf.
Um Anforderungen downstream senden zu können, muß das
Argument arg auf eine strioctl-Struktur zeigen.
Die Komponente iccmd ist das interne ioctl()-Kommando für
ein Downstream-Modul oder einen Downstream-Treiber, und
ictimout ist die Anzahl der Sekunden (-1 = unendlich, 0 =
implementierungsspezifisches Zeitüberschreitungsintervall,
>0 = wie angegeben), die eine ISTR-Anforderung auf eine
Bestätigung wartet, bevor sie aufgrund der Zeitüberschrei-
tung abgebrochen wird. iclen ist die Anzahl der Bytes im
Datenargument und icdp ist ein Zeiger auf das Datenargu-
ment. Die Komponente iclen dient zwei Zwecken: Bei Ein-
gabe des Kommandos enthält sie die Länge des zu übergeben-
den Datenarguments, und bei der Ausgabe enthält sie die
Anzahl der an den Prozeß zurückgegebenen Bytes. (Der Puf-
fer, auf den icdp zeigt, sollte groß genug für die Auf-
nahme der maximalen Datenmenge sein, die ein Modul oder
der Treiber im Stream zurückgeben kann.)
Seite 8 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
Der Stream-Kopf wandelt die Informationen, auf die die
Struktur strioctl zeigt, in eine interne ioctl()-Kommando-
meldung um, und sendet sie downstream.
Die Funktion ioctl() mit dem Kommando ISTR schlägt bei
folgenden Bedingungen fehl:
EAGAIN oder ENOSR
Für die ioctl()-Meldung können keine Puffer
zugeordnet werden.
EINVAL Die Komponente iclen ist kleiner als 0 oder
größer als die maximal konfigurierte Größe des
Datenteils einer Meldung, oder ictimout ist
kleiner als -1.
ENXIO Hangup bei fildes erhalten.
ETIME Bei einer Downstream-ioctl()-Funktion wurde die
Zeit vor Eingang der Bestätigung überschritten.
Ein ISTR-Aufruf kann auch fehlschlagen, während er auf
eine Bestätigung wartet, und zwar dann, wenn eine Fehler-
oder Hangup-Meldung am Stream-Kopf empfangen wird. Außer-
dem kann ein Fehlercode in der positiven oder negativen
Bestätigungsmeldung zurückgegeben werden, wenn das down-
stream gesendete ioctl()-Kommando fehlschlägt. In diesen
Fällen schlägt ISTR fehl, und errno wird auf den Wert in
der Meldung gesetzt.
ISWROPT Setzt den Schreibmodus und verwendet dazu den Wert aus dem
Argument arg. Gültige Bit-Werte für arg sind:
SNDZERO Sendet bei einem write() von 0 Byte eine leere
Meldung downstream. Wenn in diesem Fall keine
leere Meldung gesendet werden soll, darf dieses
Bit im Argument arg nicht gesetzt werden (arg
könnte zum Beispiel auf 0 gesetzt werden).
Die Funktion ioctl() mit dem Kommando ISWROPT schlägt bei
folgender Bedingung fehl:
EINVAL arg ist nicht auf den oben angegebenen Wert
gesetzt.
IGWROPT Gibt die aktuelle Einstellung des Schreibmodus wie oben
beschrieben in einer ganzen Zahl int zurück, auf die das
Argument arg zeigt.
Seite 9 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
ISENDFD ISENDFD erstellt einen neuen Verweis auf die offene
Dateibeschreibung, die dem Dateideskriptor arg zugeordnet
ist, und schreibt eine Meldung, die diesen Verweis sowie
die Benutzer- und die Gruppen-ID des aufrufenden Prozesses
enthält, in die auf STREAMS basierende Pipe fildes.
Die Funktion ioctl() mit dem Kommando ISENDFD schlägt bei
folgenden Bedingungen fehl:
EAGAIN Der sendende Stream kann keinen Nachrichtenblock
für die Aufnahme des Dateizeigers zuordnen, oder
die Lesewarteschlange des empfangenden Stream-
Kopfes ist voll und kann die von ISENDFD gesen-
dete Meldung nicht annehmen.
EBADF Das Argument arg ist kein gültiger offener
Dateideskriptor.
EINVAL Das Argument fildes ist nicht mit einer Stream-
Pipe verbunden.
ENXIO Hangup bei fildes erhalten.
IRECVFD Ruft den Verweis auf eine offene Dateibeschreibung aus
einer Meldung ab, die mit dem Kommando ISENDFD in die auf
STREAMS basierende Pipe geschrieben wurde, und ordnet
einen neuen Dateideskriptor im aufrufenden Prozeß zu, der
auf diese offene Dateibeschreibung verweist. Das Argument
arg argument ist ein Zeiger auf eine strrecvfd-Datenstruk-
tur wie in <stropts.h> definiert.
Die Komponente fd ist ein Dateideskriptor. Die Komponenten
uid und gid sind die effektive Benutzer-ID bzw. die effek-
tive Gruppen-ID des sendenden Prozesses.
Wenn ONONBLOCK nicht gesetzt ist, wird IRECVFD so lange
blockiert, bis eine Meldung im Stream-Kopf vorliegt. Wenn
ONONBLOCK gesetzt ist, schlägt IRECVFD fehl und errno
wird auf EAGAIN gesetzt, wenn keine Meldung im Stream-Kopf
vorliegt.
Handelt es sich bei der Meldung im Stream-Kopf um eine von
einem ISENDFD-Aufruf gesendete Meldung, wird ein neuer
Dateideskriptor für den offenen Dateideskriptor zugeord-
net, auf den in der Meldung verwiesen wird. Der neue
Dateideskriptor wird in die Komponente fd der Struktur
strrecvfd gestellt, auf die arg zeigt.
Die Funktion ioctl() mit dem Kommando IRECVFD schlägt bei
folgenden Bedingungen fehl:
Seite 10 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
EAGAIN In der Lesewarteschlange für den Stream-Kopf
liegt keine Meldung vor und das Flag ONONBLOCK
ist gesetzt.
EBADMSG Die Meldung in der Lesewarteschlange für den
Stream-Kopf enthält keinen gesendeten Dateide-
skriptor.
EMFILE Im Prozeß ist die maximal zulässige Anzahl von
Dateideskriptoren geöffnet.
ENXIO Hangup bei fildes erhalten.
ILIST Über diese Anforderung kann der Prozeß alle Modulnamen im
Stream bis zum obersten Treibernamen einschließlich aufli-
sten. Wenn arg ein Nullzeiger ist, wird als Rückgabewert
die Anzahl der Module, einschließlich Treiber zurückgege-
ben, die im Stream, auf den fildes zeigt, enthalten sind.
Hierdurch kann der Prozeß genügend Speicherplatz für die
Modulnamen zuordnen. Andernfalls sollte das Kommando auf
eine strlist-Struktur zeigen.
Die Komponente slnmods gibt die Anzahl der Einträge an,
die der Prozeß im Array zugeordnet hat. Bei der Ausgabe
enthält die Komponente slmodlist der Struktur strlist
die Liste der Modulnamen, und die Komponente slnmods die
Anzahl der Einträge, die in das Array slmodlist eingefügt
wurden (diese Zahl umfaßt die Anzahl der Module ein-
schließlich Treiber). Der Rückgabewert von ioctl() ist 0.
Das Einfügen der Einträge beginnt oben im Stream und wird
dann downstream fortgesetzt, bis entweder das Ende des
Stream erreicht ist oder alle angeforderten Module
(slnmods) eingegeben wurden.
Die Funktion ioctl() mit dem Kommando ILIST schlägt bei
folgenden Bedingungen fehl:
EINVAL Die Komponente slnmods ist kleiner als 1.
EAGAIN oder ENOSR
Es können keine Puffer zugeordnet werden.
IATMARK Über diese Anforderung kann der Prozeß erkennen, ob die
Meldung am Anfang der Lesewarteschlange für den Stream-
Kopf downstream durch ein Modul markiert ist. Das Argument
arg legt fest, wie die Überprüfung erfolgen soll, wenn
mehrere Meldungen in der Lesewarteschlange für den
Stream-Kopf markiert sind. Das Argument kann einen der
folgenden Werte haben:
ANYMARK Prüft, ob die Meldung markiert ist.
Seite 11 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
LASTMARK Prüft, ob es sich um die letzte markierte Mel-
dung in der Warteschlange handelt.
Die bitweise logische OR-Verknüpfung der Flags ANYMARK und
LASTMARK (jeweils inklusive) ist erlaubt.
Der Rückgabewert ist 1, wenn die Bedingung für die Markie-
rung erfüllt ist. Andernfalls wird 0 zurückgegeben.
Die Funktion ioctl() mit dem Kommando IATMARK schlägt bei
folgender Bedingung fehl:
EINVAL Ungültiger Wert für arg.
ICKBAND Prüft, ob die Meldung eines bestimmten Prioritätsbereichs
in der Lesewarteschlange für den Stream-Kopf vorliegt.
Hierbei wird 1 zurückgegeben, wenn eine Meldung der jewei-
ligen Priorität vorliegt, 0, wenn keine Meldung vorliegt
und -1 bei einem Fehler. arg sollte ein Wert vom Typ int
sein.
Die Funktion ioctl() mit dem Kommando ICKBAND schlägt bei
folgender Bedingung fehl:
EINVAL Ungültiger Wert für arg.
IGETBAND Gibt den Prioritätsbereich der ersten Meldung in der Lese-
warteschlange für den Stream-Kopf in einer ganzen Zahl
zurück, auf die arg verweist.
Die Funktion ioctl() mit dem Kommando IGETBAND schlägt
bei folgender Bedingung fehl:
ENODATA In der Lesewarteschlange für den Stream-Kopf
liegt keine Meldung vor.
ICANPUT Prüft, ob für einen bestimmten Bereich Schreibzugriff
gilt. arg wird auf den entsprechenden Prioritätsbereich
gesetzt. Bei Flußsteuerung für den Bereich wird 0 zurück-
gegeben, bei Schreibzugriff wird 1 und bei einem Fehler -1
zurückgegeben.
Die Funktion ioctl() mit dem Kommando ICANPUT schlägt bei
folgenden Bedingungen fehl:
EINVAL Ungültiger Wert für arg.
Seite 12 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
ISETCLTIME Über diese Anforderung kann der Prozeß die Zeit einstel-
len, die der Stream-Kopf warten soll, wenn beim Schließen
eines Stream noch Daten in der Schreibwarteschlange ent-
halten sind. Befinden sich vor dem Schließen der einzelnen
Module oder des Treibers noch Daten in der Schreibwarte-
schlange, wird die Ausführung des Stream-Kopfes um die
angegebene Zeit verzögert, damit die Daten aus der War-
teschlange geleert werden können. Sind auch nach Ablauf
der Verzögerungszeit noch Daten vorhanden, werden diese
gelöscht. Das Argument arg ist ein Zeiger auf eine ganze
Zahl, die die Anzahl der Millisekunden für die Verzögerung
gerundet auf den nächsten gültigen Wert angibt. Wenn
ISETCLTIME nicht für einen Stream ausgeführt wird, wird
ein implementierungsspezifischer Standardwert für die
Zeitüberschreitung verwendet.
Die Funktion ioctl() mit dem Kommando ISETCLTIME schlägt
bei folgenden Bedingungen fehl:
EINVAL Ungültiger Wert für arg.
IGETCLTIME Diese Anforderung gibt die Wartezeit beim Schließen in der
Ganzzahl zurück, auf die arg zeigt.
Multiplex-STREAMS-Konfigurationen
Die folgenden vier Kommandos werden zum Herstellen bzw. Aufheben von
Verbindungen zu Multiplex-STREAMS-Konfigurationen eingesetzt. Diese
Kommandos verwenden einen implementierungsspezifischen Standardwert
für die Zeitüberschreitung.
ILINK Verbindet zwei Streams, wobei fildes der Dateideskriptor
des Stream ist, der mit dem Multiplex-Treiber verbunden
ist, und arg der Dateideskriptor des Stream, der mit einem
anderen Treiber verbunden ist. Der durch arg bezeichnete
Stream wird unterhalb (downstream) des Multiplex-Treibers
verbunden. Für ILINK muß der Multiplex-Treiber eine
Bestätigungsmeldung in Bezug auf die Verbindung an den
Stream-Kopf senden. Dieser Aufruf gibt bei erfolgreicher
Ausführung eine Multiplexer-ID zurück (eine ID, die zum
Aufheben der Multiplexer-Verbindung verwendet wird; siehe
IUNLINK). Bei einem Fehler wird -1 zurückgegeben.
Die Funktion ioctl() mit dem Kommando ILINK schlägt bei
folgenden Bedingungen fehl:
ENXIO Hangup bei fildes erhalten.
ETIME Zeitüberschreitung vor Eingang der Bestätigungs-
meldung am Stream-Kopf.
Seite 13 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
EAGAIN oder ENOSR
Es kann kein STREAMS-Speicher für die Ausführung
von ILINK zugeordnet werden.
EBADF Das Argument arg ist kein gültiger offener
Dateideskriptor.
EINVAL Das Argument fildes unterstützt kein Multiple-
xen; oder arg ist kein Stream oder ist bereits
downstream von einem Multiplexer verbunden; oder
die angegebene ILINK-Operation würde den
Stream-Kopf an mehr als einer Stelle im
Multiplex-Stream verbinden.
Ein ILINK-Aufruf kann auch fehlschlagen, während er auf
eine Bestätigung seitens des Multiplex-Treibers wartet,
und zwar dann, wenn eine Fehler- oder Hangup-Meldung am
Stream-Kopf von fildes empfangen wird. Außerdem kann ein
Fehlercode in der positiven oder negativen Bestätigungs-
meldung zurückgegeben werden. In diesen Fällen schlägt
ILINK fehl, und errno wird auf den Wert in der Meldung
gesetzt.
IUNLINK Hebt die Verbindung der beiden durch fildes und arg ange-
gebenen Streams auf. fildes ist der Dateideskriptor des
Streams, der mit dem Multiplexer-Treiber verbunden ist.
Das Argument arg ist die Multiplexer-ID, die vom ioctl()-
Kommando ILINK zurückgegeben wurde, als ein Stream
downstream vom Multiplex-Treiber verbunden wurde. Ist arg
gleich MUXIDALL, wird die Verbindung aller mit fildes
verbundenen Streams aufgehoben. Wie auch bei ILINK ist
für dieses Kommando eine Bestätigung erforderlich.
Die Funktion ioctl() mit dem Kommando IUNLINK schlägt bei
folgenden Bedingungen fehl:
ENXIO Hangup bei fildes erhalten.
ETIME Zeitüberschreitung vor Eingang der Bestätigungs-
meldung am Stream-Kopf.
EAGAIN oder ENOSR
Es können keine Puffer für die Bestätigungsmel-
dung zugeordnet werden.
EINVAL Ungültige Multiplexer-ID.
Seite 14 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
Ein IUNLINK-Aufruf kann auch fehlschlagen, während er auf
eine Bestätigung seitens des Multiplex-Treibers wartet,
und zwar dann, wenn eine Fehler- oder Hangup-Meldung am
Stream-Kopf von fildes empfangen wird. Außerdem kann ein
Fehlercode in der positiven oder negativen Bestätigungs-
meldung zurückgegeben werden. In diesen Fällen schlägt
IUNLINK fehl, und errno wird auf den Wert in der Meldung
gesetzt.
IPLINK Erstellt eine permanente Verbindung ("persistent connec-
tion") zwischen zwei Streams, wobei fildes der Dateide-
skriptor des Streams ist, der mit dem Multiplex-Treiber
verbunden ist und arg der Dateideskriptor des Stream, der
mit einem anderen Gerät verbunden ist. Dieser Aufruf
erstellt eine permanente Verbindung, die auch dann noch
bestehen kann, wenn der dem oberen Stream zum Multiplex-
Treiber zugeordnete Dateideskriptor fildes geschlossen
wird. Der durch arg bezeichnete Stream wird über eine per-
manente Verbindung unterhalb des Multiplex-Treibers ver-
bunden. Für IPLINK muß der Multiplex-Treiber eine Bestä-
tigungsmeldung an den Stream-Kopf senden. Dieser Aufruf
gibt bei erfolgreicher Ausführung eine Multiplexer-ID
zurück (eine ID, die zum Aufheben der Multiplexer-Verbin-
dung verwendet wird; siehe IPUNLINK). Bei einem Fehler
wird -1 zurückgegeben.
Die Funktion ioctl() mit dem Kommando IPLINK schlägt bei
folgenden Bedingungen fehl:
ENXIO Hangup bei fildes erhalten.
ETIME Zeitüberschreitung vor Eingang der Bestätigungs-
meldung am Stream-Kopf.
EAGAIN oder ENOSR
Es kann kein STREAMS-Speicher für die Ausführung
von IPLINK zugeordnet werden.
EBADF Das Argument arg ist kein gültiger offener
Dateideskriptor.
EINVAL Das Argument fildes unterstützt kein Multiple-
xen; oder arg ist kein Stream oder ist bereits
downstream von einem Multiplexer verbunden; oder
die angegebene IPLINK-Operation würde den
Stream-Kopf an mehr als einer Stelle im Multi-
plex-Stream verbinden.
Seite 15 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
Ein IPLINK-Aufruf kann auch fehlschlagen, während er auf
eine Bestätigung seitens des Multiplex-Treibers wartet,
und zwar dann, wenn eine Fehler- oder Hangup-Meldung am
Stream-Kopf von fildes empfangen wird. Außerdem kann ein
Fehlercode in der positiven oder negativen Bestätigungs-
meldung zurückgegeben werden. In diesen Fällen schlägt
IPLINK fehl, und errno wird auf den Wert in der Meldung
gesetzt.
IPUNLINK Hebt die permanente Verbindung der beiden durch fildes und
arg angegebenen Streams auf. Das Argument fildes ist der
Dateideskriptor des Stream, der mit dem Multiplex-Treiber
verbunden ist. Das Argument arg ist die Multiplexer-ID,
die vom ioctl()-Kommando IPLINK zurückgegeben wurde, als
ein Stream downstream vom Multiplex-Treiber verbunden
wurde. Ist arg gleich MUXIDALL, wird die permanente Ver-
bindung aller mit fildes verbundenen Streams aufgehoben.
Wie auch bei IPLINK ist für dieses Kommando eine Bestäti-
gung seitens des Multiplex-Treibers erforderlich.
Die Funktion ioctl() mit dem Kommando IPUNLINK schlägt
bei folgenden Bedingungen fehl:
ENXIO Hangup bei fildes erhalten.
ETIME Zeitüberschreitung vor Eingang der Bestätigungs-
meldung am Stream-Kopf.
EAGAIN oder ENOSR
Es können keine Puffer für die Bestätigungsmel-
dung zugeordnet werden.
EINVAL Ungültige Multiplexer-ID.
Ein IPUNLINK-Aufruf kann auch fehlschlagen, während er
auf eine Bestätigung seitens des Multiplex-Treibers war-
tet, und zwar dann, wenn eine Fehler- oder Hangup-Meldung
am Stream-Kopf von fildes empfangen wird. Außerdem kann
ein Fehlercode in der positiven oder negativen Bestäti-
gungsmeldung zurückgegeben werden. In diesen Fällen
schlägt IPUNLINK fehl, und errno wird auf den Wert in der
Meldung gesetzt.
RÜCKGABEWERT
Nach erfolgreicher Ausführung gibt ioctl() einen anderen Wert als -1
zurück, der von der jeweiligen Steuerfunktion des STREAMS-Geräts
abhängig ist. Andernfalls wird -1 zurückgegeben und errno gesetzt, um
den Fehler anzuzeigen.
Seite 16 Reliant UNIX 5.44 Gedruckt 11/98
ioctl(2) ioctl(2)
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
Bei folgenden allgemeinen Bedingungen schlägt ioctl() fehl:
EBADF Das Argument fildes ist kein gültiger, offener Dateideskrip-
tor.
EINTR Während der ioctl()-Operation wurde ein Signal aufgefangen.
EINVAL Der Stream oder Multiplexer, auf den fildes verweist, ist
(direkt oder indirekt) downstream von einem Multiplexer ver-
bunden.
Wenn ein zugrundeliegender Gerätetreiber einen Fehler findet, schlägt
ioctl() bei folgenden Bedingungen fehl:
EINVAL Das Argument request oder arg ist für dieses Gerät nicht
gültig.
EIO Ein physischer Ein-/Ausgabefehler ist aufgetreten.
ENOTTY Das Argument fildes ist keinem STREAMS-Gerät zugeordnet, das
Steuerfunktionen akzeptiert.
ENXIO Die Argumente request und arg sind für diesen Gerätetreiber
zwar gültig, der angeforderte Service kann jedoch auf diesem
untergeordneten Gerät nicht ausgeführt werden.
ENODEV Das Argument fildes verweist zwar auf ein gültiges STREAMS-
Gerät, die ioctl()-Funktion wird von dem zugehörigen Geräte-
treiber jedoch nicht unterstützt.
Wenn ein Stream downstream von einem Multiplexer verbunden ist, setzt
jedes ioctl()-Kommando, mit Ausnahme von IUNLINK und IPUNLINK, errno
auf EINVAL.
ANWENDUNGSZWECK
Der implementierungsspezifische Zeitüberschreitungsintervall für
STREAMS wurde auf 15 Sekunden eingestellt.
SIEHE AUCH
close(2), fcntl(2), getmsg(2), open(2), pipe(2), poll(2), putmsg(2),
read(2), sigaction(2), write(2), unistd(4), stropts(5), streamio(7),
termio(7).
Seite 17 Reliant UNIX 5.44 Gedruckt 11/98