NOME
write − Scrive su un descrittore di file
SINTASSI
#include <unistd.h>
ssize_t write(int fd, const void *buf, size_t count);
DESCRIZIONE
write() scrive fino a count byte contenuti in buf nel file a cui fa riferimento il descrittore di file fd.
Il numero di byte scritti potrebbe essere meno di count se, per esempio, non c’è spazio sufficiente sul supporto fisico sottostante, o se si raggiunge il limite della risorsa RLIMIT_FSIZE (vedere setrlimit(2)), o se la chiamata è stata interrotta da un handler di segnale dopo che ha scritto meno di count byte (vedere anche pipe(7)).
Per un file che si può spostare (cioè un file a cui si può applicare lseek(2), per esempio un file regolare), la scrittura viene eseguita all’offset del file attuale, e l’offset del file viene incrementato dal numero di byte effettivamente scritti. Se il file è stato aperto da open(2) con O_APPEND, l’offset del file viene prima impostato alla fine del file, e poi scritto. La regolazione dell’offset del file e l’operazione di scrittura vengono eseguite come un’operazione atomica.
POSIX richiede che una chiamata read(2) avvenuta dopo l’esecuzione di una chiamata write() restituisca i nuovi dati. Notare che non tutti i filesystem sono conformi a POSIX.
VALORI RESTITUITI
Se è andato tutto bene, la funzione restituisce il numero di byte scritti (zero indica che non è stato scritto nulla). In caso di errore viene restituito −1 , e errno viene impostato di conseguenza.
Se count è zero, e fd fa riferimento ad un file regolare, write() può restituire uno stato di insuccesso se viene rilevato uno degli errori descritti più avanti. Se non vengono rilevati errori, restituisce 0 senza causare altri effetti. Se count è zero e fd fa riferimento ad un file diverso da uno regolare, i risultati non sono specificati.
ERRORI
|
EAGAIN |
Il descrittore di file fd fa riferimento a un file diverso da un socket ed è stato marcato come non bloccante (O_NONBLOCK), e la scrittura si bloccherebbe. |
EAGAIN o EWOULDBLOCK
Il descrittore di file fd fa riferimento a un diverso da un socket ed è stato marcato come non bloccante (O_NONBLOCK), e la scrittura si bloccherebbe. POSIX.1-2001 consente che venga restituito uno qualsiasi dei due errori per questo caso, e non richiede che queste costanti abbiano lo stesso valore, per cui un’applicazione portabile dovrebbe verificare entrambe le possibilità.
|
EBADF |
fd non è un decrittore di file valido o non è aperto in scrittura. |
EDESTADDRREQ
fd fa riferimento a un socket a datagrammi per il quale un indirizzo dello stesso livello non è stato impostato usando connect(2).
|
EDQUOT |
La quota utente di blocchi del disco sul filesystem contenente il file a cui fd fa riferimento è esaurita. | ||
|
EFAULT |
buf è al di fuori del proprio spazio di indirizzamento accessibile. | ||
|
EFBIG |
È stato fatto un tentativo di scrivere un file che supera la massima dimensione del file definita dall’implementazione o il limite di dimensione del file del processo, o di scrivere ad una posizione oltre il massimo offset consentito. | ||
|
EINTR |
La chiamata è stata interrotta da un segnale prima che sia stato scritto qualunque dato; vedere signal(7). | ||
|
EINVAL |
fd è attaccato a un oggetto su cui non si può scrivere; o il file è stato aperto con l’opzione O_DIRECT, e l’indirizzo specificato in buf, o il valore specificato in count, o l’offset del file corrente non è correttamente allineato. | ||
|
EIO |
Un errore I/O di basso livello è accaduto mentre si modificava l’inode. | ||
|
ENOSPC |
Il dispositivo contenente il file a cui fa riferimento fd non ha spazio per i dati. | ||
|
EPIPE |
fd è connesso a una pipe o un socket la cui lettura è chiusa. Quando ciò accade il processo di scrittura riceverà anche un segnale SIGPIPE. (Quindi il valore restituito in scrittura è visto solo se il programma intercetta, blocca o ignora questo segnale). |
Possono accadere altri errori, in funzione dell’oggetto connesso a fd.
CONFORME A
SVr4, 4.3BSD, POSIX.1-2001.
Sotto SVr4 una scrittura può essere interrotta e restituire EINTR in qualsiasi punto, non solo prima che venga scritto un dato.
NOTE
Un ritorno con successo da write() non dà alcuna garanzia che i dati siano stati trasferiti sul disco. Infatti in alcune implementazioni errate, esso non garantisce che questo spazio sia stato riservato per i dati con successo. Il solo modo per essere sicuri è di chiamare fsync(2) dopo che si è eseguita la scrittura di tutti i propri dati.
Se una scrittura con write() viene interrotta da un handler di segnale prima che venga scritto qualunque byte, la chiamata fallisce con l’errore EINTR; se viene interrotta dopo aver scritto almeno un byte, la chiamata ha successo e restituisce il numero di byte scritti.
BUG
Secondo POSIX.1-2008/SUSv4 Section XSI 2.9.7 ("Thread Interactions with Regular File Operations"):
Tutte le seguenti funzioni devono essere atomiche l’una rispetto all’altra nei risultati specificati in POSIX.1-2008 quando esse operano su file regolari o su collegamenti simbolici: ...
Tra le API elencate susseguentemente ci sono write() e writev(2). E tra i risultati che dovrebbero essere atomici attraverso i thread (e i processi) ci sono gli aggiornamenti dell’offset dei file. Tuttavia, sulle versioni di Linux precedenti alla 3.14 non era così: se due processi che condividono una descrizione di file aperto (vedi open(2)) effettuano un write() (o writev(2)) allo stesso tempo, le operazioni I/O non erano atomiche rispetto all’offset del file, col risultato che i blocchi di dati in uscita dai due processi potrebbero (non correttamente) sovrapporsi. Questo problema è stato risolto in Linux 3.14.
VEDERE ANCHE
close(2), fcntl(2), fsync(2), ioctl(2), lseek(2), open(2), pwrite(2), read(2), select(2), writev(2), fwrite(3)
COLOPHON
Questa pagina fa parte del rilascio 3.73 del progetto Linux man-pages. Una descrizione del progetto, le istruzioni per la segnalazione degli errori, e l’ultima versione di questa pagina si trova su http://www.kernel.org/doc/man−pages/.
La versione
italiana fa parte del pacchetto man-pages-it v. 3.73,
a cura di: ILDP "Italian Linux Documentation
Project" http://www.pluto.it/ildp
Per la traduzione in italiano si può fare riferimento
a http://www.pluto.it/ildp/collaborare/
Segnalare eventuali errori di traduzione a
ildp [AT] pluto.it