freopen_s, _wfreopen_s

Artículo
06/09/2015

Reasigna un puntero de archivo. Estas versiones de freopen, _wfreopen tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

errno_t freopen( 
   FILE** pFile,
   const char *path,
   const char *mode,
   FILE *stream 
);
errno_t _wfreopen( 
   FILE** pFile,
   const wchar_t *path,
   const wchar_t *mode,
   FILE *stream 
);

Parámetros

[out] pFile
Puntero al puntero de archivo que la llamada va a proporcionar.
[in] path
Ruta de acceso del nuevo archivo.
[in] mode
Tipo de acceso permitido.
[in] stream
Puntero a la estructura FILE.

Valor devuelto

Cada una de estas funciones devuelve un código de error. Si se produce un error, el archivo original se cierra.

Comentarios

La función freopen_s cierra el archivo asociado actualmente a stream y reasigna stream al archivo especificado por path. _wfreopen_s es una versión con caracteres anchos de _freopen_s; los argumentos de path y mode para _wfreopen_s son cadenas de caracteres anchos. Por lo demás, _wfreopen_s y _freopen_s se comportan de forma idéntica.

Si pFile, path, mode o stream es NULL, o si path es una cadena vacía, estas funciones invocan el controlador de parámetros no válido, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones establecen errno en EINVAL y devuelven EINVAL.

Asignaciones de rutina de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tfreopen_s	freopen_s	freopen_s	_wfreopen_s

freopen_s se suele usar para redirigir los archivos ya abiertos stdin, stdout y stderr a los archivos especificados por el usuario. El nuevo archivo asociado a stream se abre con mode*,* una cadena de caracteres que especifica el tipo de acceso solicitado para el archivo, como se indica a continuación:

"r"
Abre para lectura. Si el archivo no existe o no se encuentra, la llamada de freopen_s produce un error.
"w"
Abre un archivo vacío para escritura. Si el archivo especificado existe, se destruye su contenido.
"a"
Abre para escribir al final del archivo (anexar) sin quitar el marcador EOF antes de escribir nuevos datos en archivo; primero 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 especificado existe, se destruye su contenido.
"a+"
Abre para leer y anexar. La operación para anexar incluye la eliminación del marcador EOF antes de escribir los nuevos datos en el archivo; el marcador se restablece cuando se finaliza la escritura. Primero crea el archivo si no existe.

Use los tipos "w" y "w+" con cuidado, ya que podrían destruir archivos existentes.

Si se abre un archivo con el tipo de acceso "a" o "a+", todas las operaciones de escritura se realizan en el final del archivo. Si bien el puntero de archivo se puede mover mediante fseek o rewind, siempre se desplaza al final del archivo antes de que se realice cualquier operación de escritura. Por consiguiente, los datos existentes no pueden sobrescribirse.

El modo "a" no quita el marcador EOF antes de que se anexe contenido 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. El modo "a+" quita el marcador EOF antes de que se anexe contenido al archivo. Después de anexar, el comando TYPE de MS-DOS muestra todos los datos del archivo. El modo "a+" se requiere para anexar a un archivo de streaming terminado con el marcador EOF CTRL+Z.

Cuando se especifica el tipo de acceso "r+", "w+", o "a+", se permiten la lectura y la escritura (el archivo está abierto para "actualización"). Sin embargo, si se cambia entre lectura y escritura, debe haber una operación intermedia fsetpos, fseek o rewind. Si se desea, se puede especificar la posición actual para la operación fsetpos o fseek. Además de los valores anteriores, uno de los caracteres siguientes se puede incluir en la cadena de mode para especificar el modo de traducción para las nuevas líneas.

t
Abrir en modo de texto (traducido); las combinaciones de retorno de carro–avance de línea (CR-LF) se convierten en caracteres únicos de avance de línea (LF) en la entrada; los caracteres de LF se traducen en combinaciones de CR-LF en la salida. Además, CTRL+Z se interpreta como carácter de final de archivo en la entrada. En archivos abiertos para lectura, o para escritura y lectura, con "a+", la biblioteca en tiempo de ejecución comprueba si hay un CTRL+Z al final del archivo y lo quita, si es posible. Se hace así porque el uso de fseek y ftell para desplazarse por un archivo puede hacer que fseek se comporte de forma incorrecta cerca del final del archivo. La opción t es una extensión de Microsoft que no se debe usar si se desea disponer de portabilidad de ANSI.
b
Abrir en modo binario (sin traducir); las conversiones anteriores se suprimen.

Si no se especifica t o b en mode, el modo de traducción predeterminado está definido por 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 información sobre los modos de texto y binario, vea E/S de archivo de modo de texto y binario.

Requisitos

Función	Encabezado necesario
freopen_s	<stdio.h>
_wfreopen_s	<stdio.h> o <wchar.h>

La consola no se admite en las aplicaciones de Tienda Windows. Se deben redirigir los identificadores estándar de flujo que están asociados a la consola, stdin, stdout y stderr, antes de que las funciones en tiempo de ejecución de C puedan usarlos en aplicaciones de Tienda Windows. Para obtener más información sobre compatibilidad, vea Compatibilidad.

Ejemplo

// crt_freopen_s.c
// This program reassigns stderr to the file
// named FREOPEN.OUT and writes a line to that file.
 
#include <stdio.h>
#include <stdlib.h>

FILE *stream;

int main( void )
{
   errno_t err;
   // Reassign "stderr" to "freopen.out": 
   err = freopen_s( &stream, "freopen.out", "w", stderr );

   if( err != 0 )
      fprintf( stdout, "error on freopen\n" );
   else
   {
      fprintf( stdout, "successfully reassigned\n" ); fflush( stdout );
      fprintf( stream, "This will go to the file 'freopen.out'\n" );
      fclose( stream );
   }
   system( "type freopen.out" );
}