C standard library :: stropts

ioctl - kontrol på STREAMS device

^[XSR]

int ioctl (int fd, unsigned long int request, ../* arg */..)

Denne funktion udfører en mængde kontrol funktioner på STREAMS devices. For non-STREAM devices er kald til funktionen uvist. Parameteren request og en optionel tredie parameter (med forskellige typer) skal medtages og fortolkes af den tilhørende del af den STREAM associeret med fd.

Parameteren fd er en åben file descriptor som refererer til en device.

Parameteret request udvælger en kontrolfunktion at udføre og skal afhænge af den STREAMS der adresseres.

Parameteren arg præsenterer ekstra informationer som behøves af denne specifikke STREAMS device i at udføre den ønskede kontrolfunktion. Typen af arg afhænger af den bestemte kontrolforespørgsel, men den skal enten være et heltal eller en peger til en af device'n afhængig datastruktur.

Kommandoer med ioctl() til STREAMS, deres parametre og fejl muligheder til hver enkelt kommando er beskrevet nedenstående.

Følgende ioctl() kommandoer med fejlværdier vist er gældende for alle STREAMS filer:

I_PUSH

Skubber ind modulet hvis navn er udpeget af arg på toppen af den aktuelle STREAM lige under STREAM head. Den kalder derefter funktionen open() til det nye indskubbede modul.

Funktionen ioctl() med I_PUSH kommandoen vil fejle hvis:

[EINVAL]: Invalid modul navn.
[ENXIO]: Open funktionen til det nye modul fejlede.
[ENXIO]: Afbrydelse modtaget på fd.

I_POP

Skubber ud modulet lige under STREAM head udpeget af fd. Parameteren arg skal være 0.

Funktionen ioctl() med I_POP kommandoen vil fejle hvis:

[EINVAL]: Der er ikke noget modul i STREAM.
[ENXIO]: Afbrydelse modtaget på fd.

I_LOOK

Henter navnet på modulet lige under STREAM head på den STREAM udpeget af fd og placerer det i en streng udpeget af arg. Bufferen udpeget af arg bør være mindst FMNAMESZ+1 bytes lang, hvor FMNAMESZ er defineret i <stropts.h>.

Funktionen ioctl() med I_LOOK kommandoen vil fejle hvis:

[EINVAL]: Der er ikke noget modul i STREAM.

I_FLUSH

Nulstiller læse og/eller skrive køer afhængig af værdien på arg. Korrekte værdier af arg er:

FLUSHR: Nulstil alle læse køer.
FLUSHW: Nulstil alle skrive køer.
FLUSHRW: Nulstil alle læse og skrive køer.

Funktionen ioctl() med I_FLUSH kommandoen vil fejle hvis:

[EINVAL]: Invalid arg værdi.
[EAGAIN] eller [ENOSR]: Kan ikke allokere buffere for flush-message.
[ENXIO]: Afbrydelse modtaget på fd.

I_FLUSHBAND

Nulstiller et bestemt band af messages. Parameteren arg peger på en bandinfo struktur. Medlemmet bi_flag kan være en af FLUSHR, FLUSHW eller FLUSHRW. Medlemmet bi_pri bestemmer prioritetsband der skal nulstilles.

I_SETSIG

Beder til at STREAMS sender SIGPOLL signalet til den kaldende process når en bestemt hændelse indtræder på den STREAM associeret med fd. I_SETSIG supporterer en asynkron behandlings metode i STREAMS. Værdien af arg er en bitmaske som anviger hændelsen for hvilken processen skal signaleres. Det er en bitmaske der med OR kan kombineres af følgende konstanter:

S_RDNORM: En normal (prioritetsband sat til 0) message er ankommet til starten af en STREAM head læse kø. Et signal skal genereres selvom message er nul i længden.
S_RDBAND: En message med ikke-nul prioritet er ankommet til starten af en STREAM head læse kø. Et signal skal genereres selvom message er nul i længden.
S_INPUT: En message, der ikke er højprioriteret, er ankommet til starten af en STREAM head læse kø. Et signal skal genereres selvom message er nul i længden.
S_HIPRI: En højt prioriteret message er ankommet til starten af en STREAM head læse kø. Et signal skal genereres selvom message er nul i længden.
S_OUTPUT: Skrive køen for normal data (prioritetsband 0) lige under en STREAM head er ikke længere fuld. Det anviser for processen, at der er plads i køen for at sende (eller skrive) normal data downstream.
S_WRNORM: Se S_OUTPUT.
S_WRBAND: Skrive køen for en ikke-nul prioritetsband lige under en STREAM head er ikke længere fuld. Det anviser for processen, at der er plads i køen for at sende (eller skrive) prioriterede data downstream.
S_MSG: Et STREAM signal message som indeholder SIGPOLL signalet er nået forrest i STREAM head læse køen.
S_ERROR: Anmeldelsen af en fejl tilstand er nået til STREAM head.
S_HANGUP: Anmeldelsen af en afbrydelse er nået til STREAM head.
S_BANDURG: Når den bruges i forbindelse med S_RDBAND, SIGURG er genereret i stedet for SIGPOLL når en prioriteret message når forrest i STREAM head læse køen.

Hvis arg er 0 skal den kalende process afmeldes og skal ikke modtage flere SIGPOLL signaler for den stream associeret med fd.

Processer som ønsker at modtage SIGPOLL signaler skal sikre at de klart tilmeldes til at modtage dem ved brug af I_SETSIG. Hvis flere processer tilmeldet for at modtage dette signal for den samme hændelse på den samme STREAM, vil hver process blive signaleret når hændelsen optræder.

Funktionen ioctl() med I_SETSIG kommandoen vil fejle hvis:

[EINVAL]: Invalid arg værdi.
[EINVAL]: Værdien af arg er o og den kalende process er ikke anmeldt til at modtage SIGPOLL signalet.
[EAGAIN]: Der er utilstrækkelige ressourcer til at gemme signal forespørgslen.

I_GETSIG

Returnerer den hændelse for hvilken den kalende process fornærværende er anmeldt til få sendt et SIGPOLL signal. Hændelsen er returneret som en bitmaske i en int udpeget af arg, hvor hændelsen er af de specificeret i beskrivelsen til I_SETSIG ovenfor.

Funktionen ioctl() med I_GETSIG kommandoen vil fejle hvis:

[EINVAL]: Processen er ikke anmeldt til at modtage SIGPOLL signalet.

I_FIND

Sammenligner navnene af alle moduler aktuelt tilstede i STREAM med navnet udpeget af arg og returnerer 1 hvis modulnavnet er tilstede eller 0 hvis det ikke findes.

Funktionen ioctl() med I_FIND kommandoen vil fejle hvis:

[EINVAL]: arg har ikke et valid modulnavn.

I_PEEK

Modtager informationer i den første message på STREAM head læse køen uden at tage den message af køen. Den er analog til getmsg() bort set fra at denne kommando ikke fjerner message fra køen. Parameteren arg peger på en strpeek struktur.

Det er applikationen der skal sikre at maxlen, medlem i strukturen strbuf som findes i to medlemmer ctlbuf og databuf, er sat til antallet af bytes som kontrollerer informationen og/eller data information der modtages. Medlemmet flags kan markere RS_HIPRI eller 0 som beskrevet af getmsg(). Hvis processen sætter flags til RS_HIPRI, for eksempel, vil I_PEEK kun søge efter højt prioriterede message på STREAM head læse kø.

I_PEEK returnerer 1 hvis en message blev modtaget og 0 hvis ingen message blev fundet på STREAM head læse køen, eller hvis RS_HIPRI flaget var sat i flags og der ikke var nogen højt prioriterede message på STREAM head læse køen. Den venter ikke efter en message skal ankomme. Efter udførelse, vil ctlbuf angive information i kontrolbufferen og databuf angive informationer i data bufferen og flags indeholder værdien RS_HIPRI eller 0.

I_SRDOPT

Sætter read mode ved brug af værdier i parameteren arg. Read modes er beskrevet i read(). Flags i arg kan være:

RNORM: Byte-stream mode, standard.
RMSGD: Message-discard mode.
RMSGN: Message-nondiscard mode.

Bitmønsteret med OR af RMSGD og RMSGN skal returnere [EINVAL]. Bitmønsteret med OR af RNORM og enter RMSGD eller RMSGN skal resultere i andre flag overskriver RNORM hvilket er standard.

I tillæg behandlingen af kontrol messages af STREAM head kan ændres ved at sætte en af følgende flag i arg:

RPROTNORM: Lad read() fejle med [EBADMSG] hvis en message indeholder en kontrol del der er i front af STREAM head læse køen.
RPROTDAT: Levér en kontrol del af en message som data når en process kalder en read().
RPROTDIS: Fjern kontrol delen af en message og levér data delen når en process kalder en read().

Funktionen ioctl() med I_SRDOPT kommandoen vil fejle hvis:

[EINVAL]: Invalid arg værdi.

I_GRDOPT

Returnerer aktuel read mode indstilling, som beskrevet overfor, i en int peger i parameteren arg. Read modes er beskrevet i read().

I_NREAD

Tæller antallet af byte i data delen på den første message i STREAM head læse køen og placerer værdien i en int peger i parameteren arg. Returværdien for kommandoen skal være antallet af message i STREAM head læse køen. For eksempel, hvis 0 er returneret til arg, medens ioctl() returværdien er større end 0, betyder der at en nul-længde message er næst i køen.

I_FDINSERT

Kreerer en message fra specificeret buffer(e), tillægger information om en anden STREAM, og sender den message downstream. Denne message indeholder en kontrol del og en valgfri data del. Data og kontrol delen der skal sendes er adskildt gennem placering i seperate buffere som beskrevet nedenstående. Parameteren arg peger på strfdinsert strukturen.

Applikationen skal sikre at len, medlem i strukturen strbuf som findes i to medlemmer ctlbuf og databuf, er sat til størrelsen af en t_uscalar_t plus antallet af bytes af kontrol informationer der skal sendes med denne message. Medlemmet fildes angiver file descriptor på den anden STREAM og medlemmet offset skal have et passende forhold for brugen af en t_uscalar_t, specificerer offsettet fra starten af kontrolbufferen hvor I_FDINSERT skal gemme en t_uscalar_t hvis tolkning er specifik til STREAM enden. Applikationen skal sikre at len medlemmet i databuf strbuf strukturen er sat til antallet af bytes af data information der skal sendes med message eller til 0 hvis ingen data del skal sendes.

Medlemmet flags angiver typen af message der skal dannes. En normal message kreeres hvis flags er sat til 0 og en højpriotiteres message er kreeret hvis flags er sat til RS_HIPRI. For ikke-priotets messages, I_FDINSERT vil blokere hvis STREAM skrive køen er fuld. For prioriterede message, blokkerer I_FDINSERT ikke ved sådanne omstændigheder. For ikke-priotets messages, I_FDINSERT vil blokere ikke hvis STREAM skrive køen er fuld og O_NONBLOCK er sat. Derimod fejler kommandoen og sætter errno til [EAGAIN].

I_FDINSERT blokkerer også, med mindre det forhindres som udslag på mangel af ressourcer, ventende på tilgængeligheden af message blokke i STREAM uanset prioritet eller om O_NONBLOCK er angivet. Ingen message del er sendt.

Return værdi

Ved succes vil ioctl() returnere en værdi forskellig fra -1, det afhænger af den STREAM device kontrolfunktioner. Ellers returneres -1 og errno bliver sat med årsag til fejlen.

Fejl

1 2 3 4 5 6 7 8 9 Næste side »