C standard library :: unistd

read - Læs fra en fil

ssize_t read(int fd, void *buf, size_t nbyte)

^[XSI]

ssize_t pread(int fd, void *buf, size_t nbyte, off_t offset)

Denne funktion læser nbyte fra en fil associeret med den åbne file descriptor til bufferen udpeget af buf. Udslaget af samtidige processer der læser på den samme pipe, FIFO eller terminal enhed er uvist.

Før nogen handling beskrevet nedenfor har fundet sted og hvis nbyte er nul, vil read() funktionen muligvis detektere og returnere fejl. I fravær af fejl eller hvis fejl detektion ikke udføres, vil read() funktionen returnere nul og ikke have andre resultater.

På filer som supporterer søgning (f.eks. en almindelig fil), skal read() starte på positionen i den fil på offset associeret med fd. Offset vil blive øget med antallet af bytes læst.

Filer der ikke supporterer søgning, f.eks terminaler, vil altid læse fra aktuel position. Værdi af file offset associeret med en sådan fil er ikke defineret.

Ingen data overføres efter aktuel end-of-file. Hvis startpositionen er ved eller efter end-of-file, returneres 0. Hvis filen refererer til en device speciel fil er resultatet af efterfølgende read() forespørgsler defineret i implementeringen.

Hvis værdien af nbyte er større end (SSIZE_MAX) er resultatet defineret i implementeringen.

Ved forsøg på at læse fra en tom pipe eller FIFO:

Hvis ingen process ejer den åbne pipe for skrivning skal read() returnere 0 til identikation af end-of-file.
Hvis en process har en pipe åben for skrivning og O_NONBLOCK er sat, skal read() returnerer -1 og sætte errno til [EAGAIN].
Hvis en process har en pipe åben for skrivning og O_NONBLOCK er clear, skal read() blokere den kalende process indtil data er skrevet til eller pipe'n er lukket af alle processer der har pipe'n åben for skrivning.

Ved forsøg på at læse fra en fil (ikke pipe eller FIFO) som supporterer non-blocking læsninger, men som ikke har nogle data klar:

Hvis O_NONBLOCK er sat, skal read() returnere -1 og sætte errno til [EAGAIN].
Hvis O_NONBLOCK er clear, skal read() blokere for kalende tråde indtil data bliver tilgængelige.
Brugen af O_NONBLOCK har ingen effekt hvis data er tilgængelige.

Funktionen read() læser data tidligere skrevet til en fil. Hvis en del af en almindelig fil forud for end-of-file ikke er skrevet, skal read() returnere bytes med værdien 0. For eksempel, lseek() tillader filens offset at sættes udover enden af filens eksisterende data. Hvis data senere bliver skrevet til dette punkt, efterfølgende læsninger i mellemrummet mellem den tidligere ende af data og de nyligen skrevne data skal returnere bytes med værdien 0 indtil data er skrevet ind i mellemrummet.

Ved succesfuld læsning, hvor nbyte er større end 0, skal read() tidsstemple st_atime feltet på filen og returnere antallet af bytes læst. Dette antal vil aldrig overstige nbyte. Værdien kan være mindre end nbyte, hvis read() forespørgslen blev afbrudt af et signal eller hvis en fil er en pipe eller FIFO eller speciel-fil og har færre end nbyte bytes tilgægelig for læsning. F.eks. en read() fra en fil associeret med en terminal kan returnere en linie af data.

Hvis read() bliver afbrudt af et signal før den læser data, skal den returnere -1 med errno sat til [EINTR].

Hvis read() bliver afbrudt af et signal efter den har fuldført læsning af nogle data, skal den returnere det antal der blev læst.

For en almindelig fil vil ingen data overførsel finde sted udover der offset maksimum etableret i file description associeret med fd.

Hvis fd refererer til en socket, skal read() være det samme som recv() uden flag sat.

^[SIO] Hvis O_SYNC og O_RSYNC bittene er sat, vil læse I/O operationer på file descriptor udføres som defineret i synkroniseret I/O handlinger.

^[SHM] Hvis fd refererer til en Shared Memory Object vil resultatet af read() funktionen være uvist.

^[TYM] Hvis fd refererer til en Shared Memory Object vil resultatet af read() funktionen være uvist.

^[XSR] En read() fra en STREAMS fil kan læse data i tre forskellige modes: byte-stream mode, message-nondiscard mode og message-discard mode. Standard er byte-stream mode. Denne kan ændres ved at bruge I_SRDOPT ioctl() forespørgsler og kan testes med I_GRDOPT ioctl(). I byte-stream mode skal read() hente data fra STREAM indtil antallet af bytes ønsker er overført eller indtil der ikke er flere data at hente. Byte-stream mode ignorerer message grænser.

I STREAMS message-nondiscard mode skal read() hente data indtil antallet af byte ønsker er overført eller indtil en message grænse er nået. Hvis read() ikke henter alle data i en message vil de tilbageværende blive efterladt på STREAM og kan hentes af den næste read() kald. Message-discard mode henter også data indtil antallet ønsket er overført eller en message grænse er nået. Hvor om alt er, ulæste data i en message efter read() returnerer vil blive fjernet og er ikke tilgængelig for en efterfølgende read(), getmsg() eller getpmsg() kald.

