Nous recommandons d’utiliser Visual Studio 2017

fopen_s, _wfopen_s

 

Pour obtenir la dernière documentation sur Visual Studio 2017, consultez Documentation Visual Studio 2017.

Ouvre un fichier. Ces versions de fopen, _wfopen ont des améliorations de sécurité, comme décrit dans fonctionnalités de sécurité de la bibliothèque CRT.

errno_t fopen_s(   
   FILE** pFile,  
   const char *filename,  
   const char *mode   
);  
errno_t _wfopen_s(  
   FILE** pFile,  
   const wchar_t *filename,  
   const wchar_t *mode   
);  

Paramètres

[out] pFile
Pointeur désignant le pointeur de fichier appelé à recevoir le pointeur vers le fichier ouvert.

[in] filename
Nom de fichier.

[in] mode
Type d'accès autorisé.

Zéro si l'opération a réussi ; code d'erreur en cas de échec. Consultez la page errno, _doserrno, _sys_errlist et _sys_nerr pour plus d’informations sur ces codes d’erreur.

Conditions d’erreur

pFilefilenamemodeValeur de retourContenu depFile
NULLanyanyEINVALinchangé
anyNULLanyEINVALinchangé
anyanyNULLEINVALinchangé

Les fichiers ouverts par fopen_s et _wfopen_s ne peuvent pas être partagés. Si vous avez besoin qu’un fichier être partageable, utilisez _fsopen, _wfsopen avec la constante appropriée de mode partage, par exemple, _SH_DENYNO pour le partage en lecture/écriture.

La fonction fopen_s ouvre le fichier spécifié par filename. _wfopen_s est une version à caractères larges de fopen_s ; les arguments de _wfopen_s sont des chaînes à caractères larges. Sinon, _wfopen_s et fopen_s se comportent de la même façon.

fopen_s accepte les chemins d'accès valides sur le système de fichiers au point d'exécution ; les chemins d'accès UNC et les chemins d'accès qui impliquent des lecteurs réseau mappés sont acceptés par fopen_s du moment où le système qui exécute le code a accès au partage ou au lecteur réseau mappé au moment de l'exécution. Quand il s'agit de construire des chemins d'accès pour fopen_s, ne faites pas d'hypothèses quant à la disponibilité des lecteurs, chemins d'accès ou partages réseau dans l'environnement d'exécution. Vous pouvez utiliser des barres obliques (/) ou barres obliques inverses (\) comme séparateurs de répertoire dans un chemin d’accès.

Ces fonctions valident leurs paramètres. Si pFile, filename, ou mode est un pointeur null, ces fonctions génèrent une exception de paramètre non valide, comme décrit dans Validation de paramètre.

Vérifiez toujours la valeur de retour pour savoir si la fonction a abouti avant d'effectuer d'autres opérations sur le fichier. Si une erreur se produit, le code d'erreur est retourné et la variable globale errno est définie. Pour plus d’informations, consultez errno, _doserrno, _sys_errlist et _sys_nerr.

fopen_s prend en charge les flux de fichiers Unicode. Pour ouvrir un fichier Unicode nouveau ou existant, passez un indicateur ccs qui spécifie le codage souhaité sur fopen_s :

fopen_s(&fp, "newfile.txt", "rw,   ccs=  encoding ");

Les valeurs autorisées de encoding sont UNICODE, UTF-8et UTF-16LE. Si aucune valeur n'est spécifiée pour encoding, fopen_s utilise le codage ANSI.

Si le fichier existe déjà et qu'il est ouvert pour lecture ou ajout, la marque d'ordre d'octet (BOM, Byte Order Mark), si elle est présente dans le fichier, détermine le codage. Le codage BOM est prioritaire sur le codage spécifié par l'indicateur ccs. Le codage ccs est utilisé uniquement quand aucune marque BOM n'est présente ou si le fichier est un nouveau fichier.

System_CAPS_ICON_note.jpg Remarque

La détection BOM s'applique uniquement aux fichiers ouverts en mode Unicode, autrement dit, en passant l'indicateur ccs.

Le tableau suivant fait la synthèse des modes pour les différents indicateurs ccs donnés à fopen_s et pour les marques BOM présentes dans le fichier.

Codages utilisés selon l'indicateur ccs et la marque BOM

Indicateur ccsAucune marque BOM (ou nouveau fichier)Marque BOM : UTF-8Marque BOM : UTF-16
UNICODEUTF-16LEUTF-8UTF-16LE
UTF-8UTF-8UTF-8UTF-16LE
UTF-16LEUTF-16LEUTF-8UTF-16LE

Une marque BOM est écrite automatiquement dans les fichiers ouverts pour écriture en mode Unicode.

