Compartir por

fopen_s, _wfopen_s

  • Artigo

Abre un archivo. Estas versiones de , _wfopentienen mejoras defopen seguridad, como se describe en Características de seguridad de CRT.

Sintaxis

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

Parámetros

pFile
Puntero al puntero de archivo que recibe el puntero al archivo abierto.

filename
Nombre del archivo que se va a abrir.

mode
Tipo de acceso permitido.

Valor devuelto

Devuelve cero si se ejecuta correctamente; devuelve un código de error si se produce un error. Para obtener más información sobre estos códigos de error, vea errno, _doserrno, _sys_errlist y _sys_nerr.

Condiciones del error

pFile filename mode Valor devuelto Contenido de pFile
NULL cualquiera cualquiera EINVAL sin cambios
cualquiera NULL cualquiera EINVAL sin cambios
cualquiera cualquiera NULL EINVAL sin cambios

Comentarios

Las funciones fopen_s y _wfopen_s no pueden abrir un archivo para compartirlo. Si necesita compartir el archivo, use _fsopen o _wfsopen con la constante de modo de uso compartido adecuada; por ejemplo, use _SH_DENYNO para compartir con permisos de lectura y escritura.

La fopen_s función abre el archivo especificado por filename. _wfopen_s es una versión de caracteres anchos de fopen_s y los argumentos para _wfopen_s son cadenas de caracteres anchos. _wfopen_s y fopen_s se comportan de forma idéntica, de lo contrario.

fopen_s acepta las rutas válidas en el sistema de archivos en el momento de la ejecución; fopen_s acepta las rutas UNC y las rutas que requieren unidades de red asignadas siempre y cuando el sistema que ejecuta el código tenga acceso al recurso compartido o a la unidad asignada en el momento de la ejecución. Cuando se construyen las rutas de fopen_s, no asuma nada sobre la disponibilidad de unidades, rutas o recursos compartidos de red en el entorno de ejecución. Puede usar barras diagonales (/) o barras diagonales inversas (\) como separadores de directorio en una ruta de acceso.

Estas funciones validan sus parámetros. Si pFile, filenameo mode es un puntero nulo, estas funciones generan una excepción de parámetro no válida, como se describe en Validación de parámetros.

Compruebe siempre el valor devuelto para ver si la función se realizó correctamente antes de llevar a cabo cualquier otra operación en el archivo. Si se produce un error, se devuelve el código de error y se establece la variable errno global. Para obtener más información, veaerrno, _doserrno, _sys_errlisty _sys_nerr.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiarlo, consulte Estado global en CRT.

Compatibilidad con Unicode

fopen_s admite secuencias de archivo Unicode. Para abrir un archivo Unicode nuevo o ya creado, pase una marca ccs que especifique la codificación elegida a fopen_s; por ejemplo:

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

Los valores permitidos para la marca ccs son UNICODE, UTF-8 y UTF-16LE. Si no se especifica ningún valor para ccs, fopen_s usa la codificación ANSI.

Si el archivo ya existe y está abierto para lectura o anexión, la marca de orden de bytes (BOM) determina la codificación, siempre que esté presenten en el archivo. La codificación de BOM tiene prioridad sobre la codificación especificada por la marca de ccs. La codificación de ccs solo se usa cuando no hay BOM presente o el archivo es nuevo.

Nota:

La detección de BOM solo se aplica a los archivos abiertos en modo Unicode (es decir, pasando el indicador de ccs).

En la tabla siguiente se resumen los modos de diferentes valores de marca ccs que se especifican en fopen_s y de las marcas de orden de bytes en el archivo.

Codificaciones usadas en función de la marca ccs y BOM

Marca deccs Ninguna BOM (o archivo nuevo) BOM: UTF-8 BOM: UTF-16
UNICODE UTF-8 UTF-8 UTF-16LE
UTF-8 UTF-8 UTF-8 UTF-16LE
UTF-16LE UTF-16LE UTF-8 UTF-16LE

En los archivos que se abren para escribir en el modo Unicode se escribe una BOM automáticamente.

Si mode es "a, ccs=UNICODE", "a, ccs=UTF-8" o "a, ccs=UTF-16LE", fopen_s primero intenta abrir el archivo con acceso tanto de lectura como de escritura. Si la operación se realiza correctamente, la función lee la BOM para determinar la codificación del archivo; si se produce un error, la función usa la codificación predeterminada del archivo. En cualquier caso, fopen_s abre de nuevo el archivo con acceso de solo escritura. (Este comportamiento solo se aplica al modo a, no al modo a+).

La cadena de caracteres mode especifica el tipo de acceso solicitado para el archivo, como se muestra a continuación:

mode Access
"r" Abre para lectura. Si el archivo no existe o no se encuentra, la llamada fopen_s genera un error.
"w" Abre un archivo vacío para escritura. Si el archivo especificado existe, se destruye su contenido.
"a" Abre para escritura al final del archivo (anexo) sin eliminar el marcador de fin de archivo (EOF) antes de que se escriban nuevos datos en el archivo. Crea el archivo si no existe.
"r+" Abre para lectura y escritura. El archivo debe existir.
"w+" Abre un archivo vacío para lectura y escritura. Si el archivo existe, se destruye su contenido.
"a+" Se abre para lectura y anexado. La operación de anexado incluye la eliminación del marcador EOF antes de que los nuevos datos se escriban en el archivo. El marcador EOF no se restablece una vez completada la escritura. Crea el archivo si no existe.

Cuando un archivo se abre mediante el tipo de acceso de "a" o de "a+", todas las operaciones de escritura aparecen al final del archivo. El puntero de archivo se puede recolocar mediante fseek o rewind, pero siempre se vuelve a colocar al final del archivo antes de que se lleve a cabo cualquier operación de escritura, de modo que los datos existentes no se puedan sobrescribir.

El modo "a" no quita el marcador EOF antes de que se anexe contenido al archivo. Una vez terminado la anexión, el comando TYPE de MS-DOS solo muestra los datos hasta el marcador EOF original, no los datos anexados al archivo. El modo "a+" quita el marcador EOF antes de que se anexe contenido al archivo. Después de la anexión, el comando TYPE de MS-DOS muestra todos los datos del archivo. El "a+" modo es necesario para anexar a un archivo de secuencia que finaliza con elCTRL+ marcador Z EOF.

Cuando se especifica el tipo de acceso "r+", "w+" o "a+", se permiten tanto la lectura como la escritura. (Se dice que el archivo está abierto para "update"). Sin embargo, al cambiar de lectura a escritura, la operación de entrada debe cruzarse con un marcador EOF. Si no hay ningún marcador EOF, debe usar una llamada intermedia a una función de posicionamiento de archivo. Las funciones de posición de archivo son fsetpos, fseek y rewind. Cuando cambie de escritura a lectura, debe usar una llamada intermedia a fflush o una función de posición del archivo.

A partir de C11, puede anexar "x" a "w" o "w+" para provocar que se produzca un error en la función si el archivo existe en lugar de sobrescribirlo.

Además de los valores anteriores, se pueden incluir los siguientes caracteres en mode para especificar el modo de traducción para los caracteres de nueva línea:

Modificador mode Modo de traducción
t Abra en modo de texto (traducido). Las combinaciones de retorno de carro (CR-LF) se traducen en fuentes de línea única (LF) en caracteres de entrada y LF se traducen a combinaciones CR-LF en la salida. CTRL+Z se interpreta como un carácter de fin de archivo en la entrada.
b Abra en modo binario (sin traducir); las traducciones que implican los caracteres de retorno de carro y avance de línea se suprimen.

En el modo CTRL+de texto (traducido), Z se interpreta como un carácter de fin de archivo en la entrada. En el caso de los archivos abiertos para lectura y escritura con "a+", fopen_s comprueba si hay una+CTRL Z al final del archivo y la quita, si es posible. Se quita porque usar fseek y ftell mover dentro de un archivo que termina con unaCTRL+ Z, puede provocar fseek que se comporte incorrectamente cerca del final del archivo.

Además, en este modo, las combinaciones de retorno de carro-avance de línea (CRLF) se convierten en avances de una línea (LF) en la entrada, y los caracteres de LF se convierten en combinaciones de CRLF en la salida. Cuando una función de E/S de flujo Unicode funciona en el modo de texto (valor predeterminado), se asume que el flujo de origen o de destino son una secuencia de caracteres multibyte. Las funciones de entrada y flujo de Unicode convierten los caracteres de varios bytes en caracteres anchos (como por una llamada a la función mbtowc). Por la misma razón, las funciones de salida y flujo Unicode convierten los caracteres anchos en caracteres multibyte (como si se realizara una llamada a la función de wctomb ).

Si no se especifica t o b en mode, el modo de traducción predeterminado lo define la variable global _fmode. Si se agrega t o b como prefijo al argumento, se produce un error en la función y devuelve NULL.

Para obtener más información sobre el uso de modos binarios y de texto en E/S de secuencias Unicode y multibyte, vea E/S de archivos de modo binario y texto e E/S de secuencias Unicode en modos binarios y de texto.

Modificador mode Comportamiento
c Habilite la marca de confirmación para el filename asociado para que el contenido del búfer del archivo se escriba directamente en disco si se llama a fflush o a _flushall .
n Restablezca la marca de confirmación para el filename asociado a "no-commit". Esta marca es la predeterminada. También invalida la marca de confirmación global si enlaza el programa a COMMODE.OBJ. El valor predeterminado de la marca de confirmación global es "sin confirmación", a menos que vincule explícitamente el programa con COMMODE.OBJ (consulte Opciones de vínculo).
N Especifica que el archivo no se hereda mediante procesos secundarios.
S Especifica que el almacenamiento en caché está optimizado para el acceso secuencial (pero no restringido a este) desde el disco.
R Especifica que el almacenamiento en caché está optimizado para el acceso aleatorio (pero no restringido a este) desde el disco.
T Especifica un archivo que no se escribe en el disco a menos que la presión de memoria lo requiera.
D Especifica un archivo temporal que se elimina cuando se cierra el último puntero de archivo.
ccs=UNICODE Especifica UNICODE como el juego de caracteres codificado que se usará para este archivo. Deje sin especificar si desea la codificación ANSI.
ccs=UTF-8 Especifica UTF-8 como el juego de caracteres codificado que se usará para este archivo. Deje sin especificar si desea la codificación ANSI.
ccs=UTF-16LE Especifica UTF-16LE como el juego de caracteres codificado que se usará para este archivo. Deje sin especificar si desea la codificación ANSI.

Los caracteres válidos para la cadena mode que se usa en fopen_s y _fdopen corresponden a los argumentos oflag que se usan en _open y _sopen de la manera siguiente.

Caracteres de la cadena mode Valor oflag equivalente para _open/_sopen
a _O_WRONLY | _O_APPEND (normalmente _O_WRONLY | _O_CREAT | _O_APPEND)
a+ _O_RDWR | _O_APPEND (normalmente _O_RDWR | _O_APPEND | _O_CREAT)
R _O_RDONLY
r+ _O_RDWR
w _O_WRONLY (normalmente _O_WRONLY | _O_CREAT | _O_TRUNC)
w+ _O_RDWR (normalmente **_O_RDWR | _O_CREAT | _O_TRUNC)
b _O_BINARY
t _O_TEXT (traducido)
c None
n None
D _O_TEMPORARY
R _O_RANDOM
S _O_SEQUENTIAL
T _O_SHORTLIVED
ccs=UNICODE _O_WTEXT
ccs=UTF-8 _O_UTF8
ccs=UTF-16LE _O_UTF16

Las copciones , n, R, S, t, Ty D mode son extensiones de Microsoft para fopen_s y _wfopen_s y no deben usarse cuando quiera portabilidad ANSI.

Si usa el modo rb y no necesita trasladar el código, espera leer una gran parte del archivo o no le preocupa el rendimiento de la red, los archivos Win32 asignados a memoria pueden ser una opción.

Con respecto a T y D:

  • T evita escribir el archivo en disco siempre que la presión de memoria no la requiera. Para obtener más información, vea FILE_ATTRIBUTE_TEMPORARY en Constantes de atributos de archivo y también esta entrada de blog Es solo temporal.
  • D especifica un archivo normal que se escribe en el disco. La diferencia es que se elimina automáticamente cuando se cierra. Puede combinar TD para obtener ambas semánticas.

Requisitos

Función Encabezado necesario Encabezado C++
fopen_s <stdio.h> <cstdio>
_wfopen_s <stdio.h> o <wchar.h> <cstdio>

Para obtener más información sobre el cumplimiento de los estándares y las convenciones de nomenclatura de la biblioteca de runtime de C, vea Compatibilidad.

Asignaciones de rutinas de texto genérico

Rutina <tchar.h> _UNICODE y _MBCS no definidos _MBCS definido _UNICODE definido
_tfopen_s fopen_s fopen_s _wfopen_s

Bibliotecas

Todas las versiones de las bibliotecas en tiempo de ejecución de C.

Ejemplo

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

Vea también

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