ioctl - Geräte und STREAMS steuern

Definition

#include <stropts.h>

int ioctl(int fildes, int request, .../* arg */);

Beschreibung

ioctl() führt eine Vielzahl an Steuerfunktionen für Geräte und STREAMS aus. Bei Nicht-STREAMS-Dateien sind die von diesem Aufruf ausgeführten Funktionen undefiniert. Das Argument request und ein optionales drittes Argument mit variierendem Typ werden an die mit fildes bezeichnete Datei weitergereicht und vom Gerätetreiber interpretiert.

fildes ist ein offener Dateideskriptor, der sich auf ein Gerät bezieht.

request wählt die auszuführende Steuerfunktion aus und hängt jeweils von den adressierten Geräten ab.

arg beinhaltet zusätzliche Informationen, die von diesen spezifischen Geräten zur Ausführung der angefragten Funktion benötigt werden. Der Datentyp von arg hängt von der jeweiligen Steuerfunktion ab, ist jedoch entweder eine ganze Zahl oder ein Zeiger auf eine gerätespezifische Datenstruktur.

Die folgenden ioctl()-Kommandos, mit den jeweils angegebenen Fehlernummern, können auf alle STREAMS-Dateien angewendet werden:

I_PUSH	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()-Funktion des neu eingeklinkten Moduls auf. ioctl() mit dem I_PUSH-Kommando schlägt fehl, wenn gilt:
	EINVAL	Ungültiger Modulname.
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums.
	ENXIO	Die open()-Funktion des neuen Moduls schlug fehl.
	ENXIO	Verbindungsabbruch für fildes empfangen.
I_POP	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, muss 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: ioctl() mit dem I_POP-Kommando schlägt fehl, wenn gilt:
	EINVAL	Kein Modul Stream vorhanden.
	ENXIO	Verbindungsabbruch für fildes empfangen.
I_LOOK	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 abgeschlossenen Zeichenkette ab, auf die arg zeigt. Der Puffer, auf den arg zeigt, sollte mindestens FMNAMESZ+1 Bytes lang sein. FMNAMESZ ist in stropts.h definiert. ioctl() mit dem I_LOOK-Kommando schlägt fehl, wenn gilt:
	EINVAL	Kein Modul im Stream vorhanden.
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums.
I_FLUSH	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
	ioctl() mit dem I_FLUSH-Kommando schlägt fehl, wenn gilt:
	EINVAL	Ungültiger Wert für arg.
	EAGAIN oder ENOSR
		Es konnte kein Puffer für die flush-Nachricht reserviert werden, da nicht genügend STREAMS-Speicherplatz verfügbar war.
	ENXIO	Verbindungsabbruch für fildes empfangen.
I_FLUSHBAND
	Leert ein bestimmtes Band von Nachrichten. arg zeigt auf eine bandinfo-Struktur, die folgende Komponenten besitzt: unsigned char bi_pri ; int bi_flag ; Die bi_flag-Komponente kann gleich FLUSHR, FLUSHW oder FLUSHRW sein (siehe oben). Die bi_pri-Komponente bestimmt das Prioritätsband.
