FOPEN(3)

NOM
fopen, fdopen, freopen - Fonctions d'ouverture de flux

SYNOPSIS
#include <stdio.h>

FILE *fopen(const char *path, const char *mode);
FILE *fdopen(int fd, const char *mode);
FILE *freopen(const char *path, const char *mode, FILE *stream);

Exigences de macros de test de fonctionnalités pour la glibc (voir feature_test_macros(7)) :

fdopen() : _POSIX_C_SOURCE || _XOPEN_SOURCE

DESCRIPTION
La fonction fopen() ouvre le fichier dont le nom est contenu dans la chaîne pointée par path et lui associe un flux.

L'argument mode pointe vers une chaîne commençant par l'une des séquences suivantes (d'autres caractères peuvent suivre la séquence) :

r   Ouvre le fichier en lecture. Le pointeur de flux est placé au début du fichier.

r+  Ouvre le fichier en lecture et écriture. Le pointeur de flux est placé au début du fichier.

w   Tronque le fichier à son début ou ouvre le fichier en écriture. Le pointeur de flux est placé au début du fichier.

w+  Ouvre le fichier en lecture et écriture. Le fichier est créé s'il n'existait pas. S'il existait déjà, sa longueur est ramenée à 0. Le pointeur de flux est placé au début du fichier.

a   Ouvre le fichier en ajout (écriture à la fin du fichier). Le fichier est créé s'il n'existait pas. Le pointeur de flux est placé à la fin du fichier.

a+  Ouvre le fichier en lecture et ajout (écriture en fin de fichier). Le fichier est créé s'il n'existait pas. La tête de lecture initiale du fichier est placée au début du fichier mais la sortie est toujours ajoutée à la fin du fichier.

La chaîne mode peut également inclure la lettre « b » comme dernier caractère, ou même entre les deux caractères d'une des séquences à 2 caractères vues ci-dessus. Ce mode sert uniquement à assurer la compatibilité avec C89 et n'a aucun effet. Le « b » est ignoré sur tous les systèmes compatibles POSIX, y compris Linux. (D'autres systèmes peuvent traiter les fichiers de texte et les fichiers binaires différemment, et l'ajout du « b » peut être une bonne idée si vous faites des entrées-sorties binaires et que votre programme risque d'être porté sur un environnement non-Unix).

Tout fichier créé aura le mode S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666), qui sera ensuite modifié par la valeur d'umask du processus. Voir umask(2).

Les lectures et les écritures peuvent être mélangées sur les flux en lecture et écriture, dans un ordre quelconque. Notez que la norme C ANSI nécessite qu'une fonction de positionnement dans le fichier soit appelée entre une lecture et une écriture, à moins qu'une lecture atteigne la fin du fichier. (Si cette condition n'est pas rencontrée, une lecture est permise pour renvoyer le résultat d'une écriture autre que la dernière). Une bonne habitude (souvent nécessaire sous Linux) consiste donc à intercaler un fseek(3) ou fgetpos(3) entre les lectures et les écritures sur le même flux. Ces opérations peuvent être visiblement sans effet comme fseek(..., 0L, SEEK_CUR) et ne servant que pour l'effet de bord de synchronisation.

Ouvrir un fichier en mode ajout (a en premier caractère dans le mode) feront agir toutes les opérations d'écriture à la fin du flux, comme si elles étaient précédées par un appel
    fseek(stream,0,SEEK_END);

systématique.

La fonction fdopen() associe un flux avec un descripteur de fichier fd existant. Le mode du flux (« r », « "r+ », « w », « w+ », « a » ou « a+ ») doit être compatible avec celui du descripteur de fichier. L'indicateur de position du nouveau flux prend la même valeur que celui de fd, et les indicateurs d'erreur et de fin de fichier sont effacés. Les modes « w » et « w+ » ne tronquent pas le fichier. Le descripteur n'est pas dupliqué par dup(2), et sera fermé lorsque le flux créé par fdopen() sera fermé. L'appel de fdopen() sur un objet en mémoire partagée est indéfini.

La fonction freopen() ouvre le fichier dont le nom se trouve dans la chaîne de caractères pointée par path et lui associe le flux pointé par stream. Le flux original, s'il existe, est fermé. L'argument mode est utilisé exactement comme avec fopen(). La principale utilisation de freopen() est de modifier le fichier associé aux flux standard de texte (stderr, stdin, ou stdout).

VALEUR RENVOYÉE
Si elles réussissent intégralement fopen(), fdopen() et freopen() renvoient un pointeur sur un fichier, de type FILE. Sinon, elles renvoient NULL et errno contient le code d'erreur.

ERREURS

EINVAL
    Le mode fourni à fopen(), fdopen(), ou freopen() était invalide.

Les fonctions fopen(), fdopen() et freopen() peuvent également échouer et renseigner errno avec une des erreurs susceptibles de se produire avec malloc(3).

La fonction fopen() peut aussi échouer et renseigner errno avec une des erreurs susceptibles de se produire avec open(2).

La fonction fdopen() peut aussi échouer et renseigner errno avec une des erreurs susceptibles de se produire avec fcntl(2).

La fonction freopen() peut aussi échouer et positionner dans errno une des erreurs susceptibles de se produire avec open(2), fclose(3) et fflush(3).

CONFORMITÉ
Les fonctions fopen() et freopen() sont conformes à C89. La fonction fdopen() est conforme à POSIX.1-1990.

NOTES

  Notes glibc
La glibc permet les extensions suivantes pour la chaîne spécifiée dans mode :

c (depuis la glibc 2.3.3)
    Ne pas effectuer l'opération d'ouverture, ou les opérations de lecture et d'écriture suivantes, point d'annulation de thread.

e (depuis la glibc 2.7)
    Ouvrir le fichier avec l'attribut O_CLOEXEC. Voir open(2) pour plus d'informations.

m (depuis la glibc 2.3)
    Essayer d'accéder au fichier avec mmap(2), plutôt qu'avec les appels système d'entrées-sorties (read(2), write(2)). Actuellement, l'utilisation de mmap(2) n'est tentée que pour un fichier ouvert en lecture.

x   Ouvrir le fichier de manière exclusive (comme avec l'attribut O_EXCL de open(2)). Si le fichier existe déjà, fopen() échoue et renseigne errno avec EEXIST. Cet attribut est ignoré par fdopen().

VOIR AUSSI
open(2), fclose(3), fileno(3)

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 23 octobre 1996 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 fopen ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.