fopen_s, _wfopen_s

Ouvre un fichier. Ces versions ont des améliorations de fopen _wfopensécurité, comme décrit dans les fonctionnalités de sécurité du CRT.

Syntaxe

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

pFile
Pointeur vers le pointeur de fichier qui reçoit le pointeur vers le fichier ouvert.

filename
Nom du fichier à ouvrir.

mode
Type d'accès autorisé.

Valeur retournée

Zéro si l'opération a réussi ; code d'erreur en cas de échec. Pour plus d’informations sur ces codes d’erreur, consultez , , _sys_errlist_doserrnoet _sys_nerr.errno

Conditions d’erreur

Notes

Les fopen_s fonctions et _wfopen_s ne peuvent pas ouvrir un fichier pour le partage. Si vous avez besoin de partager le fichier, utilisez _fsopen ou _wfsopen utilisez la constante de mode de partage appropriée, par exemple pour _SH_DENYNO le partage en lecture/écriture.

La fopen_s fonction ouvre le fichier spécifié par filename. _wfopen_s est une version à caractères larges et fopen_s les arguments à mettre en valeur sont des chaînes à _wfopen_s caractères larges. _wfopen_s et fopen_s se comportent de façon identique, sinon.

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 des barres obliques inverses (\) comme séparateurs de répertoires dans un chemin d’accès.

Ces fonctions valident leurs paramètres. Si pFile, filenameou mode est un pointeur Null, ces fonctions génèrent une exception de paramètre non valide, comme décrit dans la validation des paramètres.

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

Par défaut, l’état global de cette fonction est limité à l’application. Pour le modifier, consultez l’état global dans le CRT.

Prise en charge d’Unicode

fopen_s prend en charge les flux de fichiers Unicode. Pour ouvrir un fichier Unicode nouveau ou existant, transmettez un ccs indicateur qui spécifie l’encodage souhaité, fopen_spar exemple :

fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");

Les valeurs autorisées de l’indicateur ccs sont UNICODE, UTF-8et UTF-16LE. Si aucune valeur n’est spécifiée pour ccs, fopen_s utilise l’encodage ANSI.

Si le fichier existe déjà et est ouvert pour la lecture ou l’ajout, la marque d’ordre d’octet (BOM), s’il est présent dans le fichier, détermine l’encodage. 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.

Le tableau suivant récapitule les modes des différentes ccs valeurs d’indicateur qui sont données aux fopen_s machines virtuelles dans le fichier et pour les machines virtuelles.

Encodages utilisés en fonction de l’indicateur et du ccs boM

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

Si mode c’est "a, ccs=UNICODE", "a, ccs=UTF-8"ou , ou "a, ccs=UTF-16LE", fopen_s tente d’abord d’ouvrir le fichier avec accès en lecture et 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 rouvert le fichier avec un accès en écriture seule. (Ce comportement s’applique uniquement au mode, pas a+à a .)

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

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 fseek ou rewind, mais il est toujours déplacé vers la fin du fichier avant qu’une opération d’écriture soit effectuée afin que les données existantes ne puissent pas être remplacées.

Le "a" mode ne supprime pas le marqueur EOF avant de l’ajouter au fichier. Une fois l’ajout effectué, la commande MS-DOS TYPE affiche uniquement les données jusqu’au marqueur EOF d’origine et non les données 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 "a+" mode est requis pour l’ajout à un fichier de flux qui est arrêté avec leCTRL+ marqueur Z EOF.

Lorsque le type d’accès ou "a+" de "w+"lecture est spécifié, la lecture et l’écriture "r+"sont autorisées. (Le fichier est dit ouvert pour « update ». Toutefois, lorsque vous passez de la lecture à l’écriture, l’opération d’entrée doit se trouver sur un marqueur EOF. S’il n’existe aucun marqueur EOF, vous devez utiliser 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.

À compter de C11, vous pouvez ajouter "x" ou "w+" "w" provoquer l’échec de la fonction si le fichier existe, au lieu de le remplacer.

Outre les valeurs précédentes, les caractères suivants peuvent être inclus pour mode spécifier le mode de traduction pour les caractères de nouvelle ligne :

En mode texte (traduit), CTRL+Z est interprété comme un caractère de fin de fichier lors de l’entrée. Pour les fichiers ouverts pour la lecture/écriture avec "a+", fopen_s recherche unCTRL+ Z à la fin du fichier et le supprime, si possible. Elle est supprimée, car l’utilisation fseek et ftell le déplacement dans un fichier qui se termine par unCTRL+ Z peuvent entraîner fseek un comportement incorrect près de la fin du fichier.

En outre, en mode texte, les combinaisons retour chariot/flux de ligne (CRLF) sont traduites en caractères LF (Single Line Feed) sur entrée, et les caractères LF sont traduits en combinaisons CRLF 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. Les fonctions d’entrée de flux Unicode convertissent des caractères multioctets en caractères larges (comme s’il s’agit d’un appel à la mbtowc fonction). 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 ).

Si t la b variable globale est définie ou non, modele mode de traduction par défaut est défini par la variable _fmodeglobale. Si t ou b a l'argument comme préfixe, la fonction échoue et retourne NULL.

Pour plus d’informations sur l’utilisation de modes texte et binaire dans les E/S de flux Unicode et multioctets, consultez E/S de fichier de texte et de mode binaire et E/S de flux Unicode dans les modes texte et binaire.

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

Les cextensions , , SRt, n, T, et D mode les options Microsoft sont pour fopen_s et _wfopen_s ne doivent pas être utilisées lorsque vous souhaitez la portabilité ANSI.

Si vous utilisez rb le mode, les fichiers Win32 mappés en mémoire peuvent également être une option si vous n’avez pas besoin de porter votre code, vous vous attendez à lire une grande partie du fichier, ou vous ne vous souciez pas des performances réseau.

En ce qui concerne T et D:

• T évite d’écrire le fichier sur le disque tant que la pression de la mémoire ne le nécessite pas. Pour plus d’informations, consultez FILE_ATTRIBUTE_TEMPORARY les constantes d’attributs de fichier et ce billet de blog uniquement temporaire.
• D spécifie un fichier standard écrit sur le disque. La différence est qu’elle est automatiquement supprimée lorsqu’elle est fermée. Vous pouvez combiner TD pour obtenir les deux sémantiques.

Spécifications

Pour plus d’informations sur la conformité aux normes et les conventions d’affectation de noms dans la bibliothèque runtime C, consultez Compatibilité.

Mappages de routines de texte générique

Bibliothèques

Toutes les versions des bibliothèques Runtime C.

Exemple

// 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" doesn't 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+, ccs=UTF-8" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it isn't 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

Voir aussi

E/S de flux
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode