Standard I/O

This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Functions

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 (...)

All processes have input and output channels by default, without the need to create them explicitly. By channels we mean streams or data flows.

Use bstd_printf to write text to standard output.
Use bstd_read to read bytes from standard input.

Each running process has three standard communication channels:

stdin: data input. The process will read data that comes from outside.
stdout: data output. The process will write results on this channel.
stderr: error output. The process will write on this channel information regarding errors.

It's like having three perpetually open files where the program can read and write without limits. When we execute a process from the Console or the Terminal, stdin automatically connects to the keyboard and stdout/stderr to the screen (Figure 1). However, these standard channels can be redirected to use files as input sources or output destinations:

1
2
3

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

Scheme showing the standard input/output channels of a process. — Figure 1: Executing a process from the Terminal.

In this code snippet, the result of the command dir (ls in Unix) has been redirected to the file out.txt, so we will not see anything on the screen. On the other hand, the command sort it does not wait for the user to enter through the keyboard. Simply taking the file out.txt, sorting its lines. Therefore, whenever we write applications on the command line, we should conveniently use these standard channels without making presumptions from where the information processed by the application comes from or where it goes.

bstd_sprintf ()

Write a string with the printf format in a memory buffer.

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

str	Pointer to the buffer where the result will be written. It will end in a null character `'\0'`.
size	Size of `str` in bytes.
format	String with the printf-like format with a variable number of parameters.
...	Arguments or variables of printf.

Return

The number of bytes written, not including the null character '\0'.

Remarks

It is a safe function and will not write more than size bytes. To obtain the necessary size of str, call this function with str=NULL and size=0.

bstd_vsprintf ()

Like bstd_sprintf but with the list of arguments already resolved.

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

str	Pointer to the buffer where the result will be written. It will end in a null character `'\0'`.
size	Size of `str` in bytes.
format	String with the printf-like format with a variable number of parameters.
args	Arguments.

Return

The number of bytes written, not including the null character '\0'.

Remarks

It is a safe function and will not write more than size bytes.

bstd_printf ()

Writes a formatted string in the standard output (stdout). It is equivalent to the function printf from the standard library.

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

format	String with the printf-like format with a variable number of parameters.
...	Arguments or variables of printf.

Return

The number of bytes written in stdout.

bstd_eprintf ()

Writes a formatted string in the error output (stderr).

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

format	String with the printf-like format with a variable number of parameters.
...	Arguments or variables of printf.

Return

The number of bytes written in stderr.

bstd_writef ()

Write a string C UTF8 in the standard output (stdout).

uint32_t
bstd_writef(const char_t *str);

str	String C UTF8 ending in null character `'\0'`.

Return

The number of bytes written in stdout.

bstd_ewritef ()

Write a string C UTF8 on the error output (stderr).

uint32_t
bstd_ewritef(const char_t *str);

str	String C UTF8 ending in null character `'\0'`.

Return

The number of bytes written in stderr.

bstd_read ()

Read data from standard input stdin.

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

data	Buffer where the read data will be written.
size	The number of maximum bytes to read (buffer size).
rsize	Receive the number of bytes actually read. Can be `NULL`.

Return

TRUE if data has been read. FALSE if any error has occurred.

Remarks

Standard stream implements high-level functions for reading/writing on standard channels.

bstd_write ()

Write data in the standard output stdout.

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

data	Buffer that contains the data to write.
size	The number of bytes to write.
wsize	It receives the number of bytes actually written. Can be `NULL`.

Return

TRUE if data has been written. FALSE if any error has occurred.

Remarks

Standard stream implements high-level functions for reading/writing on standard channels.

bstd_ewrite ()

Write data in the error output stderr.

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

data	Buffer that contains the data to write.
size	The number of bytes to write.
wsize	It receives the number of bytes actually written. Can be `NULL`.

Return

TRUE if data has been written. FALSE if any error has occurred.

Remarks

Standard stream implements high-level functions for reading/writing on standard channels.