I_SETSIG	Informiert den Stream-Kopf darüber, dass der Benutzer will, dass der Systemkern das SIGPOLL-Signal auslöst (siehe signal()), wenn ein bestimmtes Ereignis für den dem fildes zugeordneten Stream eintritt. I_SETSIG unterstü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 beliebigen Kombination der folgenden Konstanten:
	S_RDNORM	Eine Nachricht normaler Priorität (Prioritätsband = 0) befindet sich an der Spitze der Lese-Queue des Stream-Kopfs. Ein Signal wird auch dann erzeugt, wenn die Nachricht die Länge 0 hat.
	S_RDBAND	Eine Nachricht im Prioritätsband > 0 befindet sich an der Spitze der Lese-Queue des Stream-Kopfs. Ein Signal wird auch dann erzeugt, wenn die Nachricht die Länge 0 hat.
	S_INPUT	Irgendeine Nachricht ungleich M_PCPROTO (hochprior) traf in der Lese-Queue des Stream-Kopfs ein. Dieses Ereignis wird aus Gründen der Kompatibilität zu früheren Versionen von UNIX System V angeboten. Ein Signal wird auch dann erzeugt, wenn die Nachricht die Länge 0 hat.
	S_HIPRI	Eine Nachricht mit hoher Priorität (M_PCPROTO) befindet sich an der Spitze der Lese-Queue des Stream-Kopfs. Ein Signal wird auch dann erzeugt, wenn die Nachricht die Länge 0 hat.
	S_OUTPUT	Eine Schreib-Queue für normale Daten (Prioritätsband = 0) gerade unterhalb des Stream-Kopfes ist nicht mehr voll (ohne Flusskontrolle). Dies informiert den Benutzer, dass Platz in der Queue vorhanden ist, normale Daten in Richtung stream-abwärts zu senden oder zu schreiben.
	S_WRNORM	Genau wie S_OUTPUT.
	S_WRBAND	Eine Schreib-Queue für Daten im Prioritätsband != 0 gerade unterhalb des Stream-Kopfes ist nicht mehr voll. Dies informiert einen Benutzer, dass Platz in der Queue vorhanden ist, Daten mit Priorität in Richtung stream-abwärts zu senden oder zu schreiben.
	S_MSG	Eine M_SIG- oder M_PCSIG-Nachricht, die das Signal SIGPOLL enthält, hat die Spitze der Lese-Queue des Stream-Kopfs erreicht.
	S_ERROR	Eine M_ERROR-Nachricht hat den Stream-Kopf erreicht.
	S_HANGUP	Eine M_HANGUP-Nachricht hat den Stream-Kopf erreicht.
	S_BANDURG	Wird dieses Ereignis zusammen mit S_RDBAND verwendet, dann wird SIGURG statt SIGPOLL erzeugt, wenn eine Nachricht hoher Priorität die Spitze der Lese-Queue des Stream-Kopfs erreicht.
	Ist der Wert von arg gleich 0, dann meldet sich der aufrufende Prozess wieder ab, und er erhält keine weiteren SIGPOLL-Signale mehr. Ein Benutzerprozess kann entscheiden, nur im Fall von Nachrichten hoher Priorität ein Signal zugestellt zu bekommen, wenn er die Bitmaske arg auf den Wert S_HIPRI setzt. Prozesse, die das Signal SIGPOLL erhalten wollen, müssen sich explizit für den Empfang anmelden, indem sie I_SETSIG verwenden. Wenn sich mehrere Prozesse für dieses Signal anmelden und dabei das gleiche Ereignis für denselben Stream anfordern, dann erhält jeder Prozess das Signal, wenn das Ereignis eintritt. ioctl() mit dem I_SETSIG-Kommando schlägt fehl, wenn gilt:
	EINVAL	Der Wert von arg ist ungültig oder arg ist gleich 0 und der Prozess nicht für den Empfang des SIGPOLL-Signals angemeldet.
	EAGAIN	Die Reservierung einer Datenstruktur für die Signal-Anforderung schlug fehl.
