Sous-routine write, writex, write64x, writev, writevx, ewrite, ewritev, pwrite ou pwritev

Objectif

Ecrit dans un fichier.

Bibliothèque

Syntaxe

#include <unistd.h>

ssize_t write (FileDescriptor, Buffer, NBytes)
int  FileDescriptor;
const void * Buffer;
size_t  NBytes;

int writex (FileDescriptor, Buffer, NBytes, Extension)
int FileDescriptor;
char *Buffer;
unsigned int NBytes;
int  Extension;

int write64x (FileDescriptor, Buffer, NBytes, Extension)
int FileDescriptor;
void *Buffer;
size_t NBytes;
void *Extension;

ssize_t pwrite (FileDescriptor, Buffer, NBytes, Offset)
int  FileDescriptor;
const void * Buffer;
size_t  NBytes;
off_t Offset;

#include <sys/uio.h>

ssize_t writev (FileDescriptor, iov, iovCount)
int FileDescriptor;
const struct iovec *  iov;
int  iovCount;

ssize_t writevx (FileDescriptor, iov, iovCount, Extension)
int FileDescriptor;
struct iovec *iov;
int iovCount;
int  Extension;

#include <unistd.h>
#include <sys/uio.h>

ssize_t pwritev ( 
int  FileDescriptor,
const struct iovec * iov,
int iovCount,
offset_t offset);

ssize_t ewrite (FileDescriptor, Buffer, Nbytes,  labels)
int  FileDescriptor;
const void * Buffer;
size_t  NBytes;
sec_labels_t * labels;

ssize_t ewritev (FileDescriptor, iov, iovCount,labels)
int FileDescriptor;
const struct iovec * iov;
int  iovCount;
sec_labels_t * labels;

Descriptif

La sous-routine write tente d'écrire le nombre d'octets de données spécifié par le paramètre NBytes dans le fichier associé au paramètre FileDescriptor à partir de la mémoire tampon désignée par le paramètre Buffer .

La sous-routine writev exécute la même action mais collecte les données de sortie des mémoires tampon iovCount spécifiées par le tableau de structures iovec désigné par le paramètre iov . Chaque entrée Iovec indique l'adresse de base et la longueur d'une zone dans la mémoire à partir de laquelle les données sont écrites. La sous-routine Writev écrit toujours une zone complète avant qu'elle ne passe à l'étape suivante.

Les sous-routines Writex et Writevx sont les mêmes que les sous-routines écrire et Writev , avec l'ajout d'un paramètre Extension , qui est utilisé pour écrire sur certains pilotes de périphérique.

Avec des fichiers et des dispositifs réguliers capables de rechercher, l'écriture réelle des données se fait à partir de la position dans le fichier indiqué par le pointeur de fichier. En retour de la sous-routine écrire , le pointeur de fichier incrémente le nombre d'octets écrits.

Avec les dispositifs incapables de chercher, l'écriture commence toujours à la position courante. La valeur d'un pointeur de fichier associé à une telle unité n'est pas définie.

Si une écrire demande que plus d'octets soient écrits qu'il n'y a de place pour (par exemple, le Ulimit ou la fin physique d'un support), il n'y a qu'un nombre d'octets pour l'écriture. Par exemple, supposons qu'il y ait un espace pour 20 octets de plus dans un fichier avant qu'il atteigne une limite. Un écrire de 512 octets renvoie 20. La prochaine écriture d'un nombre non nul d'octets donne un retour d'échec (sauf comme indiqué dans la rubrique en cours) et l'implémentation génère un signal SIGXFSZ pour l'unité d'exécution.

Moins d'octets peuvent être écrits que ceux demandés s'il n'y a pas suffisamment de place pour satisfaire la demande. Ici, le nombre d'octets écrits est renvoyé. La tentative suivante d'écriture d'un nombre non nul d'octets n'aboutit pas (excepté comme indiqué dans le texte suivant). La limite atteinte peut être définie par le sous-programme Ulimit ou par la fin du support physique.