Hvordan read() håndterer nul-byte STREAMS messages er bestemt af aktuel read-mode opsætning. I byte-stream mode skal read() acceptere data indtil den har læst nbyte bytes eller indtil der ikke er flere data at læse eller indtil en nul-byte message blok mødes. Funktionen read() skal returnere antallet af bytes læst og placere den nul-byte message tilbage til STREAM for at blive hentet af den næste read(), getmsg() eller getpmsg(). I message-nondiscard mode eller message-discard mode skal en nul-byte message returnere 0 og den message vil fjernes fra STREAM. Når en nul-byte message er læst som den første message på en STREAM skal den message blive fjernet fra den STREAM og 0 vil returneres uanset af mode.

En read() fra en STREAM file skal returnere data i en message som den første af en STREAM head læse kø, uanset af hvordan message er knyttet af priotiteten.

Som standard, er STREAMSs i control-normal mode i hvilken en read() fra en STREAM fil kun kan bearbejde message som indeholder data dele som ikke indeholder en kontrol del. Den read() vil fejle hvis en message indeholdende en kontrol del forekommer i den STREAM head. Standard handlingen kan ændres ved at placere den STREAM i enten control-data mode eller control-discard mode med I_SRDOPT ioctl() kommandoen. I control-data mode skal read() konvertere en kontrol del til data og lade den passere til applikationen før den lader data passere som oprindelig hører sammen med den samme message. I control-discard mode skal read() fjerne message kontrol delen og kun returnere data delen i den message.

I tillæg skal read() fejle hvis STREAM head har behandlet en asynkron fejl før kaldet. I det tilfælde vil værdien af errno ikke reflektere resultatet af read(), men reflektere den forrige fejl. Hvis en afbrydelse finder sted på en STREAM som læses, skal read() fortsætte med at operere normalt indtil STREAM head læse køen er tom. Derefter returneres 0.

Return værdi

Ved succes returneres antallet af bytes læst ellers -1 og errno bliver sat med årsag til fejlen.

Fejl

Funktionen read() vil fejle hvis:

[EAGAIN]: Flaget O_NONBLOCK er sat for file descriptor og tråden vil forsinkes.
[EBADF]: Parameteren fd er ikke en valid file descriptor åben for læsning.
[EBADMSG]: ^[XSR] Filen er en STREAM fil som er sat til control-normal mode og meddelelsen ventende på at blive læst inkluderer en kontrol del.
[EINTR]: Læseoperationen blev termineret ved modtagelsen af et signal og ingen data er overført.
[EINVAL]: ^[XSR] Den STREAM eller multiplexer refereret af fd er kædet (direkte eller indirekte) til downstream fra en multiplexer.
[EIO]: Processen er medlem af en baggrunds process som forsøger at læse fra den terminal der er i kontrol, processen ignorerer eller blokerer SIGTTIN signalet, eller process group er uden parent. Fejlen kan også hidrøre fra implementeringen.
[EISDIR]: ^[XSI] Parameteren filedes refererer til en mappe og implementeringen tillader ikke denne mappe at blive læst gennem read() eller pread(). Funktionen readdir() bør anvendes istedet.
[EOVERFLOW]: Filen er en almindelig fil, nbyte er større en 0, startpositionen er før end-of-file og startpositionen er større end eller lig med det offset maksimum etableret i den åbne file descriptor associeret med fd.

Funktionen read() vil fejle hvis:

[EAGAIN] eller [EWOULDBLOCK]: File descriptor for en socket er markeret O_NONBLOCK og der er ingen data klar til modtagelse.
[ECONNRESET]: En læsning forsøgt på en socket hvor forbindelsen var forceret lukket af modparten.
[ENOTCONN]: En læsning forsøgt på en socket som ikke er forbundet.
[ETIMEDOUT]: En læsning forsøgt på en socket og transmissionen fik timeout.

Funktionen read() og ^[XSI] pread() vil fejle hvis:

[EIO]: Der er en fysisk I/O fejl.
[ENOBUFS]: Utilstrækkelige ressourcer tilgængelige for systemer til at udføre handlingen.
[ENOMEM]: Utilstrækkelig memory til at gennemføre forespørgsel.
[ENXIO]: En forespørgsel til en ikke eksisterende device eller en forespørgsel udenfor mulighederne for en device.

Funktionen pread() vil fejle og fil pegeren forbliver uændret hvis:

[EINVAL]: ^[XSI] Parameteren offset er invalid. Værdien er negativ.
[EOVERFLOW]: ^[XSI] Filen er en almindelig fil og et forsøg på at læse udover maksimum grænsen for offset associeret med filen.
[ENXIO]: ^[XSI] En forespørgsel var udenfor mulighederne for en device.
[ESPIPE]: ^[XSI] fd er associeret med en pipe eller FIFO.

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