fopen_s, _wfopen_sfopen_s, _wfopen_s

Ouvre un fichier.Opens a file. Ces versions de fopen, _wfopen intègrent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.These versions of fopen, _wfopen have security enhancements, as described in Security Features in the CRT.

SyntaxeSyntax

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ètresParameters

pFilepFile
Pointeur désignant le pointeur de fichier appelé à recevoir le pointeur vers le fichier ouvert.A pointer to the file pointer that will receive the pointer to the opened file.

filenamefilename
Nom de fichier.Filename.

modemode
Type d'accès autorisé.Type of access permitted.

Valeur de retourReturn Value

Zéro si l'opération a réussi ; code d'erreur en cas de échec.Zero if successful; an error code on failure. Pour plus d’informations sur ces codes d’erreur, consultez, errno, _doserrno, _sys_errlist et _sys_nerr.See errno, _doserrno, _sys_errlist, and _sys_nerr for more information about these error codes.

Conditions d’erreurError Conditions

pFilepFile filenamefilename modemode Valeur de retourReturn Value Contenu de pFileContents of pFile
NULLNULL anyany anyany EINVALEINVAL inchangéunchanged
anyany NULLNULL anyany EINVALEINVAL inchangéunchanged
anyany anyany NULLNULL EINVALEINVAL inchangéunchanged

NotesRemarks

Les fichiers ouverts par fopen_s et _wfopen_s ne peuvent pas être partagés.Files that are opened by fopen_s and _wfopen_s are not sharable. Si vous avez besoin qu’un fichier soit partageable, utilisez _fsopen, _wfsopen avec la constante de mode de partage appropriée, par exemple, _SH_DENYNO pour le partage en lecture/écriture.If you require that a file be sharable, use _fsopen, _wfsopen with the appropriate sharing mode constant—for example, _SH_DENYNO for read/write sharing.

La fonction fopen_s ouvre le fichier spécifié par filename.The fopen_s function opens the file that's specified by filename. _wfopen_s est une version à caractères larges de fopen_s; les arguments de _wfopen_s sont des chaînes à caractères larges._wfopen_s is a wide-character version of fopen_s; the arguments to _wfopen_s are wide-character strings. dans le cas contraire, _wfopen_s et fopen_s se comportent de la même façon._wfopen_s and fopen_s behave identically otherwise.

fopen_s accepte les chemins d’accès qui sont 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 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.fopen_s accepts paths that are valid on the file system at the point of execution; UNC paths and paths that involve mapped network drives are accepted by fopen_s as long as the system that's executing the code has access to the share or mapped network drive at the time of execution. Lorsque vous construisez des chemins d’accès pour fopen_s, ne faites pas de suppositions quant à la disponibilité des lecteurs, chemins d’accès ou partages réseau dans l’environnement d’exécution.When you construct paths for fopen_s, don't make assumptions about the availability of drives, paths, or network shares in the execution environment. Vous pouvez utiliser des barres obliques (/) ou des barres obliques inverses (\) comme séparateurs de répertoire dans un chemin.You can use either forward slashes (/) or backslashes (\) as the directory separators in a path.

Ces fonctions valident leurs paramètres.These functions validate their parameters. Si pFile, filenameou 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.If pFile, filename, or mode is a null pointer, these functions generate an invalid parameter exception, as described in Parameter Validation.

Vérifiez toujours la valeur de retour pour savoir si la fonction a abouti avant d'effectuer d'autres opérations sur le fichier.Always check the return value to see if the function succeeded before you perform any further operations on the file. Si une erreur se produit, le code d’erreur est retourné et la variable globale errno est définie.If an error occurs, the error code is returned and the global variable errno is set. Pour plus d’informations, consultez errno, _doserrno, _sys_errlist et _sys_nerr.For more information, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Prise en charge UnicodeUnicode support