I_GETSIG	Liefert die Ereignisse, für die sich der aufrufende Prozess derzeit angemeldet hat, um ein SIGPOLL-Signal zu erhalten. Die Ereignisse werden in der Bitmaske zurückgeliefert, auf die arg zeigt, wobei die Ereignisse die in der Beschreibung von I_SETSIG spezifizierten sind (siehe oben). ioctl() mit dem I_GETSIG-Kommando schlägt fehl, wenn gilt:
	EINVAL	Der Prozess ist nicht für den Empfang des SIGPOLL-Signals angemeldet.
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums.
I_FIND	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. ioctl() mit dem I_FIND-Kommando schlägt fehl, wenn gilt:
	EINVAL	arg enthält keinen gültigen Modulnamen.
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums.
I_PEEK	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. I_PEEK arbeitet analog zu getmsg(), außer dass dieses Kommando die Nachricht nicht aus der Queue entfernt. arg zeigt auf eine strpeek-Struktur, die folgende Komponenten enthält: struct strbuf ctlbuf ; struct strbuf databuf ; long flags ; Die maxlen-Komponente in den strbuf-Strukturen ctlbuf und databuf (siehe getmsg()) muss gleich der Anzahl der Bytes gesetzt sein, die als Steuer- und/oder Daten-Informationen gelesen werden sollen. flags kann gleich RS_HIPRI oder gleich 0 gesetzt sein. Ist RS_HIPRI gesetzt, dann sucht I_PEEK eine Nachricht hoher Priorität in der Lese-Queue des Stream-Kopfs. Andernfalls sucht I_PEEK nach der ersten Nachricht in der Lese-Queue des Stream-Kopfs. I_PEEK liefert den Wert 1, wenn eine Nachricht gefunden wurde. I_PEEK liefert den Wert 0, wenn keine Nachricht in der Lese-Queue des Stream-Kopfs gefunden werden konnte, bzw. wenn flags auf RS_HIPRI gesetzt war und keine Nachricht mit hoher Priorität gefunden wurde. Dieses Kommando wartet nicht darauf, dass eine Nachricht eintrifft. Nach der Rückkehr liefert ctlbuf die Informationen aus dem Steuerteil, databuf die Informationen aus dem Datenteil und flags enthält den Wert RS_HIPRI oder 0. ioctl() mit dem I_PEEK-Kommando schlägt fehl, wenn gilt:
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums oder der Pufferbereich, der in ctlbuf oder databuf angegeben wurde, befindet sich außerhalb des reservierten Adressraums.
	EBADMSG	Zu lesende eingereihte Nachricht ist für I_PEEK ungültig.
	EINVAL	flags hat einen ungültigen Wert.
I_SRDOPT	Setzt die Einstellung für das Lesen (siehe read()) auf den Wert des Arguments arg. Zulässige Werte für arg sind:
	RNORM	Betriebsart „Bytestrom“ (Voreinstellung).
	RMSGD	Betriebsart „Nachricht verwerfen“.
	RMSGN	Betriebsart „Nachricht nicht verwerfen“.
	Ist der Wert für arg durch bitweises ODER von RMSGD und RMSGN entstanden, so führt dies zum Fehler EINVAL. Bitweises ODER von RNORM mit RMSGD ergibt RMSGN; bitweises ODER von RNORM mit RMSGN ergibt RMSGD. 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. 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. ioctl() mit dem I_SRDOPT-Kommando schlägt fehl, wenn gilt:
	EINVAL	arg hat keinen der oben genannten legalen Werte.
I_GRDOPT	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() beschrieben. ioctl() mit dem I_GRDOPT-Kommando schlägt fehl, wenn gilt:
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums.
I_NREAD	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 Nachrichten 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, dass die nächste Nachricht in der Queue die Länge 0 hat. ioctl() mit dem I_NREAD-Kommando schlägt fehl, wenn gilt
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums.
I_FDINSERT
	Erzeugt eine Nachricht aus benutzerdefinierten Puffern, fügt Informationen über einen anderen Stream hinzu und sendet die Nachricht stream-abwärts. Die Nachricht enthält einen Steuer- und einen optionalen Datenteil. Die zu sendenden Daten- und Steuerteile werden dadurch unterschieden, dass 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 ; Die len-Komponente in der strbuf-Struktur ctlbuf (siehe putmsg()) muss 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 den Dateideskriptor des anderen Streams an. offset muss auf Wortgrenze ausgerichtet sein und gibt die Anzahl der Bytes an, nach der I_FDINSERT 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 Struktur strfdinsert entspricht. Die len-Komponente in der strbuf-Struktur databuf muss 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 normale Nachricht wird erzeugt, wenn flags gleich 0 ist, eine Nachricht hoher Priorität wird erzeugt, wenn flags gleich RS_HIPRI ist. Bei normalen Nachrichten blockiert I_F-DINSERT, wenn die Schreib-Queue des Streams auf Grund der internen Flusskontrolle voll ist. Bei Nachrichten hoher Priorität blockiert I_FDINSERT in diesem Fall nicht. Bei normalen Nachrichten blockiert I_FDINSERT dann nicht, wenn die Schreib-Queue voll ist, aber O_NDELAY oder O_NONBLOCK gesetzt ist. Statt dessen schlägt der Aufruf fehl und errno ist dann gleich EAGAIN. I_FDINSERT blockiert auch, wenn der Aufruf auf die Verfügbarkeit von Nach-richten-Blöcken wartet und nicht durch ein Fehlen interner Betriebsmittel daran gehindert wird. Dabei ist es gleichgültig, welche Priorität gesetzt ist und ob O_N-DELAY oder O_NONBLOCK angegeben wurden. Es wird keine Teil-Nachricht gesendet. ioctl() mit dem I_FDINSERT-Kommando schlägt fehl, wenn gilt:
	EAGAIN	Es wurde ein Nachricht ohne Priorität angegeben, O_NDELAY oder O_NONBLOCK ist gesetzt und die Schreib-Queue des Streams ist auf Grund der internen Flusskontrolle voll.
	EAGAIN oder ENOSR
		Es konnten keine Puffer für die zu erzeugende Nachricht reserviert werden, da zu wenig Speicherplatz unter STREAMS verfügbar war.
	EINVAL	Es liegt einer der folgenden Gründe vor: fildes in der strfdinsert-Struktur ist kein gültiger offener Dateideskriptor für einen Stream. Die Größe eines Zeigers plus offset ist größer als die len-Komponente des Puffers, der durch ctlptr angegeben wurde. offset gibt keinen korrekt ausgerichteten Ort im Datenpuffer an. flags hat einen undefinierten 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 maximale und minimale Paketgröße des obersten Moduls im Stream festgelegt ist. Oder die len-Komponente für den durch databuf angegebenen Puffer ist größer als die konfigurierte 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.
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums oder der Pufferbereich, der in ctlbuf oder databuf angegeben wurde, befindet sich außerhalb des reservierten Adressraums.
	I_FDINSERT 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.
I_STR	Erzeugt eine interne ioctl-Nachricht aus den Daten, auf die arg zeigt und sendet diese Nachricht stream-abwärts. Dieser Mechanismus wird angeboten, um benutzerdefinierte ioctl()-Anfor-derungen stream-abwärts an Module und Treiber zu senden. Er erlaubt, dass Informationen mit dem ioctl() gesendet werden und liefert dem Benutzer alle Informationen zurück, die vom stream-abwärtigen Empfänger stream-aufwärts gesendet werden. I_STR 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 Aufruf mit errno gleich ETIME fehl. Es kann immer höchstens ein I_STR-Aufruf in einem Stream aktiv sein. Weitere I_STR -Aufrufe blockieren, bis der aktive I_STR-Aufruf sich am Stream-Kopf beendet. Die Voreinstellung für einen Timeout bei diesen Anforderungen beträgt 15 Sekunden. O_NDELAY und O_NONBLOCK (siehe open()) haben keinen Einfluss auf diesen Aufruf. Um Anforderungen stream-abwärts zu senden, muss arg auf eine strioctl-Struktur zeigen, die folgende Komponenten enthält: int ic_cmd ; int ic_timout ; int ic_len ; char * ic_dp ; ic_cmd ist das interne ioctl()-Kommando, das an ein stream-abwärts liegendes Modul oder einen Treiber gesendet werden soll und ic_timout ist die Zahl der Sekunden für ein Timeout (-1 = unendlich, 0 = Voreinstellung, > 0 = wie angegeben). ic_len ist die Anzahl der Bytes im Daten-Argument und ic_dp ist ein Zeiger auf das Daten-Argument. Die ic_len-Komponente besitzt zwei Verwendungen: bei der Eingabe enthält sie die Länge des übergebenen Daten-Arguments, bei der Rückkehr vom Kommando enthält sie die Anzahl der an den Benutzer zurückgelieferten Bytes (der Puffer, auf den ic_dp zeigt, sollte groß genug sein, die maximale Länge der 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 stream-abwärts. ioctl() mit dem I_STR-Kommando schlägt fehl, wenn gilt:
	EAGAIN oder ENOSR
		Auf Grund fehlenden Speicherplatzes konnte kein Puffer für die io ctl()-Nachricht reserviert werden.
	EINVAL	ic_len ist kleiner als 0, oder ic_len ist größer als die konfigurierte maximale Größe des Datenteils einer Nachricht, oder ic_timout ist kleiner als -1.
	ENXIO	Verbindungsabbruch wurde für fildes empfangen.
	ETIME	Ein stream-abwärtiger ioctl()-Aufruf erhielt ein Timeout, bevor eine Bestätigung empfangen wurde.
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums oder der Pufferbereich, der von ic_dp und ic_len angegeben wurde (getrennt für gesendete und empfangene Daten), befindet sich außerhalb des reservierten Adressraums.
	Ein I_STR-Aufruf kann auch dann fehlschlagen, wenn eine Fehler- oder Verbin-dungsabbruch-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, dass das ioctl-Kommando weiter stream-abwärts fehlschlägt. In diesem Fall besitzt errno den Wert aus der Nachricht.
I_SWROPT	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 stream-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.
	ioctl() mit dem I_SWROPT-Kommando schlägt fehl, wenn gilt:
	EINVAL	arg enthält nicht den oben angegebenen Wert.
I_GWROPT	Liefert die aktuell gültige Einstellung für das Schreiben in der int-Variablen zurück, auf die arg zeigt (siehe unter I_SWROPT).
I_SENDFD	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 ein offener Dateideskriptor sein muss. I_SENDFD 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 ebenfalls eingefügt. Diese Nachricht wird direkt in die Lese-Queue des Stream-Kopfs am anderen Ende der Pipe eingetragen. ioctl() mit dem I_SENDFD-Kommando schlägt fehl, wenn gilt:
	EAGAIN	Der sendende Stream ist nicht in der Lage, einen Nachrichten-Block zu reservieren, der den Dateizeiger aufnehmen kann, oder die Lese-Queue des empfangenden Stream-Kopfs ist voll und kann die von I_SENDFD gesendete Nachricht nicht aufnehmen.
	EBADF	arg ist kein gültiger, offener Dateideskriptor.
	EINVAL	fildes ist nicht mit einer Pipe verbunden.
	ENXIO	Verbindungsabbruch für fildes empfangen.
I_RECVFD	Ermittelt die Zuordnung zu einer offenen Dateibeschreibung einer Nachricht , die mit dem Kommando I_SENDFD für ioctl() über eine Pipe gesendet wurde und reserviert einen neuen Dateideskriptor im aufrufenden Prozess, der sich auf diese offene Dateibeschreibung bezieht. arg ist ein Zeiger auf einen Datenpuffer, der groß genug ist, eine strrecvfd-Datenstruktur aufzunehmen. Die Struktur strrecvfd ist in stropts.h definiert und enthält die folgenden Komponenten: int fd ; uid_t uid ; gid_t gid ; char fill[8] ; fd ist ein Dateideskriptor. uid und gid sind die Benutzer- und die Gruppennummer des sendenden Streams. Wenn O_NDELAY und O_NONBLOCK nicht gesetzt ist (siehe open()), dann blockiert I_RECVFD, bis eine Nachricht am Stream-Kopf vorhanden ist. Ist O_NDE LAY oder O_NONBLOCK gesetzt, so schlägt I_RECVFD 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 I_SENDFD gesendet wurde, dann wird ein neuer Benutzer-Dateideskriptor für den in der Nachricht enthaltenen Dateizeiger reserviert. Der neue Dateideskriptor wird in der fd-Komponente der strrecvfd-Struktur abgelegt. Die Struktur wird in den Datenpuffer des Benutzers kopiert, auf den arg zeigt. ioctl() mit dem I_RECVFD-Kommando schlägt fehl, wenn gilt:
	EAGAIN	Es befindet sich keine Nachricht in der Lese-Queue des Stream- Kopfs und O_NDELAY oder O_NONBLOCK ist gesetzt.
	EBADMSG	Die Nachricht in der Lese-Queue des Stream-Kopfs ist keine Nachricht, die einen übergebenen Dateideskriptor enthält.
	EMFILE	NOFILES Dateideskriptoren sind bereits geöffnet.
	ENXIO	Verbindungsabbruch für fildes empfangen.
	EOVERFLOW
		uid oder gid ist zu groß, um in der Struktur abgelegt werden zu können, auf die arg zeigt.
	EFAULT	arg zeigt auf einen Punkt außerhalb des reservierten Adressraums.
I_LIST	Erlaubt es einem Benutzer, alle Modulnamen im Stream auszugeben 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, genügend Platz für die Modulnamen zu reservieren. Ist arg ungleich NULL, dann sollte dieses Argument auf eine str_list-Struktur zeigen, die folgende Komponenten besitzt: int sl_nmods; struct str_mlist *sl_modlist; Die str_mlist-Struktur besitzt folgende Komponenten: char l_name[FMNAMESZ+1]; sl_nmods gibt die Anzahl der Einträge an, die der Benutzer im Vektor reserviert hat. Nach der Rückkehr enthält sl_modlist die Liste der Modulnamen und sl_nmods enthält die Anzahl der Einträge im Vektor sl_modlist, dies ist die Anzahl aller Module einschließlich des Treibers. Der Rückgabewert von ioctl() ist 0. Mit dem Schreiben der Einträge wird bei der Spitze des Streams begonnen und dann stream-abwärts fortgefahren, bis entweder das Ende des Streams oder die Anzahl der gewünschten Module (sl_nmods) erreicht ist. ioctl() mit dem I_LIST-Kommando schlägt fehl, wenn gilt:
	EINVAL	Die Komponente sl_nmods ist kleiner als 1.
	EAGAIN oder ENOSR
		Puffer konnte nicht reserviert werden.
I_ATMARK	Erlaubt es dem Benutzer zu überprüfen, ob die aktuelle Nachricht in der Lese-Queue des Stream-Kopfs von einem Modul weiter stream-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 die Nachricht markiert ist.
	LASTMARK	Prüfen, ob die Nachricht die letzte markierte 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: ioctl() mit dem I_ATMARK-Kommando schlägt fehl, wenn gilt:
	EINVAL	Der Wert von arg ist ungültig.
I_CKBAND	Prüft, ob eine Nachricht in einem gegebenen 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 Prioritätsbands enthält. ioctl() mit dem I_CKBAND-Kommando schlägt fehl, wenn gilt:
	EINVAL	Der Wert von arg ist ungültig.
I_GETBAND
	Liefert das Prioritätsband der ersten Nachricht in der Lese-Queue des Stream-Kopfs in dem ganzzahligen Wert zurück, auf den arg zeigt. ioctl() mit dem I_GETBAND-Kommando schlägt fehl, wenn gilt:
	ENODATA	Es befindet sich keine Nachricht in der Lese-Queue des Stream-Kopfs.
I_CANPUT	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 Flusskontrolle unterliegt, 1, wenn das Band beschreibbar ist oder -1 bei einem Fehler. ioctl() mit dem I_CANPUT-Kommando schlägt fehl, wenn gilt:
	EINVAL	Der Wert von arg ist ungültig.
I_SETCLTIME
	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 Sekunden. ioctl() mit dem I_SETCLTIME-Kommando schlägt fehl, wenn gilt:
	EINVAL	Der Wert von arg ist ungültig.
I_GETCLTIME
	Liefert die Wartezeit beim Schließen in der long-Variablen zurück, auf die arg zeigt.

Multiplex-Konfigurationen unter STREAMS

I_LINK	Verbindet zwei Datenströme, wobei fildes der Dateideskriptor des Streams ist, der mit dem Multiplex-Treiber verbunden ist und arg ist der Dateideskriptor des Streams, der mit einem anderen Treiber verbunden ist. Der Stream, der mit arg angegeben wird, wird unterhalb des Multiplex-Treibers verbunden. I_LINK erwartet, dass der Multiplex-Treiber eine Bestätigung an den Stream-Kopf sendet. Dieser Aufruf liefert eine Multiplexer-Kennzahl (diese Kennzahl wird für den Abbau des Multiplexers benötigt; siehe I_UNLINK) bei Erfolg und -1 bei einem Fehler. ioctl() mit dem I_LINK-Kommando schlägt fehl, wenn gilt:
	ENXIO	Verbindungsabbruch für fildes empfangen.
	ETIME	Timeout erfolgte, bevor die Bestätigung vom Stream-Kopf empfangen wurde.
	EAGAIN oder ENOSR
		Nicht genügend Speicher unter STREAMS verfügbar, um I_LINK ausführen zu können.
	EBADF	arg ist kein gültiger, offener Dateideskriptor.
	EINVAL	Einer der folgenden Fehler ist aufgetreten: Der fildes zugeordnete Stream unterstützt das Multiplexen nicht. arg ist kein Stream, oder bereits unter einem Multiplexer verbunden. Die angegebene Verbindung würde eine Schleife in der sich ergebenden Konfiguration erzeugen, d. h. ein gegebener Treiber ist in einer Multiplex-Konfiguration an mehr als einer Stelle vorhanden. fildes ist der Dateideskriptor einer Pipe oder FIFO-Datei.
	Die Operation I_LINK kann auch fehlschlagen, wenn sie darauf wartet, dass der Multiplex-Treiber die Verbindungsanforderung 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 I_LINK fehl, wobei errno gleich dem Wert in der Nachricht ist.
I_UNLINK	Löst die Verbindung zwischen den beiden durch fildes und arg angegebenen Datenströmen. fildes ist der Dateideskriptor des mit dem Multiplex-Treiber verbundenen Streams. arg ist die Multiplexer-Kennzahl, die von I_LINK zurückgeliefert wurde. Ist arg gleich MUXID_ALL, dann werden alle Datenströme abgehängt, die mit fildes verbunden waren. Ebenso wie I_LINK erwartet auch dieses Kommando, dass der Multiplex-Treiber die Auflösung der Verbindung bestätigt. ioctl() mit dem I_UNLINK-Kommando schlägt fehl, wenn gilt:
	ENXIO	Verbindungsabbruch für fildes empfangen.
	ETIME	Timeout erfolgte, bevor eine Bestätigung vom Stream-Kopf empfangen wurde.
	EAGAIN oder ENOSR
		Es kann nicht genügend Speicherplatz für die Bestätigung reserviert werden.
	EINVAL	arg ist keine gültige Multiplexer-Kennzahl oder fildes ist nicht der Stream, für den die I_LINK-Operation ausgeführt wurde, die arg geliefert hat.
	EINVAL	fildes ist der Dateideskriptor einer Pipe oder FIFO-Datei.
	Die Operation I_UNLINK kann auch fehlschlagen, wenn sie darauf wartet, dass der Multiplex-Treiber die Verbindungsanforderung 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 I_UNLINK fehl, wobei errno gleich dem Wert in der Nachricht ist.
I_PLINK	Verbindet zwei Datenströme, wobei fildes der Dateideskriptor des Streams ist, der mit dem Multiplex-Treiber verbunden ist und arg ist der Dateideskriptor 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. Dieser Aufruf erzeugt einen ständigen Verweis, der auch dann existieren kann, wenn der Dateideskriptor fildes, der dem oberen Stream zum Multiplex-Treiber zugeordnet ist, geschlossen wird. I_PLINK erwartet, dass der Multiplex-Treiber eine Bestätigung an den Stream-Kopf sendet. Dieser Aufruf liefert eine Multiplexer-Kennzahl (diese Kennzahl wird für den Abbau des Multiplexers benötigt; siehe I_PUNLINK) bei Erfolg und -1 bei Fehler. ioctl() mit dem I_PLINK-Kommando schlägt fehl, wenn gilt:
	ENXIO	Verbindungsabbruch für fildes empfangen.
	ETIME	Timeout erfolgte, bevor eine Bestätigung vom Stream-Kopf empfangen wurde.
	EAGAIN oder ENOSR
		Nicht genügend Speicher unter STREAMS verfügbar, um I_PLINK ausführen zu können.
	EBADF	arg ist kein gültiger, offener Dateideskriptor.
	EINVAL	Einer der folgenden Fehler ist aufgetreten: Der fildes zugeordnete Stream unterstützt das Multiplexen nicht. arg ist kein Stream oder bereits unter einem Multiplexer angehängt. Die angegebene Verbindung würde eine Schleife in der sich ergebenden Konfiguration erzeugen, d. h. ein gegebener Treiber ist in einer Multiplex-Konfiguration an mehr als einer Stelle vorhanden. fildes ist der Dateideskriptor einer Pipe oder FIFO-Datei.
	Die Operation I_PLINK kann auch fehlschlagen, wenn sie darauf wartet, dass der Multiplex-Treiber die Verbindungsanforderung 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 I_PLINK fehl, wobei errno gleich dem Wert in der Nachricht ist.
I_PUNLINK
	Löst die ständige Verbindung zwischen den beiden durch fildes und arg angegebenen Datenströmen. fildes ist der Dateideskriptor des mit dem Multiplex-Treiber verbundenen Streams. arg ist die Multiplexer-Kennzahl, die von I_-PLINK zurückgeliefert worden ist, als ein Stream unter dem Multiplex-Treiber eingehängt wurde. Ist arg gleich MUXID_ALL, dann werden alle Datenströme abgehängt, die mit fildes über ständige Verweise verbunden waren. Ebenso wie I_PLINK erwartet auch dieses Kommando, dass der Multiplex-Treiber die Auflösung der Verbindung bestätigt. ioctl() mit dem I_PUNLINK-Kommando schlägt fehl, wenn gilt:
	ENXIO	Verbindungsabbruch für fildes empfangen.
	ETIME	Timeout erfolgte, bevor eine Bestätigung vom Stream-Kopf empfangen wurde.
	EAGAIN oder ENOSR
		Puffer für die Bestätigung konnte nicht reserviert werden.
	EINVAL	Ungültige Multiplexer-Kennzahl.
	EINVAL	fildes ist der Dateideskriptor einer Pipe oder FIFO-Datei.
	Die Operation I_PUNLINK kann auch fehlschlagen, wenn sie darauf wartet, dass 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 I_PUNLINK fehl, wobei errno gleich dem Wert in der Nachricht ist.

Returnwert

nicht negative ganze Zahl

bei Erfolg. Der zurückgegebene Wert hängt jeweils von der Geräte-Steuerfunktion ab.

-1

bei Fehler. errno wird gesetzt, um den Fehler anzuzeigen.

Fehler

ioctl() ist bei jedem Dateityp erfolglos, wenn einer oder mehrere der nachstehenden Punkte zutreffen:

 

EBADF

fildes ist kein gültiger offener Dateideskriptor.

 

EINTR

Ein Signal wurde während des Systemaufrufs ioctl() abgefangen.

 

EINVAL

Der mit fildes bezeichnete Stream oder Multiplexer ist (direkt oder indirekt) unter einem Multiplexer eingehängt.

 

ioctl() ist außerdem erfolglos, wenn der Gerätetreiber einen Fehler feststellt. In diesem Fall wird der Fehler durch ioctl() ohne Änderung an den Aufrufer weitergeleitet. Nicht alle nachstehenden Fehlerfälle können bei jedem Treiber auftreten: 

 

EINVAL

request oder arg sind für dieses Gerät nicht gültig.

 

EIO

Ein physikalischer E/A-Fehler ist aufgetreten.

 

ENOTTY

fildes bezeichnet keinen Gerätetreiber/keine STREAMS-Datei, der/die
Steuerfunktionen akzeptiert.

 

ENXIO

request und arg sind für diesen Gerätetreiber gültig, jedoch kann der angeforderte Dienst nicht auf diesem Gerät ausgeführt werden.

 

ENODEV

fildes bezeichnet eine gültige STREAMS-Datei, aber der zugehörige Gerätetreiber unterstützt die Funktion ioctl() nicht.

 

ENOLINK

fildes befindet sich auf einem fernen Rechner, und die Verbindung zu diesem Rechner ist nicht mehr aktiv.

 

EFAULT

request fordert eine Datenübertragung auf einen bzw. von einem Puffer, auf den arg zeigt, wobei jedoch ein Teil des Puffers außerhalb des dem Prozess zugewiesenen Adressraums liegt.

 

Wenn ein Stream unter einem Multiplexer eingehängt ist, führt jedes ioctl()-Kommando außer I_UNLINK und I_PUNLINK zum Fehler EINVAL.

Siehe auch

streamio() in „Leitfaden für Programmierer: STREAMS“, termio() in „Referenzhandbuch für Systemverwalter“, close(), fcntl(), getmsg(), open(), pipe(), poll(), putmsg(), read(), sigaction(), write(), stropts.h.