L'exécution d'un sous-programme d'écriture efface le bit SetUserID(S_ISUID) d'un fichier si toutes les conditions suivantes sont remplies :

• Le processus appelant ne dispose pas des droits utilisateur root.
• L'ID utilisateur effectif du processus appelant ne correspond pas à l'ID utilisateur du fichier.
• Le fichier est exécutable par le groupe (S_IXGRP) ou autre (S_IXOTH).

Le sous-programme d'écriture efface le bit SetGroupID(S_ISGID) si toutes les conditions suivantes sont remplies :

• Le processus appelant ne dispose pas des droits utilisateur root.
• L'ID groupe du fichier ne correspond pas à l'ID de groupe effectif ou à l'un des ID de groupe supplémentaires du processus.
• Le fichier est exécutable par le propriétaire (S_IXUSR) ou d'autres (S_IXOTH).

Si l'indicateur O_APPEND du statut du fichier est défini, le décalage du fichier est défini à la fin du fichier avant chaque écriture.

Si le paramètre FileDescriptor fait référence à un fichier standard dont les indicateurs de statut de fichier indiquent O_SYNC, cette action est une mise à jour synchrone (comme décrit dans la sous-routine open ).

Si le paramètre FileDescriptor fait référence à un fichier standard ouvert par un processus avec l'indicateur de statut de fichier O_DEFER défini, les données et la taille de fichier ne sont pas mises à jour sur le stockage permanent tant qu'un processus n'a pas lancé une sous-routine fsync ou effectué une mise à jour synchrone. Si tous les processus qui ont ouvert le fichier avec l'indicateur d'état du fichier O_REPORT ont défini la fermeture du fichier avant qu'un processus n'exécute une sous-routine Fsync ou effectue une mise à jour synchrone, les données et la taille des fichiers ne sont pas mises à jour sur le stockage permanent.

Les demandes d'écriture à un canal de communication (ou FIFO) sont traitées de la même manière qu'un fichier ordinaire avec les exceptions suivantes:

• Aucun décalage de fichier n'est associé à un canal de communication ; par conséquent, chaque demande d'écriture ajoute à la fin du canal de communication.
• Si la taille de la demande d'écriture est inférieure ou égale à la valeur de la variable système PIPE_BUF (décrite dans la routine Pathconf ), la sous-routine écrire est automatique. Les données ne sont pas imbriquée avec des données provenant d'autres processus d'écriture sur le même tube. Les écritures de plus de PIPE_BUF octets peuvent avoir des données entrelacées, sur des frontières arbitraires, avec des écritures par d'autres processus, que les indicateurs d'état du fichier O_NDELAY ou O_NONBLOCK soient définis.
• Si les indicateurs d'état du fichier O_NDELAY et O_NONBLOCK sont clairs (valeur par défaut), une demande d'écriture sur un canal complet entraîne le blocage du processus jusqu'à ce que suffisamment d'espace soit disponible pour traiter la demande entière.
• Si l'indicateur d'état du fichier O_NDELAY est défini, une écriture dans un canal complet renvoie un 0.
• Si l'indicateur de statut du fichier O_NONBLOCK est défini, une opération d'écriture sur un canal de communication complet renvoie la valeur -1 et définit la variable globale errno sur EAGAIN.

Lorsque les systèmes tentent d'écrire dans un fichier spécial de type caractère qui prend en charge les écritures sans blocage et qu'aucune donnée ne peut actuellement être écrite (les flux sont une exception qui est décrite plus loin):

• Si les indicateurs O_NDELAY et O_NONBLOCK sont clairs (valeur par défaut), les blocs de sous-routine écrire jusqu'à ce que les données puissent être écrites.
• Si l'indicateur O_NDELAY est défini, la sous-routine écrire renvoie 0.
• Si l'indicateur O_NONBLOCK est défini, la sous-routine write renvoie -1 et définit la variable globale errno sur EAGAIN si aucune donnée ne peut être écrite.

Lorsque les systèmes tentent d'écrire dans un fichier ordinaire qui prend en charge les verrous d'enregistrement en mode application, et que tout ou partie de la région à écrire est verrouillé par un autre processus, les éléments suivants peuvent se produire:

• Si les indicateurs d'état des fichiers O_NDELAY et O_NONBLOCK sont clairs (valeur par défaut), les blocs de processus appelant jusqu'à la libération du verrou.
• Si l'indicateur de statut du fichier O_NDELAY ou O_NONBLOCK est défini, la sous-routine write renvoie la valeur -1 et définit la variable globale errno sur EAGAIN.

Si Congés fait référence à un STREAM, l'opération de écrire est déterminée par les valeurs de la plage Nbyte minimale et maximale ("taille de paquet") acceptée par le STREAM. Ces valeurs sont déterminées par le module STREAM le plus haut. Si Nbyte tombe dans la plage de taille de paquet, Nbyte octets sont écrits. Si Nbyte ne tombe pas dans la plage et que la valeur minimale de la taille de paquet est 0, écrire interrompait la mémoire tampon dans les segments de taille de paquet maximum avant d'envoyer les données en aval (le dernier segment contient moins que la taille maximale des paquets). Si Nbyte ne tombe pas dans la plage et que la valeur minimale est différente de zéro, écrire échoue avec Errno défini sur ERANGE. L'écriture d'une mémoire tampon de longueur zéro (Nbyte est 0) sur un périphérique STREAMS envoie 0 octets avec 0 renvoyé. Cependant, l'écriture d'une mémoire tampon de longueur zéro sur un canal de communication basé sur STREAMS ou sur FIFO n'envoie aucun message et 0 est renvoyé. Le processus peut émettre I_SWROPT Ioctl pour permettre l'envoi de messages de longueur zéro à travers le tube ou FIFO.

Lorsque le système écrit dans un STREAM, les messages de données sont créés avec une bande de priorité de 0. Lorsqu'il s'agit d'écrire dans un STREAM qui n'est pas un tube ou FIFO:

• O_NONBLOCK indique O_NONBLOCK ou O_NDELAY. L'implémentation d'IBM streams traite ces deux types de données de la même manière.
• Si O_NONBLOCK ou O_NDELAY est clair, et que le STREAM ne peut pas accepter de données (la file d'attente d'écriture STREAM est pleine à cause des conditions de contrôle de flux internes), écrire blocs jusqu'à ce que les données puissent être acceptées.
• Si O_NONBLOCK ou O_NDELAY est défini et que STREAM ne peut pas accepter de données, write renvoie -1 et définit errno sur EAGAIN.
• Si O_NONBLOCK ou O_NDELAY est défini et qu'une partie de la mémoire tampon a été écrite alors qu'une condition dans laquelle le STREAM ne peut pas accepter d'autres données se produit, écrire termine et renvoie le nombre d'octets écrits.

En outre, écrire et Writev échouent si la tête de STREAM traite une erreur asynchrone avant l'appel. Ici, la valeur de Errno ne reflète pas le résultat de écrire ou Writev mais reflète l'erreur précédente.

La fonction Writev est équivalente à écrire, mais rassemble les données de sortie des mémoires tampon Iovcnt spécifiées par les membres de la Iov array: iov [ 0 ], iov [ 1 ], ..., Iov [ iovcnt-1 ]. iovcnt est valide s'il est supérieur à 0 et inférieur ou égal à {IOV_MAX}, défini dans limits.h.

Chaque entrée Iovec indique l'adresse de base et la longueur d'une zone dans la mémoire à partir de laquelle les données sont écrites. La fonction Writev écrit toujours une zone complète avant qu'elle ne passe à l'étape suivante.

If Congés refers to a regular file and all of the Iov_len members in the array pointed to by Iov are 0, Writev returns 0 and have no other effect. Pour les autres types de fichiers, le comportement n'est pas spécifié.

Si la somme des valeurs Iov_len est supérieure à SSIZE_MAX, l'opération échoue et aucune donnée n'est transférée.

Le comportement d'un sous-programme écrire interrompu dépend de la façon dont le gestionnaire du signal d'arrivée a été installé. Le gestionnaire peut être installé de deux manières, avec les résultats suivants:

• Si le gestionnaire est installé avec une indication que les sous-routines ne sont pas redémarrées, la sous-routine write renvoie la valeur -1 et définit la variable globale errno sur EINTR (même si certaines données ont déjà été écrites).
• Si le gestionnaire est installé avec une indication que les sous-routines doivent être redémarrées, et:
  • Si aucune donnée n'a été écrite lorsque l'interruption a été traitée, la sous-routine écrire ne renvoie pas de valeur (elle est redémarrée).
  • Si des données ont été écrites lorsque l'interruption a été traitée, cette sous-routine écrire renvoie la quantité de données déjà écrites.

La sous-routine write64x est identique à la sous-routine Writex , où le paramètre Extension est un pointeur vers une structure j2_ext (voir le fichier j2/j2_cntl.h ). La sous-routine write64x est utilisée pour écrire un fichier chiffré en mode brut (voir O_RAW dans le fichier fcntl.h ). L'utilisation de l'indicateur O_BRUT sur des fichiers chiffrés présente les mêmes limitations que l'utilisation de O_DIRECT sur des fichiers standard.

Les sous-routines Ewrite et Ewritev écrivent dans un flux et définissez les attributs de sécurité. La sous-routine ewrite copie le nombre d'octets des données spécifiées par le paramètre Nbyte de la mémoire tampon désignée par le paramètre Buffer dans un flux associé au paramètre FileDescriptor . Les informations de sécurité du message sont définies sur les valeurs de la structure pointé par le paramètre Libellés .

La fonction Pécrire exécute la même action que écrire, sauf qu'elle écrit dans une position donnée sans modifier le pointeur de fichier. Les trois premiers arguments de Pécrire sont identiques à écrire avec l'ajout d'un quatrième argument qui est décalque pour la position recherchée dans le fichier.

ssize_t pwrite64(int fd , const void *buf , size_t nbytes , off64_t offset)

La sous-routine pwrite64 effectue la même action que pwrite , mais la limite de décalage de la taille de fichier maximale pour le fichier associé à fileDescriptor et à DEV_OFF_MAX si le fichier associé à fileDescriptor est un fichier spécial de type bloc ou caractère spécial.

L'utilisation de la sous-routine écrire ou Pécrire avec un descripteur de fichier obtenu à partir d'un appel vers la sous-routine Shm_open échoue avec ENXIO.

La sous-routine Pwritev exécute la même action que la sous-routine Writev , sauf que la sous-routine Pwritev écrit dans la position donnée dans le fichier sans modifier le pointeur de fichier. Les trois premiers arguments de la sous-routine Pwritev sont identiques à ceux de la sous-routine Writev avec l'ajout de l'argument Décalage qui pointe vers la position que vous souhaitez dans le fichier. Une erreur se produit lorsque le fichier que le sous-programme Pwritev écrit est incapable de rechercher.

Paramètres

caddr_t  iov_base;
size_t  iov_len;

Valeurs renvoyées

Upon successful completion, the écrire, Writex, write64x, Writev, Writevx, et Pwritev subroutines return the number of bytes that were written. Le nombre d'octets écrits n'est jamais supérieur à la valeur spécifiée par le paramètre Noctetles . Sinon, la valeur -1 est renvoyée et la variable globale errno est définie pour indiquer l'erreur.

Une fois l'exécution terminée, les sous-programmes Ewrite et Ewritev renvoient une valeur de 0. Sinon, la variable globale Errno est définie pour identifier l'erreur.

Codes d'erreur

Les sous-routines écrire, Writex, write64x, Writev, Writevx, Ewrite, Ewritevet Pwritev ne sont pas réussies lorsqu'une ou plusieurs des opérations suivantes sont vraies:

Les sous-programmes écrire, Writex, Writev, Writevxet Pwritev risquent d'être infructueuses si les éléments suivants sont vrais: