E/S Estándar

Cabecera

#include <sewer/bstd.h>

Funciones

uint32_t	bstd_sprintf (...)
uint32_t	bstd_vsprintf (...)
uint32_t	bstd_printf (...)
uint32_t	bstd_eprintf (...)
uint32_t	bstd_writef (...)
uint32_t	bstd_ewritef (...)
bool_t	bstd_read (...)
bool_t	bstd_write (...)
bool_t	bstd_ewrite (...)

Todos los procesos disponen de canales de entrada y salida por defecto, sin necesidad de crearlos explícitamente. Por canales entendemos streams o flujos de datos.

Utiliza bstd_printf para escribir texto en las salida estándar.
Utiliza bstd_read para leer bytes desde la entrada estándar.

Cada proceso en ejecución tiene tres canales de comunicación estándar:

stdin: entrada de datos. El proceso leerá datos que le llegan desde el exterior.
stdout: salida de datos. El proceso escribirá resultados en este canal.
stderr: salida de errores. El proceso escribirá en este canal información referente a errores.

Es como tener tres archivos perpetuamente abiertos donde el programa puede leer y escribir sin límites. Cuando ejecutamos un proceso desde la Consola o el Terminal, stdin se conecta automáticamente al teclado y stdout/stderr a la pantalla (Figura 1). No obstante, estos canales estándar se pueden redirigir para usar archivos como fuentes de entrada o destinos de salida:

1
2
3

dir > out.txt
ls > out.txt
sort < out.txt

Esquema que muestra los canales entrada/salida estándar de un proceso. — Figura 1: Ejecutando un proceso desde el Terminal.

En este fragmento de código, el resultado del comando dir (ls en Unix) se ha redirigido al archivo out.txt, por lo que no veremos nada por pantalla. Por otro lado, el comando sort no espera la entrada del usuario por el teclado. Simplemente la toma del archivo out.txt, ordenando sus líneas. Por tanto, siempre que escribamos aplicaciones en línea de comandos, deberemos utilizar convenientemente estos canales estándar sin hacer presunciones desde donde viene o hacia donde va la información tratada por la aplicación.

bstd_sprintf ()

Escribe una cadena con formato del printf en un búfer de memoria.

uint32_t
bstd_sprintf(char_t *str,
             const uint32_t size,
             const char_t *format,
             ...);

str	Puntero al búfer donde será escrito el resultado. Terminará en carácter nulo `'\0'`.
size	Tamaño de `str` en bytes.
format	Cadena con el formato printf con un número variable de parámetros.
...	Argumentos o variables del printf.

Retorna

El número de bytes escritos, sin incluir el carácter nulo '\0'.

Observaciones

Es una función segura y no escribirá más de size bytes. Para obtener el tamaño necesario de str, llamar a esta función con str=NULL y size=0.

bstd_vsprintf ()

Igual que bstd_sprintf pero con la lista de argumentos ya resuelta.

uint32_t
bstd_vsprintf(char_t *str,
              const uint32_t size,
              const char_t *format,
              va_list args);

str	Puntero al búfer donde será escrito el resultado. Terminará en carácter nulo `'\0'`.
size	Tamaño de `str` en bytes.
format	Cadena con el formato tipo-printf con un número variable de parámetros.
args	Argumentos.

Retorna

El número de bytes escritos, sin incluir el carácter nulo '\0'.

Observaciones

Es una función segura y no escribirá más de size bytes.

bstd_printf ()

Escribe una cadena con formato en la salida estándar (stdout). Es equivalente a la función printf de la librería estándar.

uint32_t
bstd_printf(const char_t *format,
            ...);

format	Cadena con el formato tipo-printf con un número variable de parámetros.
...	Argumentos o variables del printf.

Retorna

El número de bytes escritos en stdout.

bstd_eprintf ()

Escribe una cadena con formato en la salida de error (stderr).

uint32_t
bstd_eprintf(const char_t *format,
             ...);

format	Cadena con el formato tipo-printf con un número variable de parámetros.
...	Argumentos o variables del printf.

Retorna

El número de bytes escritos en stderr.

bstd_writef ()

Escribe una cadena C UTF 8 en la salida estándar (stdout).

uint32_t
bstd_writef(const char_t *str);

str	Cadena C UTF8 terminada en carácter nulo `'\0'`.

Retorna

El número de bytes escritos en stdout.

bstd_ewritef ()

Escribe una cadena C UTF 8 en la salida de error (stderr).

uint32_t
bstd_ewritef(const char_t *str);

str	Cadena C UTF8 terminada en carácter nulo `'\0'`.

Retorna

El número de bytes escritos en stderr.

bstd_read ()

Lee datos desde la entrada estándar stdin.

bool_t
bstd_read(byte_t *data,
          const uint32_t size,
          uint32_t *rsize);

data	Búfer donde se escribirán los datos leídos.
size	El número de bytes máximos a leer (tamaño del búfer).
rsize	Recibe el número de bytes leídos realmente. Puede ser `NULL`.

Retorna

TRUE si se han leído datos. FALSE si ha ocurrido algún error.

Observaciones

Standard stream implementa funciones de alto nivel para lectura/escritura en canales estándar.

bstd_write ()

Escribe datos en la salida estándar stdout.

bool_t
bstd_write(const byte_t *data,
           const uint32_t size,
           uint32_t *wsize);

data	Búfer que contiene los datos a escribir.
size	El número de bytes a escribir.
wsize	Recibe el número de bytes escritos realmente. Puede ser `NULL`.

Retorna

TRUE si se han escrito datos. FALSE si ha ocurrido algún error.

Observaciones

Standard stream implementa funciones de alto nivel para lectura/escritura en canales estándar.

bstd_ewrite ()

Escribe datos en la salida de error stderr.

bool_t
bstd_ewrite(const byte_t *data,
            const uint32_t size,
            uint32_t *wsize);

data	Búfer que contiene los datos a escribir.
size	El número de bytes a escribir.
wsize	Recibe el número de bytes escritos realmente. Puede ser `NULL`.

Retorna

TRUE si se han escrito datos. FALSE si ha ocurrido algún error.

Observaciones

Standard stream implementa funciones de alto nivel para lectura/escritura en canales estándar.