write(2)

NUME
write - scrie într-un descriptor de fișier

BIBLIOTECA
Biblioteca C standard (libc, -lc)

SINOPSIS
#include <unistd.h>

ssize_t write(size_t count;
              int fd, const void buf[count], size_t count);

DESCRIERE
write() scrie până la count octeți din memoria tampon care începe la buf în fișierul la care se face referire prin descriptorul de fișier fd.

Numărul de octeți scriși poate fi mai mic decât count dacă, de exemplu, nu există spațiu suficient pe suportul fizic subiacent, dacă este întâlnită limita de resurse RLIMIT_FSIZE (a se vedea setrlimit(2)) sau dacă apelul a fost întrerupt de un gestionar de semnal după ce a scris mai puțin de count octeți. A se vedea și pipe(7).

Pentru un fișier care poate fi căutat (adică unul căruia i se poate aplica lseek(2), de exemplu, un fișier obișnuit), scrierea are loc la poziția fișierului, iar poziția fișierului este incrementată cu numărul de octeți scriși efectiv. În cazul în care fișierul a fost deschis cu open(2) O_APPEND, poziția fișierului este mai întâi stabilită la sfârșitul fișierului înainte de scriere. Ajustarea decalajului fișierului și operația de scriere sunt efectuate ca un pas atomic.

POSIX stipulează că un read(2) despre care se poate dovedi că apare după ce un write() a fost returnat va returna noile date. Rețineți că nu toate sistemele de fișiere sunt conforme cu POSIX.

În conformitate cu POSIX.1, dacă count este mai mare decât SSIZE_MAX, rezultatul este definit de implementare; a se vedea NOTE pentru limita superioară în Linux.

VALOAREA RETURNATĂ
În caz de succes, este returnat numărul de octeți scriși. În caz de eroare, este returnat -1, iar errno este configurată pentru a indica eroarea.

Rețineți că o operație write() reușită poate transfera mai puțin de count octeți. Astfel de scrieri parțiale pot avea loc din diverse motive; de exemplu, pentru că nu a existat spațiu suficient pe dispozitivul de disc pentru a scrie toți octeții solicitați sau pentru că un apel write() blocat către un soclu, conductă sau similar a fost întrerupt de un gestionar de semnal după ce a transferat o parte, dar înainte de a transfera toți octeții solicitați. În cazul unei scrierii parțiale, apelantul poate efectua un alt apel write() pentru a transfera octeții rămași. Apelul ulterior fie va transfera alți octeți, fie poate duce la o eroare (de exemplu, dacă discul este acum plin).

Dacă count este zero și fd se referă la un fișier obișnuit, atunci write() poate returna o stare de eșec dacă este detectată una dintre erorile de mai jos. Dacă nu sunt detectate erori sau dacă detectarea erorilor nu este efectuată, se returnează 0 fără a provoca alte efecte. Dacă count este zero și fd se referă la un alt fișier decât un fișier obișnuit, rezultatele nu sunt specificate.

ERORI-IEȘIRE

EAGAIN
    Descriptorul de fișier fd se referă la un alt fișier decât un soclu și a fost marcat ca fiind fără blocare (O_NONBLOCK), iar scrierea s-ar bloca. Consultați open(2) pentru mai multe detalii privind marcajul O_NONBLOCK.

EAGAIN sau EWOULDBLOCK
    Descriptorul de fișier fd se referă la un soclu și a fost marcat ca fiind fără blocare (O_NONBLOCK), iar scrierea s-ar bloca. POSIX.1-2001 permite returnarea oricărei erori în acest caz și nu solicită ca aceste constante să aibă aceeași valoare, astfel încât o aplicație portabilă ar trebui să verifice ambele posibilități.

EBADF
    fd nu este un descriptor de fișier valid sau nu este deschis pentru scriere.

EDESTADDRREQ
    fd se referă la o priză de datagramă pentru care nu a fost definită o adresă de mașină partener folosind connect(2).

EDQUOT
    Cota utilizatorului de blocuri de disc pe sistemul de fișiere care conține fișierul menționat de fd a fost epuizată.

EFAULT
    buf se află în afara spațiului dvs. de adrese accesibil.

EFBIG
    S-a încercat scrierea unui fișier care depășește dimensiunea maximă a fișierului definită de implementare sau limita de dimensiune a fișierului procesului sau scrierea la o poziție care depășește decalajul maxim permis.

EINTR
    Apelul a fost întrerupt de un semnal înainte ca orice date să fie scrise; a se vedea signal(7).

EINVAL
    fd este atașat unui obiect care nu este adecvat pentru scriere; sau fișierul a fost deschis cu fanionul O_DIRECT, iar adresa specificată în buf, valoarea specificată în count sau poziția fișierului nu este aliniată corespunzător.

EIO S-a produs o eroare I/O de nivel scăzut în timpul modificării nodului-i. Această eroare poate fi legată de scrierea înapoi (write-back) a datelor scrise de o operație write() anterioară, care poate să fi fost emisă către un descriptor de fișier diferit pe același fișier. Începând cu Linux 4.13, erorile de la write-back vin cu promisiunea că acestea pot fi raportate de următoarele. write(), și will să fie raportate de o cerere ulterioară fsync(2) (indiferent dacă au fost sau nu raportate și de write()). O altă cauză a EIO pe sistemele de fișiere în rețea este atunci când un blocaj consultativ a fost luat pe descriptorul de fișier și acest blocaj a fost pierdut. Consultați secțiunea Blocări pierdute din fcntl(2) pentru detalii suplimentare.

ENOSPC
    Dispozitivul care conține fișierul la care se face referire prin fd nu are spațiu pentru date.

EPERM
    Operația a fost împiedicată de o sigilare de fișier; a se vedea fcntl(2).

EPIPE
    fd este conectat la o conductă sau un soclu al cărui capăt de citire este închis. Atunci când acest lucru se întâmplă, procesul de scriere va primi și un semnal SIGPIPE; (astfel, valoarea de returnare a scrierii este văzută numai dacă programul captează, blochează sau ignoră acest semnal).

Pot apărea și alte erori, în funcție de obiectul conectat la fd.

STANDARDE
POSIX.1-2024.

ISTORIC
SVr4, 4.3BSD, POSIX.1-2001.

Sub SVr4, o scriere poate fi întreruptă și se poate returna EINTR în orice moment, nu doar înainte ca datele să fie scrise.

NOTE
O returnare cu succes de la write() nu garantează în niciun fel că datele au fost stocate pe disc. Pe unele sisteme de fișiere, inclusiv NFS, nu garantează nici măcar că spațiul a fost rezervat cu succes pentru date. În acest caz, unele erori pot fi amânate până la o viitoare operație write(), fsync(2) sau chiar close(2). Singura modalitate de a fi siguri este să apelați fsync(2) după ce ați terminat de scris toate datele.

Dacă o operație write() este întreruptă de un gestionar de semnal înainte de scrierea oricărui octet, apelul eșuează cu eroarea EINTR; dacă este întrerupt după scrierea a cel puțin un octet, apelul reușește și returnează numărul de octeți scriși.

Pe Linux, write() (și apelurile de sistem similare) va transfera cel mult 0x7ffff000 (2.147.479.552) octeți, returnând numărul de octeți transferați efectiv;(acest lucru este valabil atât pe sistemele pe 32 de biți, cât și pe cele pe 64 de biți).

O valoare returnată de eroare în timpul executării write() folosind I/O direct nu înseamnă că întreaga scriere a eșuat. Se pot scrie date parțiale, iar datele de la poziția fișierului pe care s-a încercat write() trebuie considerate inconsistente.

ERORI
În conformitate cu POSIX.1-2008/SUSv4 secțiunea XSI 2.9.7 („Interacțiuni ale firelor de execuție cu operațiile fișierelor obișnuite”):

    Toate funcțiile următoare trebuie să fie atomice una față de cealaltă în efectele specificate în POSIX.1-2008 atunci când operează cu fișiere obișnuite sau legături simbolice: ...

Printre API-urile enumerate ulterior sunt write() și writev(2). Iar printre efectele care ar trebui să fie atomice între fire (și procese) se numără actualizările poziției fișierului. Cu toate acestea, înainte de Linux 3.14, acest lucru nu se întâmpla: dacă două procese care împart o descriere de fișier deschis (a se vedea open(2)) efectuează o operație write() (sau writev(2)) în același timp, atunci operațiile I/O nu erau atomice în ceea ce privește actualizarea poziției fișierului, având ca rezultat suprapunerea (incorectă) a blocurilor de date emise de cele două procese. Această problemă a fost rezolvată în Linux 3.14.

CONSULTAȚI ȘI
close(2), fcntl(2), fsync(2), ioctl(2), lseek(2), open(2), pwrite(2), read(2), select(2), writev(2), fwrite(3)

TRADUCERE
Traducerea în limba română a acestui manual a fost făcută de Remus-Gabriel Chelu <remusgabriel.chelu@disroot.org>

Această traducere este documentație gratuită; citiți Licența publică generală GNU Versiunea 3 (https://www.gnu.org/licenses/gpl-3.0.html) sau o versiune ulterioară cu privire la condiții privind drepturile de autor. NU se asumă NICIO RESPONSABILITATE.

Dacă găsiți erori în traducerea acestui manual, vă rugăm să trimiteți un e-mail la translation-team-ro@lists.sourceforge.net.