fopen_s, _wfopen_s

Article
03/26/2013

Ouvre un fichier.Ces versions d' le fopen, _wfopen ont des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité du 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 vers le pointeur de fichier qui reçoit un pointeur vers un fichier ouvert.
[in] filename
Nom de fichier.
[in] mode
Type d'accès autorisé.

Valeur de retour

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

Conditions d'erreur

pFile	filename	mode	Valeur de retour	Contenud'pFile
NULL	any	any	EINVAL	inchangé
any	NULL	any	EINVAL	inchangé
any	any	NULL	EINVAL	inchangé

Notes

Les fichiers ouverts par fopen_s et _wfopen_s ne sont pas partageables.Si vous avez besoin d'un fichier est partageable, utilisez _fsopen, _wfsopen avec le mode approprié de partage constante- pour l'exemple, _SH_DENYNO pour le partage lecture/écriture.

La fonction d' fopen_s ouvre le fichier spécifié par filename._wfopen_s est une version à caractère élargi d' fopen_s; les arguments à _wfopen_s sont des chaînes à caractères larges._wfopen_s et fopen_s se comportent de sinon.

fopen_s reçoit les chemins d'accès valides sur le système de fichiers au point de l'exécution ; Les chemins d'accès UNC et les chemins qui font participer les lecteurs réseau mappés sont reçus par fopen_s tant que 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.Lorsque vous construisez des chemins d'accès pour fopen_s, n'effectuez pas les hypothèses sur la disponibilité des lecteurs, des chemins, ou des partages réseau dans l'environnement d'exécution.Vous pouvez utiliser les barres obliques (///) ou des 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 des paramètres.

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

Prise en charge Unicode

flux de fichiers Unicode prend en charge d'fopen_s .Pour ouvrir un nouveau ou existant fichier Unicode, passez une balise d' ccs qui spécifie l'encodage souhaité à fopen_s:

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

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

Si le fichier existe déjà et est ouvert pour lire ou ajouter, la marque d'ordre d'octet (BOM), si actuel dans le fichier, détermine l'encodage.L'encodage de BOM est prioritaire sur le codage qui est spécifié par la balise d' ccs .Encodage d' ccs est utilisé uniquement lorsque aucun BOM n'est présent ou si le fichier est un fichier.

[!REMARQUE]

La BOM- détection s'applique uniquement aux fichiers qui sont en Unicode état ouvert ; autrement dit, en passant la balise d' ccs .

Le tableau suivant résume les modes pour les balises d' ccs fournies à fopen_s et pour les jetons d'ordre d'octet dans le fichier.

Encodages utilisés sur la balise de ccs et le BOM

Indicateur ccs	Aucun (BOM ou fichier)	BOM : UTF-8	BOM : UTF-16
UNICODE	UTF-16LE	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

Les fichiers ouverts pour entrer en Unicode mode ont un BOM écrit à eux automatiquement.

Si mode est « a, ccs=<encoding> », d' fopen_s des tests d'abord pour ouvrir le fichier l'accès en lecture et l'accès en écriture.Si réussie, la fonction lit le BOM pour déterminer l'encodage du fichier ; si infructueuse, la fonction utilise l'encodage 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 à a mode uniquement, pas a+.)

Mappages de routines de texte générique

Routine de TCHAR.H	_UNICODE et non définis _MBCS	_MBCS défini	_UNICODE défini
_tfopen_s	fopen_s	fopen_s	_wfopen_s

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

"r"
S'ouvre pour la lecture.Si le fichier n'existe pas ou est introuvable, l'appel d' fopen_s échoue.
"w"
Ouvre un fichier vide pour écrire.Si le fichier existe, son contenu est détruit.
"a"
S'ouvre pour écrire à la fin de le fichier (ajouter) sans supprimer marqueur EOF avant d'entrer de nouvelles données vers le fichier.Crée le fichier s'il n'existe pas.
"r+"
S'ouvre pour la lecture et l'écriture.(Le fichier doit exister.)
"w+"
Ouvre un fichier vide pour la lecture et l'écriture.Si le fichier existe, son contenu est détruit.
"a+"
S'ouvre pour lire et ajouter.L'opération d'ajout inclut la suppression de marqueur EOF avant de nouvelles données sont écrites dans le fichier et marqueur EOF est restauré une fois que l'écriture soit terminé.Crée le fichier s'il n'existe pas.

Lorsqu'un fichier est ouvert à l'aide de le type d'accès d' "a" ou d' "a+", toutes les opérations d'écriture se produisent à la fin de le fichier.Le pointeur de fichier peut être réadressé à l'aide de fseek ou d' rewind, mais il est toujours déplacé vers la fin du fichier avant qu'une opération d'écriture soit exécutée afin que les données existantes ne puissent pas être remplacées.

Le mode d' "a" ne supprime pas marqueur EOF avant d'ajouter vers le fichier.Après avoir ajouté s'est produit, le TYPE données de l'de commande uniquement jusqu'à EOF marqueur d'origine et non les données de commande MS-DOS qui sont ajoutées au fichier.Le mode d' "a+" supprime marqueur EOF avant d'ajouter vers le fichier.Après avoir ajouté, le TYPE de commande MS-DOS affiche toutes les données dans le fichier.Le mode d' "a+" est requis pour ajouter à un fichier de flux qui est terminé à l'aide de CTRL+Z marqueur EOF.