fopen_s prend en charge les flux de fichiers Unicode.fopen_s supports Unicode file streams. Pour ouvrir un fichier Unicode nouveau ou existant, transmettez un indicateur CCS qui spécifie l’encodage souhaité à fopen_s:To open a new or existing Unicode file, pass a ccs flag that specifies the desired encoding to fopen_s:

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

Les valeurs d' encodage autorisées sont Unicode, UTF-8et UTF-16LE.Allowed values of encoding are UNICODE, UTF-8, and UTF-16LE. Si aucune valeur n’est spécifiée pour l' encodage, fopen_s utilise l’encodage ANSI.If there no value is specified for encoding, fopen_s uses ANSI encoding.

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.If the file already exists and is opened for reading or appending, the Byte Order Mark (BOM), if present in the file, determines the encoding. L’encodage BOM est prioritaire sur l’encodage spécifié par l’indicateur CCS .The BOM encoding takes precedence over the encoding that's specified by the ccs flag. L’encodage CCS est utilisé uniquement quand aucune marque Bom n’est présente ou si le fichier est un nouveau fichier.The ccs encoding is only used when no BOM is present or if the file is a new file.

Notes

La détection BOM s’applique uniquement aux fichiers ouverts en mode Unicode. autrement dit, en passant l’indicateur CCS .BOM-detection only applies to files that are opened in Unicode mode; that is, by passing the ccs flag.

Le tableau suivant récapitule les modes pour différents indicateurs CCS fournis à fopen_s et pour les marques d’ordre d’octet dans le fichier.The following table summarizes the modes for various ccs flags that are given to fopen_s and for Byte Order Marks in the file.

Encodages utilisés selon l'indicateur ccs et la marque BOMEncodings Used Based on ccs Flag and BOM

indicateur CCSccs flag Aucune marque BOM (ou nouveau fichier)No BOM (or new file) BOM UTF-8BOM: UTF-8 BOM UTF-16BOM: UTF-16
UNICODEUNICODE UTF-16LEUTF-16LE UTF-8UTF-8 UTF-16LEUTF-16LE
UTF-8UTF-8 UTF-8UTF-8 UTF-8UTF-8 UTF-16LEUTF-16LE
UTF-16LEUTF-16LE UTF-16LEUTF-16LE UTF-8UTF-8 UTF-16LEUTF-16LE

Une marque BOM est écrite automatiquement dans les fichiers ouverts pour écriture en mode Unicode.Files that are opened for writing in Unicode mode have a BOM written to them automatically.

Si le mode est « a, CCS = Encoding » , fopen_s tente d’abord d’ouvrir le fichier avec un accès en lecture et un accès en écriture.If mode is "a, ccs=encoding", fopen_s first tries to open the file with both read access and write access. 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.If successful, the function reads the BOM to determine the encoding for the file; if unsuccessful, the function uses the default encoding for the file. Dans les deux cas, fopen_s ouvre à nouveau le fichier avec un accès en écriture seule.In either case, fopen_s then re-opens the file with write-only access. (Cela s’applique uniquement à un mode, et non à un + .)(This applies to a mode only, not a+.)

Mappages de routines de texte génériqueGeneric-Text Routine Mappings

Routine TCHAR.HTCHAR.H routine _UNICODE et _MBCS non définis_UNICODE & _MBCS not defined _MBCS défini_MBCS defined _UNICODE défini_UNICODE defined
_tfopen_s_tfopen_s fopen_sfopen_s fopen_sfopen_s _wfopen_s_wfopen_s

Le mode chaîne de caractères spécifie le type d’accès demandé pour le fichier, comme suit.The character string mode specifies the kind of access that's requested for the file, as follows.

modemode AccessAccess
"r""r" Ouvre pour l'accès en lecture.Opens for reading. Si le fichier n’existe pas ou est introuvable, l’appel fopen_s échoue.If the file does not exist or cannot be found, the fopen_s call fails.
"w""w" Ouvre un fichier vide pour l'accès en écriture.Opens an empty file for writing. Si le fichier spécifié existe, son contenu est détruit.If the given file exists, its contents are destroyed.
"a""a" S'ouvre pour écriture à la fin du fichier (ajout) sans supprimer le marqueur de fin de fichier (EOF) avant que de nouvelles données soient écrites dans le fichier.Opens for writing at the end of the file (appending) without removing the end-of-file (EOF) marker before new data is written to the file. Crée le fichier s'il n'existe pas.Creates the file if it does not exist.
"r+""r+" Ouvre pour l'accès en lecture et en écriture.Opens for both reading and writing. Le fichier doit exister.The file must exist.
"w+""w+" Ouvre un fichier vide pour l'accès en lecture et en écriture.Opens an empty file for both reading and writing. Si le fichier existe, son contenu est détruit.If the file exists, its contents are destroyed.
"a+""a+" S'ouvre pour lecture et ajout.Opens for reading and appending. L'opération d'ajout inclut la suppression du marqueur EOF avant que de nouvelles données soient écrites dans le fichier.The appending operation includes the removal of the EOF marker before new data is written to the file. Le marqueur EOF n'est pas restauré une fois l'écriture terminée.The EOF marker is not restored after writing is completed. Crée le fichier s'il n'existe pas.Creates the file if it does not exist.

Lorsqu’un fichier est ouvert à l’aide du type d’accès «a» ou «a +» , toutes les opérations d’écriture se produisent à la fin du fichier.When a file is opened by using the "a" or "a+" access type, all write operations occur at the end of the file. Le pointeur de fichier peut être repositionné à l’aide de fseek ou rembobiner, mais il est toujours redéplacé à la fin du fichier avant toute opération d’écriture, de sorte que les données existantes ne peuvent pas être remplacées.The file pointer can be repositioned by using fseek or rewind, but it's always moved back to the end of the file before any write operation is carried out so that existing data cannot be overwritten.

Le mode «a» ne supprime pas le marqueur EOF avant l’ajout au fichier.The "a" mode does not remove the EOF marker before appending to the file. 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.After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data that's appended to the file. Le mode «a +» supprime le marqueur EOF avant d’ajouter au fichier.The "a+" mode does remove the EOF marker before appending to the file. Après l'ajout, la commande MS-DOS TYPE affiche toutes les données du fichier.After appending, the MS-DOS TYPE command shows all data in the file. Le mode «a +» est requis pour l’ajout à un fichier de flux qui se termine à l’aide du marqueur EOF Ctrl + Z.The "a+" mode is required for appending to a stream file that is terminated by using the CTRL+Z EOF marker.

Quand le type d’accès "r +" , "w +" ou "a +" est spécifié, la lecture et l’écriture sont autorisées.When the "r+", "w+", or "a+" access type is specified, both reading and writing are allowed. (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.(The file is said to be open for "update".) However, when you switch from reading to writing, the input operation must encounter an EOF marker. S'il n'existe aucun marqueur EOF, vous devez faire un appel intermédiaire à une fonction de positionnement de fichier.If there is no EOF, you must use an intervening call to a file-positioning function. Les fonctions de positionnement de fichier sont fsetpos, fseeket Rewind.The file-positioning functions are fsetpos, fseek, and rewind. Quand vous passez de l’écriture à la lecture, vous devez utiliser un appel intermédiaire à fflush ou à une fonction de positionnement de fichier.When you switch from writing to reading, you must use an intervening call to either fflush or to a file-positioning function.

Outre les valeurs ci-dessus, les caractères suivants peuvent être inclus dans le mode pour spécifier le mode de traduction pour les caractères de saut de ligne:In addition to the above values, the following characters can be included in mode to specify the translation mode for newline characters:

modificateur de modemode modifier Mode de traductionTranslation mode
tt Ouvrir en mode texte (traduit).Open in text (translated) mode.
bb Ouvrir en mode binaire (non traduit); les traductions qui impliquent des caractères de retour chariot et de saut de ligne sont supprimées.Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed.

En mode texte (traduit), CTRL + Z est interprété comme un caractère de fin de fichier en entrée.In text (translated) mode, CTRL+Z is interpreted as an end-of-file character on input. Dans les fichiers ouverts en lecture/écriture avec « a + » , FOPEN_S recherche un Ctrl + Z à la fin du fichier et le supprime, si possible.In files opened for reading/writing with "a+", fopen_s checks for a CTRL+Z at the end of the file and removes it, if possible. Cela est dû au fait que l’utilisation de fseek et de 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.This is done because using fseek and ftell to move within a file that ends with a CTRL+Z, may cause fseek to behave improperly near the end of the file.

En outre, en mode texte, les combinaisons retour chariot-saut de ligne sont traduites en flux à ligne unique en entrée, et les caractères de saut de ligne sont traduits en combinaisons retour chariot-saut de ligne en sortie.Also, in text mode, carriage return-line feed combinations are translated into single line feeds on input, and line feed characters are translated to carriage return-line feed combinations on output. 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.When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. Par conséquent, les fonctions d’entrée de flux Unicode convertissent les caractères multioctets en caractères larges (comme après un appel à la fonction mbtowc).Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the mbtowc function). Pour la même raison, les fonctions de flux de sortie Unicode convertissent les caractères larges en caractères multioctets (comme après un appel à la fonction wctomb).For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the wctomb function).

Si t ou b n’est pas spécifié en mode, le mode de traduction par défaut est défini par la variable globale _fmode.If t or b is not given in mode, the default translation mode is defined by the global variable _fmode. Si t ou b est préfixé à l’argument, la fonction échoue et retourne la valeur null.If t or b is prefixed to the argument, the function fails and returns NULL.

Pour plus d’informations sur l’utilisation des modes texte et binaire dans les E/S de flux Unicode et multioctets, consultez E/S de fichier en mode texte et binaire et E/S de flux Unicode en modes texte et binaire.For more information about using text and binary modes in Unicode and multibyte stream-I/O, see Text and Binary Mode File I/O and Unicode Stream I/O in Text and Binary Modes.

modificateur de modemode modifier ComportementBehavior
cc Activez l’indicateur de validation pour le nom de fichier associé afin que le contenu de la mémoire tampon de fichier soit écrit directement sur le disque si fflush ou _flushall est appelé.Enable the commit flag for the associated filename so that the contents of the file buffer are written directly to disk if either fflush or _flushall is called.
nn Réinitialiser l’indicateur de validation pour le nom de fichier associé sur «no-commit».Reset the commit flag for the associated filename to "no-commit." Il s'agit de la valeur par défaut.This is the default. Substitue également l'indicateur de validation global si vous liez votre programme avec COMMODE.OBJ.It also overrides the global commit flag if you link your program with 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).The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ (see Link Options).
NN Indique que le fichier n'est pas hérité par les processus enfants.Specifies that the file is not inherited by child processes.
SS Indique que la mise en cache est optimisée pour, mais non limitée à, l'accès séquentiel à partir du disque.Specifies that caching is optimized for, but not restricted to, sequential access from disk.
RR Indique que la mise en cache est optimisée pour, mais non limitée à, l'accès aléatoire à partir du disque.Specifies that caching is optimized for, but not restricted to, random access from disk.
TT Spécifie un fichier comme temporaire.Specifies a file as temporary. Si possible, il n'est pas vidé sur disque.If possible, it is not flushed to disk.
DD Spécifie un fichier comme temporaire.Specifies a file as temporary. Il est supprimé lorsque le dernier pointeur de fichier est fermé.It is deleted when the last file pointer is closed.
ccs= encodingccs=encoding Spécifie le jeu de caractères codé à utiliser (l’un des UTF-8, UTF-16LEou Unicode) pour ce fichier.Specifies the encoded character set to use (one of UTF-8, UTF-16LE, or UNICODE) for this file. Laissez ce paramètre non spécifié si vous souhaitez bénéficier de l'encodage ANSI.Leave unspecified if you want ANSI encoding.

Les caractères valides pour la chaîne de mode utilisée dans fopen_s et _fdopen correspondent aux arguments Oflag utilisés dans _open et _sopen, comme suit.Valid characters for the mode string used in fopen_s and _fdopen correspond to oflag arguments used in _open and _sopen, as follows.

Caractères dans la chaîne de modeCharacters in mode string Valeur Oflag équivalente pour _open/_sopenEquivalent oflag value for _open/_sopen
aa _O_WRONLY | _O_APPEND (généralement _O_WRONLY | _O_CREAT |* * _O_APPEND * *)_O_WRONLY | _O_APPEND (usually _O_WRONLY | _O_CREAT |** _O_APPEND**)
a+a+ _O_RDWR | _O_APPEND (usually _O_RDWR | _O_APPEND | _O_CREAT )_O_RDWR | _O_APPEND (usually _O_RDWR | _O_APPEND | _O_CREAT )
rr _O_RDONLY_O_RDONLY
r+r+ _O_RDWR_O_RDWR
ww _O_WRONLY (généralement _O_WRONLY | _O_CREAT |* * _O_TRUNC * *)_O_WRONLY (usually _O_WRONLY | _O_CREAT |** _O_TRUNC**)
w+w+ _O_RDWR (usually _O_RDWR | _O_CREAT | _O_TRUNC)_O_RDWR (usually _O_RDWR | _O_CREAT | _O_TRUNC)
bb _O_BINARY_O_BINARY
tt _O_TEXT_O_TEXT
cc AucunNone
nn AucunNone
SS _O_SEQUENTIAL_O_SEQUENTIAL
RR _O_RANDOM_O_RANDOM
TT _O_SHORTLIVED_O_SHORTLIVED
DD _O_TEMPORARY_O_TEMPORARY
ccs=UNICODEccs=UNICODE _O_WTEXT_O_WTEXT
ccs=UTF-8ccs=UTF-8 _O_UTF8_O_UTF8
CCS = UTF-16LEccs=UTF-16LE _O_UTF16_O_UTF16

Si vous utilisez le mode RB , vous n’avez pas besoin de porter votre code et vous vous attendez à lire une grande partie du fichier et/ou ne vous souciez pas des performances réseau, les fichiers Win32 mappés en mémoire peuvent également être une option.If you are using rb mode, won't need to port your code, and expect to read a lot of the file and/or don't care about network performance, memory mapped Win32 files might also be an option.

Configuration requiseRequirements

FonctionFunction En-tête requisRequired header
fopen_sfopen_s <stdio.h><stdio.h>
_wfopen_s_wfopen_s <stdio.h> ou <wchar.h><stdio.h> or <wchar.h>

Pour plus d'informations sur la compatibilité, voir Compatibilité.For additional compatibility information, see Compatibility.

BibliothèquesLibraries

Toutes les versions des bibliothèques Runtime C.All versions of the C run-time libraries.

Les options de mode c, net t sont des extensions Microsoft pour fopen_s et _fdopen et ne doivent pas être utilisées là où la portabilité ANSI est souhaitée.The c, n, and t mode options are Microsoft extensions for fopen_s and _fdopen and should not be used where ANSI portability is desired.

ExempleExample

// 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

Voir aussiSee also

E/S de fluxStream I/O
fclose, _fcloseallfclose, _fcloseall
_fdopen, _wfdopen_fdopen, _wfdopen
ferrorferror
_fileno_fileno
freopen, _wfreopenfreopen, _wfreopen
_open, _wopen_open, _wopen
_setmode_setmode