fopen, _wfopen

Abre un archivo. Existen versiones más seguras de estas funciones que realizan una validación adicional de los parámetros y devuelven códigos de error: consulte fopen_s, _wfopen_s.

Sintaxis

FILE *fopen(
   const char *filename,
   const char *mode
);
FILE *_wfopen(
   const wchar_t *filename,
   const wchar_t *mode
);

Parámetros

filename
Nombre de archivo.

mode
Tipo de acceso habilitado.

Valor devuelto

Cada una de estas funciones devuelve un puntero al archivo abierto. Un valor de puntero null indica un error. Si filename o mode son NULL o una cadena vacía, estas funciones inician el controlador de parámetros no válidos, que se describe en Parameter Validation. Si la ejecución puede continuar, estas funciones devuelven NULL y establecen errno en EINVAL.

Para obtener más información, veaerrno, _doserrno, _sys_errlisty _sys_nerr.

Comentarios

La fopen función abre el archivo especificado por filename. De forma predeterminada, una cadena estrecha filename se interpreta mediante la página de códigos ANSI (CP_ACP). En las aplicaciones de escritorio de Windows, se puede cambiar a la página de códigos del OEM (CP_OEMCP) con la función SetFileApisToOEM. Puede usar la AreFileApisANSI función para determinar si filename se interpreta mediante la página de códigos OEM predeterminada del sistema o ANSI. _wfopen es una versión con caracteres anchos de fopen; los argumentos a _wfopen son cadenas de caracteres anchos. De lo contrario, los objetos _wfopen y fopen se comportan de forma idéntica. Si solo se usa _wfopen, no afectará al juego de caracteres codificado que se use en la secuencia del archivo.

fopen acepta las rutas válidas en el sistema de archivos en el momento de la ejecución; fopen 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. Al construir rutas de acceso para fopen, asegúrese de que las unidades, las rutas de acceso o los recursos compartidos de red estén disponibles en el entorno de ejecución. Puede usar barras diagonales (/) o barras diagonales inversas (\) como separadores de directorio en una ruta de acceso.

Compruebe siempre el valor devuelto para ver si el puntero es NULL antes de realizar cualquier operación posterior en el archivo. Si se produce un error, se establece la variable errno global y se puede usar para obtener información de error específica. 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 admite secuencias de archivo Unicode. Para abrir un archivo Unicode, pase un indicador de ccs=encoding que especifica la codificación deseada a fopen, como sigue:

FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");

Los valores permitidos para ccs la codificación son UNICODE, UTF-8y UTF-16LE.

Cuando un archivo se abre en modo Unicode, las funciones de entrada traducen los datos leídos de dicho archivo a datos UTF-16 almacenados como de tipo wchar_t. Las funciones que escriben en un archivo abierto en modo Unicode esperan que haya búferes que contengan datos UTF-16 almacenados como de tipo wchar_t. Si el archivo está codificado como UTF-8, los datos UTF-16 se convierten a UTF-8 al escribirse. El contenido con codificación UTF-8 del archivo se traslada a UTF-16 al leerse. Si se trata de leer o escribir un número impar de bytes en el modo Unicode, se producirá un error de validación de parámetros . Para leer o escribir datos almacenados en el programa como UTF-8, use un modo de archivo binario o de texto en lugar de un modo Unicode. Cualquier conversión de codificación que sea necesaria es su responsabilidad.

Si el archivo ya existe y se abre para leer o añadir, cualquier marca de orden de bytes (BOM) en el archivo determina la codificación. La codificación BOM tiene prioridad sobre la codificación especificada por la ccs marca . 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 ).

La tabla siguiente resume los modos que se utilizan para los distintos marcadores de ccs especificados en fopen y las marcas de orden de bytes en el archivo.

Codificaciones utilizadas basadas en el indicador de ccs y BOM

Marca deccs	Ninguna BOM (o archivo nuevo)	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

Los archivos abiertos para escribir en el modo Unicode tienen una BOM escriba automáticamente.

Si mode es a, ccs=encoding para algún valor encoding, fopen intenta primero abrir el archivo usando el acceso tanto de lectura como de escritura. Si esta acción tiene éxito, la función lee la lista de materiales para determinar la codificación del archivo. Si se produce un error, la función usa la codificación predeterminada para el archivo. En cualquier caso, fopen vuelve a abrir el archivo mediante acceso de solo escritura. (Este comportamiento solo se aplica al modo "a", no al modo "a+").

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tfopen	fopen	fopen	_wfopen

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

mode	Acceder
"r"	Abre para lectura. Si el archivo no existe o no se encuentra, la llamada fopen 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 el tipo de acceso de "a+" , todas las operaciones de escritura aparecen al final del archivo. El puntero de archivo se puede mover mediante fseek o rewind, pero se desplaza siempre al final del archivo antes de que se realice cualquier operación de escritura. Por consiguiente, los datos existentes no pueden sobrescribirse.

El modo de "a" no quita el marcador EOF antes de que se anexe al archivo. Una vez realizado el anexado, el comando TYPE de MS-DOS solo muestra los datos hasta el marcador EOF original, y no los datos anexados al archivo. Antes de que se anexe al archivo, el modo "a+" elimina el marcador EOF. Después de anexar, 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 habilitan la lectura y la escritura (se dice que el archivo está abierto para su “actualización”). Sin embargo, cuando cambie de lectura a la escritura, la operación de entrada debe encontrar un marcador EOF. Si no hay ningún EOF, debe utilizar una llamada intermedia a una función de posición del archivo. Las funciones de posición de archivo son fsetpos, fseeky rewind. Cuando cambie de escritura a lectura, debe utilizar una llamada intermedia a fflush o una función de posicionamiento del archivo.

Además de los valores anteriores, los caracteres siguientes se pueden anexar a mode para especificar el modo de traducción de 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. Además, CTRL+Z se interpreta como carácter de final 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 de texto, CTRL+Z se interpreta como un carácter EOF en la entrada. En los archivos que se abren para lectura y escritura mediante "a+", fopen comprueba si hay unaCTRL+ 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 conCTRL+ Z puede provocar fseek que se comporten incorrectamente cerca del final del archivo.

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. Por consiguiente, las funciones de entrada y flujo de Unicode convierten los caracteres multibyte en caracteres anchos (como si por una llamada a la función de 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 más información sobre cómo utilizar los modos binario y de texto en Unicode y la E/S de flujo multibyte, vea Text and Binary Mode File I/O y E/S de secuencias Unicode en los modos binario y de texto.

Se pueden anexar las siguientes opciones a mode para especificar más comportamientos.

Modificador mode	Comportamiento
x	Obliga a la función a producir un error si filename ya existe. Solo se puede usar con los especificadores "w" o "w+".
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 global de confirmación si vincula 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=encoding	Especifica el juego de caracteres codificado que se va a usar (uno de UTF-8, UTF-16LE o UNICODE) para este archivo. Deje sin especificar si desea la codificación ANSI. Esta marca está separada de las marcas que la preceden por una coma (,). Por ejemplo: FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");

Caracteres válidos para la mode cadena que se usa en fopen y _fdopen corresponden a oflag argumentos que se usan en _open y _sopen, como se indica a continuación.

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)
x	_O_EXCL
c	Ninguno
n	Ninguno
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 usa el modo rb, no tiene que transportar código y espera leer la mayor parte de un archivo grande o no le preocupa el rendimiento de la red, también puede considerar si usar archivos Win32 asignados con memoria como 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.

Las copciones , n, R, S, t, Ty Dmode son extensiones de Microsoft para fopen y _wfopen y no deben usarse cuando quiera portabilidad ANSI.

Requisitos

Función	Encabezado necesario
fopen	<stdio.h>
_wfopen	<stdio.h> o <wchar.h>

_wfopen es una extensión de Microsoft. Para obtener más información sobre la compatibilidad, vea Compatibilidad.

Las opciones c, n, t, S, R, Ty Dmode son extensiones de Microsoft para fopen y _fdopen y no deben utilizarse cuando se desee la portabilidad ANSI.

Ejemplo 1

El siguiente programa abre dos archivos. Utiliza fclose para cerrar el primer archivo y _fcloseall para cerrar todos los archivos restantes.

// crt_fopen.c
// compile with: /W3
// 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 )
{
   int numclosed;

   // Open for read (will fail if file "crt_fopen.c" does not exist)
   if( (stream  = fopen( "crt_fopen.c", "r" )) == NULL ) // C4996
   // Note: fopen is deprecated; consider using fopen_s instead
      printf( "The file 'crt_fopen.c' was not opened\n" );
   else
      printf( "The file 'crt_fopen.c' was opened\n" );

   // Open for write
   if( (stream2 = fopen( "data2", "w+" )) == NULL ) // C4996
      printf( "The file 'data2' was not opened\n" );
   else
      printf( "The file 'data2' was opened\n" );

   // Close stream if it is not NULL
   if( stream)
   {
      if ( fclose( stream ) )
      {
         printf( "The file 'crt_fopen.c' was not closed\n" );
      }
   }

   // All other files are closed:
   numclosed = _fcloseall( );
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );
}

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

Ejemplo 2

El siguiente programa crea un archivo (o sobrescribe uno si existe), en el modo de texto con codificación Unicode. A continuación, escribe dos cadenas en el archivo y cierra el archivo. El resultado es un archivo denominado _wfopen_test.xml, que contiene los datos de la sección de salida.

// crt__wfopen.c
// compile with: /W3
// This program creates a file (or overwrites one if
// it exists), in text mode using Unicode encoding.
// It then writes two strings into the file
// and then closes the file.

#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <wchar.h>

#define BUFFER_SIZE 50

int main(int argc, char** argv)
{
    wchar_t str[BUFFER_SIZE];
    size_t  strSize;
    FILE*   fileHandle;

    // Create an the xml file in text and Unicode encoding mode.
    if ((fileHandle = _wfopen( L"_wfopen_test.xml",L"wt+,ccs=UNICODE")) == NULL) // C4996
    // Note: _wfopen is deprecated; consider using _wfopen_s instead
    {
        wprintf(L"_wfopen failed!\n");
        return(0);
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"<xmlTag>\n");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"</xmlTag>");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Close the file.
    if (fclose(fileHandle))
    {
        wprintf(L"fclose failed!\n");
    }
    return 0;
}

Consulte también

E/S de secuencia
Interpretación de secuencias de caracteres multibyte
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode
_sopen, _wsopen