Lorsque "r+","w+", ou le type d'accès d' "a+" est spécifié, il permet la lecture et l'écriture.(Le fichier est dit ouvert pour « update »). Toutefois, lorsque vous basculez de la lecture à écrire, l'opération d'entrée doit rencontrer marqueur EOF.S'il n'existe aucun EOF, vous devez utiliser un appel intervenant à une fonction de positionnement de fichier.Les fonctions de positionnement de fichier sont fsetpos, fseek, et rewind.Lorsque vous basculez d'écriture à lire, vous devez utiliser un appel intervenant à 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 un en mode de traduction des caractères de saut de ligne :

t
Ouvrez en mode de texte (traduits).Dans ce mode, CTRL+Z est interprète comme un caractère de fin de fichier sur l'entrée.Dans les fichiers ouverts pour la lecture/écriture avec "a+", fopen_s vérifie un CTRL+Z à la fin de le fichier et le supprime, si possible.Cette opération est exécutée car l'utilisation fseek et ftell pour déplacer dans un fichier qui se termine par un CTRL+Z, peut faire comporter fseek incorrectement près de la fin de le fichier.

En outre, en mode texte, des combinaisons de saut de ligne-retour de chariot sont traduites en sauts de ligne unique sur l'entrée, et les caractères de saut de ligne sont traduits aux combinaisons de saut de ligne-retour de chariot dans la sortie.Lorsqu'une fonction Unicode stream-I/O exécute en mode texte (par défaut), la source ou il est supposé que le flux de données de destination est une séquence de caractères multioctets.Par conséquent, les fonctions de flot- entrée Unicode convertissent des caractères multioctets aux caractères larges (comme si par un appel à la fonction d' mbtowc ).Pour la même raison, les fonctions de flot- sortie Unicode convertissent des caractères larges aux caractères multioctets (comme si par un appel à la fonction d' wctomb ).

b
Ouvrez en mode (non traduit) binaire ; les traductions impliquant des caractères de retour chariot/saut de ligne sont supprimées.

Si t ou b n'est pas donné dans mode, à l'état de interprétation par défaut est défini par la variable globale _fmode.Si t ou b est préfixé à l'argument, la fonction échoue et retourne NULL.

Pour plus d'informations sur l'utilisation des modes de texte et binaire en Unicode et stream-I/O multioctets, consultez E/S de fichier du mode de texte et binaire et l' E/S de flux de données Unicode dans des modes de texte et binaire.

c
Activez la balise de validation pour filename associé afin que le contenu de la mémoire tampon de fichier est écrit directement sur le disque si fflush ou _flushall est appelé.
n
Réinitialisez la balise de validation pour filename associé à la « -- sans validation. » Valeur par défaut.Il substitue également l'indicateur global de validation si vous liez votre programme avec COMMODE.OBJ.La valeur par défaut globale de balise de validation est « -- sans validation » sauf si vous joindre explicitement votre programme avec COMMODE.OBJ (consultez Options de lien).
N
Spécifie que le fichier n'est pas héritée par les processus enfant.
S
Spécifie que la mise en cache est optimisé pour, mais pas limité à, un accès séquentiel à partir de le disque.
R
Spécifie que la mise en cache est optimisé pour, mais pas limité à, l'accès aléatoire à partir de le disque.
T
Spécifie un fichier comme temporaire.Si possible, il n'est pas vidé sur le disque.
D
Spécifie un fichier comme temporaire.Il est supprimé lorsque le dernier pointeur de fichier est fermé.
ccs=ENCODING
Spécifiez le jeu de caractères codés à utiliser (UTF-8, UTF-16LE, et UNICODE) pour ce fichier.Laissez ce n'est pas spécifié si vous souhaitez l'encodage ANSI.

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

Caractères dans la chaîne d'état	Valeur équivalente d' oflag pour _open/_sopen
a	_O_WRONLY \| _O_APPEND (généralement _O_WRONLY \| _O_CREAT \|_O_APPEND)
a+	_O_RDWR \| _O_APPEND (généralement _O_RDWR \| _O_APPEND \| _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (généralement _O_WRONLY \|_O_CREAT \| _O_TRUNC)
w+	_O_RDWR (généralement _O_RDWR \| _O_CREAT \| _O_TRUNC)
b	_O_BINARY
t	_O_TEXT
c	Aucun
n	Aucun
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 d' rb, n'avez pas besoin de déplacer votre code, et le comptez lire le nombre de le fichier et/ou ne vous inquiétez pas de performances réseau, les fichiers Win32 mappés en mémoire peuvent également être une option.

Configuration requise

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

Pour des informations de compatibilité supplémentaires, consultez l' Compatibilité dans l'introduction.

Bibliothèques

Toutes les versions d' Bibliothèques runtime C.

c, n, et les options d' tmode sont des extensions Microsoft pour fopen_s et _fdopen et ne doivent pas être utilisés où la portabilité ANSI est souhaitée.

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" 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 );
}