Si mode a la valeur « a, ccs=<encoding> », fopen_s tente d'abord d'ouvrir le fichier avec à la fois un accès en lecture et un accès en écriture. En cas de réussite, la fonction lit la marque BOM pour déterminer le codage du fichier ; en cas d'échec, elle utilise le codage par défaut pour le fichier. Dans les deux cas, fopen_s rouvre le fichier avec un accès en écriture seule. (Cela s'applique uniquement au mode a, et non à a+.)

Mappages de routines de texte générique

Routine TCHAR.H_UNICODE et _MBCS non définis_MBCS défini_UNICODE défini
_tfopen_sfopen_sfopen_s_wfopen_s

La chaîne de caractères mode spécifie le type d'accès demandé pour le fichier, comme suit.

"r"
Ouvre pour l'accès en lecture. Si le fichier n'existe pas ou est introuvable, l'appel à fopen_s échoue.

"w"
Ouvre un fichier vide pour l'accès en écriture. Si le fichier existe, son contenu est détruit.

"a"
Ouvre pour un accès en écriture à la fin du fichier (ajout) sans supprimer le marqueur de fin de fichier (EOF) avant l'écriture de nouvelles données dans le fichier. Crée le fichier s'il n'existe pas.

"r+"
Ouvre pour l'accès en lecture et en écriture. (Le fichier doit exister.)

"w+"
Ouvre un fichier vide pour l'accès en lecture et en écriture. Si le fichier existe, son contenu est détruit.

"a+"
S'ouvre pour lecture et ajout. L'opération d'ajout inclut la suppression du marqueur EOF préalablement à l'écriture de nouvelles données et à la restauration du marqueur EOF à l'issue de l'écriture. Crée le fichier s'il n'existe pas.

Quand un fichier est ouvert en utilisant le type d'accès "a" ou "a+", toutes les opérations d'écriture se produisent à la fin du fichier. Le pointeur de fichier peut être repositionné à l'aide de fseek ou rewind, mais il est toujours redéplacé à la fin du fichier avant toute opération d'écriture pour empêcher le remplacement des données existantes.

Le mode "a" ne supprime pas le marqueur EOF avant l'ajout des données au fichier. Après l'ajout, la commande MS-DOS TYPE affiche uniquement les données jusqu'au marqueur EOF d'origine, et non les données qui sont ajoutées au fichier. Le mode "a+" supprime le marqueur EOF avant l'ajout des données au fichier. Après l'ajout, la commande MS-DOS TYPE affiche toutes les données du fichier. Le mode "a+" est obligatoire pour ajouter des données à un fichier de flux qui se termine par le marqueur EOF Ctrl+Z.

Lors de la "r+",``"w+", ou "a+" type d’accès est spécifié, la lecture et écriture sont autorisées. (On dit que le fichier est ouvert pour « mise à jour ».) Toutefois, lorsque vous basculez de la lecture à l'écriture, l'opération d'entrée doit rencontrer un marqueur EOF. S'il n'existe aucun marqueur EOF, vous devez faire un appel intermédiaire à une fonction de positionnement de fichier. Les fonctions de positionnement de fichier sont fsetpos, fseek et rewind. Quand vous passez de l'écriture à la lecture, vous devez faire un appel intermédiaire à fflush ou à une fonction de positionnement de fichier.

Outre les valeurs ci-dessus, les caractères suivants peuvent être inclus dans mode pour spécifier le mode de traduction pour les caractères de nouvelle ligne :

t
Ouvrir en mode texte (traduit). Dans ce mode, Ctrl+Z est interprété comme un caractère de fin de fichier en entrée. Dans les fichiers ouverts en lecture/écriture avec "a+", fopen_s recherche un Ctrl+Z à la fin du fichier et le supprime, si possible. En effet, l'utilisation des fonctions fseek et ftell pour se déplacer dans un fichier qui se termine par un Ctrl+Z peut provoquer un comportement incorrect de fseek vers la fin du fichier.

De même, en mode texte, les combinaisons retour chariot-saut de ligne sont traduites en sauts de ligne uniques en entrée, et les caractères de saut de ligne sont traduits en combinaisons retour chariot-saut de ligne en sortie. Lorsqu'une fonction d'E/S de flux Unicode s'exécute en mode texte (comportement par défaut), on suppose que le flux source ou de destination est une séquence de caractères multioctets. Par conséquent, les fonctions d'entrée de flux Unicode convertissent les caractères multioctets en caractères larges (comme suite à un appel à la fonction mbtowc ). Pour la même raison, les fonctions de flux de sortie Unicode convertissent les caractères larges en caractères multioctets (comme suite à un appel à la fonction wctomb ).

b
Ouvrir en mode binaire (non traduit) ; les traductions implique la suppression des caractères de retour chariot et de saut de ligne.

Si t ou b n'est pas donné dans mode, le mode de traduction par défaut est défini par la variable globale _fmode. Si t ou b a l'argument comme préfixe, la fonction échoue et retourne NULL.

Pour plus d’informations sur l’utilisation des modes texte et binaire dans Unicode et multioctets flux e/S, consultez e/s de fichier en Mode binaire et de texte et e/s de flux Unicode en Modes texte et binaire.

c
Activer l'indicateur de validation pour le filename associé, afin que le contenu de la mémoire tampon de fichier soit écrit directement sur disque si fflush ou _flushall est appelé.

n
Réinitialiser l'indicateur de validation pour le filename associé à la valeur « no-commit » Il s'agit de la valeur par défaut. Substitue également l'indicateur de validation global si vous liez votre programme avec COMMODE.OBJ. La valeur par défaut de l’indicateur de validation globale est « no-commit », sauf si vous liez explicitement votre programme avec COMMODE.OBJ (consultez Link Options).

N
Indique que le fichier n'est pas hérité par les processus enfants.

S
Indique que la mise en cache est optimisée pour, mais non limitée à, l'accès séquentiel à partir du disque.

R
Indique que la mise en cache est optimisée pour, mais non limitée à, l'accès aléatoire à partir du disque.

T
Spécifie un fichier comme temporaire. Si possible, il n'est pas vidé sur disque.

D
Spécifie un fichier comme temporaire. Il est supprimé lorsque le dernier pointeur de fichier est fermé.

ccs=ENCODING
Spécifie le jeu de caractères codé à utiliser (UTF-8, UTF-16LE et UNICODE) pour ce fichier. Ne spécifiez pas ce paramètre si vous voulez un codage ANSI.

Les caractères valides pour le mode chaîne utilisée dans fopen_s et _fdopen correspondent aux oflag arguments utilisés dans les _open et _sopen, comme suit.

Caractères en mode chaîneÉquivalent oflag valeur_open/_sopen
a_O_WRONLY &#124; _O_APPEND(généralement _O_WRONLY &#124; _O_CREAT &#124;``_O_APPEND)
a+_O_RDWR &#124; _O_APPEND (généralement _O_RDWR &#124; _O_APPEND &#124; _O_CREAT )
r_O_RDONLY
r+_O_RDWR
w_O_WRONLY(généralement _O_WRONLY &#124;``_O_CREAT &#124; _O_TRUNC)
w+_O_RDWR(généralement _O_RDWR &#124; _O_CREAT &#124; _O_TRUNC)
b_O_BINARY
t_O_TEXT
cAucun
nAucun
S_O_SEQUENTIAL
R_O_RANDOM
T_O_SHORTLIVED
D_O_TEMPORARY
ccs=UNICODE_O_WTEXT
ccs=UTF-8_O_UTF8
ccs=UTF-16LE_O_UTF16

Si vous utilisez le mode rb, vous n'aurez pas besoin de porter votre code, et attendez-vous à lire une majeure partie du fichier et/ou ne vous souciez pas des performances réseau ; des fichiers Win32 mappés en mémoire peuvent aussi être une option.

FonctionEn-tête requis
fopen_s<stdio.h>
_wfopen_s<stdio.h> ou <wchar.h>

Pour plus d'informations sur la compatibilité, voir Compatibilité dans l'introduction.

Toutes les versions des bibliothèques Runtime C.

Le c, n, et t mode options sont des extensions Microsoft fopen_s et _fdopen et ne doit pas être utilisé lorsque la portabilité ANSI est souhaitée.

  
      // crt_fopen_s.c  
// This program opens two files. It uses  
// fclose to close the first file and  
// _fcloseall to close all remaining files.  
  
#include <stdio.h>  
  
FILE *stream, *stream2;  
  
int main( void )  
{  
   errno_t err;  
  
   // Open for read (will fail if file "crt_fopen_s.c" does not exist)  
   err  = fopen_s( &stream, "crt_fopen_s.c", "r" );  
   if( err == 0 )  
   {  
      printf( "The file 'crt_fopen_s.c' was opened\n" );  
   }  
   else  
   {  
      printf( "The file 'crt_fopen_s.c' was not opened\n" );  
   }  
  
   // Open for write   
   err = fopen_s( &stream2, "data2", "w+" );  
   if( err == 0 )  
   {  
      printf( "The file 'data2' was opened\n" );  
   }  
   else  
   {  
      printf( "The file 'data2' was not opened\n" );  
   }  
  
   // Close stream if it is not NULL   
   if( stream )  
   {  
      err = fclose( stream );  
      if ( err == 0 )  
      {  
         printf( "The file 'crt_fopen_s.c' was closed\n" );  
      }  
      else  
      {  
         printf( "The file 'crt_fopen_s.c' was not closed\n" );  
      }  
   }  
  
   // All other files are closed:  
   int numclosed = _fcloseall( );  
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );  
}  

The file 'crt_fopen_s.c' was opened  
The file 'data2' was opened  
Number of files closed by _fcloseall: 1  

Flux d’e/s
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode

Afficher: