Cross-platform C SDK logo

Cross-platform C SDK

Streams

❮ Back
Next ❯
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.

Water can flow or creep or drip or crash, be water my friend. Bruce Lee


Functions

Stream*stm_from_block (...)
Stream*stm_memory (...)
Stream*stm_from_file (...)
Stream*stm_to_file (...)
Stream*stm_append_file (...)
Stream*stm_socket (...)
voidstm_close (...)
endian_tstm_get_write_endian (...)
endian_tstm_get_read_endian (...)
voidstm_set_write_endian (...)
voidstm_set_read_endian (...)
unicode_tstm_get_write_utf (...)
unicode_tstm_get_read_utf (...)
voidstm_set_write_utf (...)
voidstm_set_read_utf (...)
uint64_tstm_bytes_written (...)
uint64_tstm_bytes_readed (...)
sstate_tstm_state (...)
ferror_tstm_file_err (...)
serror_tstm_sock_err (...)
voidstm_corrupt (...)
String*stm_str (...)
const byte_t*stm_buffer (...)
uint32_tstm_buffer_size (...)
voidstm_write (...)
voidstm_write_char (...)
uint32_tstm_printf (...)
uint32_tstm_writef (...)
voidstm_write_bool (...)
voidstm_write_i8 (...)
voidstm_write_i16 (...)
voidstm_write_i32 (...)
voidstm_write_i64 (...)
voidstm_write_u8 (...)
voidstm_write_u16 (...)
voidstm_write_u32 (...)
voidstm_write_u64 (...)
voidstm_write_r32 (...)
voidstm_write_r64 (...)
voidstm_write_enum (...)
uint32_tstm_read (...)
voidstm_skip (...)
uint32_tstm_read_char (...)
const char_t*stm_read_chars (...)
const char_t*stm_read_line (...)
const char_t*stm_read_delim (...)
const char_t*stm_read_trim (...)
bool_tstm_read_bool (...)
int8_tstm_read_i8 (...)
int16_tstm_read_i16 (...)
int32_tstm_read_i32 (...)
int64_tstm_read_i64 (...)
uint8_tstm_read_u8 (...)
uint16_tstm_read_u16 (...)
uint32_tstm_read_u32 (...)
uint64_tstm_read_u64 (...)
real32_tstm_read_r32 (...)
real64_tstm_read_r64 (...)
typestm_read_enum (...)
voidstm_flush (...)
voidstm_pipe (...)
voidstm_lines (...)
voidstm_next (...)

Types and Constants

StreamkSTDIN
StreamkSTDOUT
StreamkSTDERR

A stream is a data flow that runs from a source to a destination. Think of a phone call. We have an origin (the person who speaks), a destination (the person who listens) and a channel (the line itself). In programming, the stream is the equivalent to the telephone line, it is the pipe that joins the application with a data source or destination (Figure 1) and through which binary information, bit sequences, run. As with any other communication channel, the information is volatile, available for a very limited time. Once it reaches the receiver, it disappears.

Drawing of a process connecting its I/O by streams.
Figure 1: Streams connect the process with the machine and the world.

In essence, there are three elementary operations to perform when working with streams:

  • Create the stream. Define the type of channel according to its extremes.
  • Write data to the channel.
  • Read data from the channel.

1. Stream Types

Actually, it is more correct to talk about types of extremes (origin and destination) than of stream types. From the perspective of the programmer, a stream is an abstract type that presents the same functionality regardless of the ends it connects. Therefore, when talking about stream types we are referring to the type of constructor.

1.1. File stream

In File streams (Figure 2), the source is the process memory and the destination is a disk file. The opposite can also happen, the source is the file and the destination is the memory. It will depend on how we open the channel. It will not be possible to perform write operations on an open file for reading or vice versa (Listing 1). Files and directories.

Drawing of a process accessing disk through streams.
Figure 2: File streams allow communication with the file system.

1.2. Socket stream

A socket is a communication channel between two processes over the Internet (Figure 3). Unlike file streams, sockets allow bidirectional full-duplex) communication, that is, both ends can send and receive information. The sequence of message exchange between partners is determined by the protocol (Listing 2), being HTTP, FTP, SMTP or LDAP some of the most used for Internet transmissions. Sockets.

Drawing of a process accessing the Internet through streams.
Figure 3: A socket stream opens a communication channel over the Internet.

1.3. Block stream

Block streams are used to read formatted data from a generic memory block. (Figure 4). This memory area is considered read-only and will not be modified, so write operations will not be allowed in this type of stream. When the entire block has been read, the ekSTEND status will be activated.

  • Use stm_from_block to read from memory zones.
  • Drawing a process reading from a memory block using streams.
    Figure 4: With block streams we will read formatted data from memory areas.

1.4. Memory stream

Memory streams are read/write channels that allow implementing the producer/consumer model (Figure 5). First, the information is written in the stream that stores it in an internal memory buffer. Subsequently, said information can be read by another function, thread or process. The concept is similar to that of pipelines (IPC-Pipes), with the proviso that there is no size limit for the buffer, but that it will grow on demand.

  • Use stm_memory to create a stream in memory.
  • Drawing of a process sharing data between threads using streams.
    Figure 5: Producer/consumer model implemented with memory streams.
Although this type of stream supports read and write operations it is not considered full-duplex. The reading is done on previously written data, but cannot "answer" the interlocutor. It is not a "conversation".

1.5. Standard stream

The Standard I/O can be managed by streams using three predefined objects (Figure 6). These objects are created when the program starts and will be automatically released when finished.

1.6. Text stream

Generic binary data always travels through a stream. How these data are interpreted depends on the extremes and their communication protocol. Text streams are a particular case where it is assumed that binary information represents character codes (codepoints) (Figure 7). You do not have to do anything special when creating a stream to indicate that it is text type, but use the API functions specialized in this type of information.

Streams do not have to be "pure" text or binary. They can combine both types of representations.

2. Stream advantages

Although it is possible to read or write directly to the I/O channels (Memory, Files and directories, Sockets, Standard I/O), do it through Stream objects has certain advantages. Therefore, we recommend using them instead of low-level APIs for the following reasons:

2.1. Unify serialization

Streams offer a uniform interface, regardless of the origin and destination of the data (Figure 8). For the object serialization, we just have to write a reader and a writer, without worrying if the object will be saved to disk, transmitted over the Internet or stored temporarily in memory (Listing 4).

Listing 4: (De)serialization of an object through streams.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
typedef struct _product_t
{
    type_t type;
    String *code;
    String *description;
    Image *image64;
    real32_t price;
} Product;

void product_write(Stream *stm, Product *product)
{
    stm_write_enum(stm, product->type, type_t);
    str_write(stm, product->code);
    str_write(stm, product->description);
    image_write(stm, product->image64);
    stm_write_r32(stm, product->price);
}

void product_read(Stream *stm, Product *product)
{
    product->type = stm_read_enum(stm, type_t);
    product->code = str_read(stm);
    product->description = str_read(stm);
    product->image64 = image_read(stm);
    product->price = stm_read_r32(stm);
}
Unification of I/O channels with streams.
Figure 8: Through streams we manage all I/O channels with the same interface.

2.2. More elegance

The I/O channels only work with byte blocks. Streams implement high-level functions for texts and binary types. This will make our code much more readable. (Listing 5).

Listing 5: Writing an object to disk directly or through a stream.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
void product_write(File *file, Product *product)
{
    uint32_t size = str_len(product->description);
    const char_t *data = tc(product->description);
    bfile_write(file, (byte_t*)&product->id, sizeof(uint32_t), NULL, NULL);
    bfile_write(file, (byte_t*)&product->price, sizeof(real64_t), NULL, NULL);
    bfile_write(file, (byte_t*)&size, sizeof(uint32_t), NULL, NULL);
    bfile_write(file, (byte_t*)data, size, NULL, NULL);
}

void product_write(Stream *stream, Product *product)
{
    stm_write_u32(stream, product->id);
    stm_write_r64(stream, product->price);
    str_write(stream, product->description);
}

2.3. Higher productivity

Related to the previous one, streams can "parse" text strings directly. You can get characters, words or lines without having to scan the entry character by character (Listing 6). For more detail, we can use the lexical analyzer Lexical scanner.

Listing 6: Read a line of text directly or through a stream.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
String *getline(File *file)
{
    /* Potentially unsafe. */
    /* Risk of buffer overflow. */
    char_t buffer[MAXBUFF];
    uint32_t i = 0;
    char_t c;

    bfile_read(file, (byte_t*)&c, 1, NULL, NULL);
    while (c != '\n')
    {
        buffer[i] = c;
        i += 1;
        bfile_read(file, (byte_t*)&c, 1, NULL, NULL);
    }

    buffer[i] = '\0';
    return str_c(buffer);
}

String *getline(Stream *stream)
{
    /* Totally safe. */
    /* line is in dynamic cache. */
    const char_t *line = stm_read_line(stream);
    return str_c(line);
}

2.4. Higher performance

File streams and socket streams implement an internal cache. This allows less access to the channel with a higher volume of data, which means faster processing speed. (Figure 9).

  • Use stm_flush to clear the cache and dump the data in the channel.
  • Drawing the streams using data cache.
    Figure 9: Streams implement cache memory, which increases performance.

2.5. Byte order

When reading or writing binary data from an I/O channel, special attention must be paid to the order of the bytes in 16, 32 or 64 bit data types, which is known as endianness. On litte endian machines, as is the case with the Intel x86/x64 family processors, the lowest order byte will be located at the lowest memory address. In the case of the big endian (Motorola 68000, PowerPC) it happens on the contrary, it will go in the highest. For example, if we write a 32-bit integer in a file or socket from a little endian machine and read it from a big endian, the data will be corrupted by altering the internal order of bits (Figure 10). The Stream objects automatically adjust the endianness in each read/write operation. Default is set ekLITEND, except in sockets that will be ekBIGEND for being the accepted agreement for network communications. However, it can be changed if necessary.

  • Use stm_set_write_endian to establish the endianness of the output channel. The data will pass from endian CPU to Stream endian before being written.
  • Use stm_set_read_endian to establish the endianness of the input channel. The data will pass from Stream endian to CPU endian at the time of being read.
  • Drawing streams taking into account the byte order.
    Figure 10: We must take into account endianness when sharing data between machines of different architecture.
Endianness does not influence UTF-8 text strings, but it does in the UTF-16 and UTF-32.

3. Stream state

A stream can be affected by two types of problems. On the one hand the data corruption that is evident when we read binary data from the stream. A clear example would be to read a Boolean by stm_read_bool and get a value of 129 when obviously this value should be 0 (TRUE) or 1 (FALSE). Normally, a stream is corrupted due to the lack of coordination between the writer and the reader and, in general, this situation must be resolved by debugging and correcting the serialization of objects or the data protocol. On the other hand, there may be physical errors in the channel (file deleted, loss of Internet connection, permissions, etc.). In both cases the stream will be "blocked" and the read or write operations we perform on it will be ignored.

  • Use stm_state to know the current status of the channel.
  • Use stm_file_err to get extended error information on disk streams.
  • Use stm_sock_err to get extended error information in sockets.
  • Use stm_corrupt to mark a stream as ekSTCORRUPT. Sometimes it is the application itself that detects that the data is not correct (eg out of range).

kSTDIN

Stream kSTDIN;

Stream connected to the standard input stdin.


kSTDOUT

Stream kSTDOUT;

Stream connected to standard output stdout.


kSTDERR

Stream kSTDERR;

Stream connected to error output stderr.


stm_from_block ()

Create a read stream from an existing memory block.

Stream*
stm_from_block(const byte_t *data,
               const uint32_t size);
data

Pointer to the memory block.

size

Size in bytes of the memory block.

Return

The stream.

Remarks

The original block will not be modified (read only). When the end of the block is reached stm_state will return ekSTEND. Block stream.


stm_memory ()

Create a read/write memory stream.

Stream*
stm_memory(const uint32_t size);
size

Initial buffer size (in bytes). It will grow if necessary.

Return

The stream.

Remarks

It can be used as an internal pipeline for the information exchange between functions or threads. It behaves like a FIFO (First In Fist Out) buffer. For multi-threaded access you must be protected with a Mutex. Memory stream.


stm_from_file ()

Create a stream to read from a file on disk.

Stream*
stm_from_file(const char_t *pathname,
              ferror_t *error);
pathname

File pathname. Filename and pathname.

error

Error code if the function fails. Can be NULL.

Return

The stream or NULL if the file opening fails.

Remarks

File stream.


stm_to_file ()

Create a stream to write data to a file on disk.

Stream*
stm_to_file(const char_t *pathname,
            ferror_t *error);
pathname

File pathname. Filename and pathname.

error

Error code if the function fails. Can be NULL.

Return

The stream or NULL if file creation fails.

Remarks

If the file already exists it will be overwritten. File stream.


stm_append_file ()

Create a stream to write data to the end of an existing file.

Stream*
stm_append_file(const char_t *pathname,
                ferror_t *error);
pathname

File pathname. Filename and pathname.

error

Error code if the function fails. Can be NULL.

Return

The stream or NULL if the file opening fails.

Remarks

It will fail if the file does not exist (do not create it). File stream.


stm_socket ()

Create a stream and connect to a remote host.

Stream*
stm_socket(const uint32_t ip,
           const uint16_t port,
           const SockOpt *opts,
           serror_t *error);
ip

The 32-bit IPv4 address. bsocket_host_ip.

port

Connection port.

opts

Connection options.

error

Error code if the function fails. Can be NULL.

Return

The stream or NULL if the connection fails.

Remarks

Socket stream.


stm_close ()

Close the stream. All resources such as file descriptors or sockets will be released. Before to closing, the data will be written to the channel stm_flush.

void
stm_close(Stream **stm);
stm

The stream object. Will be set to NULL after closing.


stm_get_write_endian ()

Get the current byte order when writing to the stream.

endian_t
stm_get_write_endian(const Stream *stm);
stm

The stream.

Return

The Byte order.


stm_get_read_endian ()

Get the current byte order when reading from the stream.

endian_t
stm_get_read_endian(const Stream *stm);
stm

The stream.

Return

The Byte order.


stm_set_write_endian ()

Set the order of bytes when writing to the stream, from now on.

void
stm_set_write_endian(Stream *stm,
                     const endian_t endian);
stm

The stream.

endian

The Byte order.

Remarks

Default is ekLITEND, except in sockets that will be ekBIGEND.


stm_set_read_endian ()

Set the order of bytes when reading from the stream, from now on.

void
stm_set_read_endian(Stream *stm,
                    const endian_t endian);
stm

The stream.

endian

The Byte order.

Remarks

Default is ekLITEND, except in sockets that will be ekBIGEND.


stm_get_write_utf ()

Gets the UTF encoding with which the texts are being written in the stream.

unicode_t
stm_get_write_utf(const Stream *stm);
stm

The stream.

Return

UTF encodings.


stm_get_read_utf ()

Get the UTF encoding with which the texts are being read in the stream.

unicode_t
stm_get_read_utf(const Stream *stm);
stm

The stream.

Return

UTF encodings.


stm_set_write_utf ()

Set the UTF encoding when writing texts in the stream, from now on.

void
stm_set_write_utf(Stream *stm,
                  const unicode_t format);
stm

The stream.

format

UTF encodings.


stm_set_read_utf ()

Set the UTF encoding when reading texts in the stream, from now on.

void
stm_set_read_utf(Stream *stm,
                 const unicode_t format);
stm

The stream.

format

UTF encodings.


stm_bytes_written ()

Gets the total bytes written in the stream since its creation.

uint64_t
stm_bytes_written(const Stream *stm);
stm

The stream.

Return

The total number of bytes written.


stm_bytes_readed ()

Get the total bytes read from the stream since its creation.

uint64_t
stm_bytes_readed(const Stream *stm);
stm

The stream.

Return

The total number of bytes readed.


stm_state ()

Get the current state of the stream.

sstate_t
stm_state(const Stream *stm);
stm

The stream.

Return

The Stream state.


stm_file_err ()

Get additional information about the error, in disk streams.

ferror_t
stm_file_err(const Stream *stm);
stm

The stream.

Return

File error.

Remarks

It is only relevant in File stream with the state ekSTBROKEN.


stm_sock_err ()

Get additional information about the error, in network streams.

serror_t
stm_sock_err(const Stream *stm);
stm

The stream.

Return

Socket error.

Remarks

It is only relevant in Socket stream with the state ekSTBROKEN.


stm_corrupt ()

Set the stream status to ekSTCORRUPT.

void
stm_corrupt(Stream *stm);
stm

The stream.

Remarks

Sometimes, it is the application that detects that the data is corrupted since the data semantics wasn't expected.


stm_str ()

Create a string with the current content of the internal buffer. It is only valid for stream in memory. stm_memory.

String*
stm_str(const Stream *stm);
stm

The stream.

Return

The string with the buffer content.


stm_buffer ()

Gets a pointer to the current content of the internal buffer. Only valid for stream in memory. stm_memory.

const byte_t*
stm_buffer(const Stream *stm);
stm

The stream.

Return

Internal buffer pointer.

Remarks

This pointer is read only. Writing here will have unexpected consequences.


stm_buffer_size ()

Get the current size of the internal buffer. Only valid for stream in memory. stm_memory.

uint32_t
stm_buffer_size(const Stream *stm);
stm

The stream object.

Return

The size of the internal buffer (in bytes).


stm_write ()

Write bytes in the stream.

void
stm_write(Stream *stm,
          const byte_t *data,
          const uint32_t size);
stm

The stream.

data

Pointer to the data block to write.

size

Number of bytes to write.

Remarks

The block is written as is, regardless of the Byte order neither the UTF encodings.


stm_write_char ()

Write a Unicode character in the stream.

void
stm_write_char(Stream *stm,
               const uint32_t codepoint);
stm

The stream.

codepoint

The Unicode value of character.

Remarks

The encoding can be changed with stm_set_write_utf.


stm_printf ()

Write text in the stream, using the printf format .

uint32_t
stm_printf(Stream *stm,
           const char_t *format,
           ...);
1
stm_printf(stream, Code: %-10s Price %5.2f\n
stm

The stream.

format

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

...

Arguments or variables of the printf.

Return

The number of bytes written.

Remarks

The final null character ('\0') will not be written. The encoding can be changed with stm_set_write_utf.


stm_writef ()

Writes a UTF8 C string in the stream.

uint32_t
stm_writef(Stream *stm,
           const char_t *str);
stm

The stream.

str

C UTF8 string terminated in null character '\0'.

Return

The number of bytes written.

Remarks

The final null character ('\0') will not be written. This function is faster than stm_printf when the string is constant and does not need formatting. For String objects use str_writef. The encoding can be changed with stm_set_write_utf.


stm_write_bool ()

Write a bool_t variable in the stream.

void
stm_write_bool(Stream *stm,
               const bool_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams.


stm_write_i8 ()

Write a int8_t variable in the stream.

void
stm_write_i8(Stream *stm,
             const int8_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams.


stm_write_i16 ()

Write a int16_t variable in the stream.

void
stm_write_i16(Stream *stm,
              const int16_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_i32 ()

Write a int32_t variable in the stream.

void
stm_write_i32(Stream *stm,
              const int32_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_i64 ()

Write a int64_t variable in the stream.

void
stm_write_i64(Stream *stm,
              const int64_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_u8 ()

Write a uint8_t variable in the stream.

void
stm_write_u8(Stream *stm,
             const uint8_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams.


stm_write_u16 ()

Write a uint16_t variable in the stream.

void
stm_write_u16(Stream *stm,
              const uint16_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_u32 ()

Write a uint32_t variable in the stream.

void
stm_write_u32(Stream *stm,
              const uint32_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_u64 ()

Write a uint64_t variable in the stream.

void
stm_write_u64(Stream *stm,
              const uint64_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_r32 ()

Write a real32_t variable in the stream.

void
stm_write_r32(Stream *stm,
              const real32_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_r64 ()

Write a real64_t variable in the stream.

void
stm_write_r64(Stream *stm,
              const real64_t value);
stm

The stream.

value

Value to write.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_write_enum ()

Write a enum variable in the stream.

void
stm_write_enum(Stream *stm,
               const type value,
               type);
stm

The stream.

value

Value to write.

type

The enum type.

Remarks

It is a binary write. Do not use in "pure" text streams. Byte order.


stm_read ()

Read bytes from the stream.

uint32_t
stm_read(Stream *stm,
         byte_t *data,
         const uint32_t size);
stm

The stream.

data

Pointer to the buffer where the read data will be written.

size

The number of bytes to read (buffer size).

Return

The number of bytes actually read.


stm_skip ()

Skip and ignore the next bytes of the stream.

void
stm_skip(Stream *stm,
         const uint32_t size);
stm

The stream.

size

The number of bytes to skip.


stm_read_char ()

Read a text character from the stream.

uint32_t
stm_read_char(Stream *stm);
stm

The stream.

Return

The Unicode character code.

Remarks

The encoding of the input text can be changed with stm_set_read_utf.


stm_read_chars ()

Read several characters from the stream.

const char_t*
stm_read_chars(Stream *stm,
               const uint32_t n);
stm

The stream.

n

The number of characters to read.

Return

Pointer to the UTF8 C string read. It will end with the null character '\0'.

Remarks

The returned pointer is temporary and will be overwritten in the next reading. If necessary, make a copy with str_c. The encoding of the input text can be changed with stm_set_read_utf.


stm_read_line ()

Read stream characters until an end of line is reached '\n'.

const char_t*
stm_read_line(Stream *stm);
stm

The stream.

Return

Pointer to the UTF8 C string read. It will end with the null character '\0'. Characters '\n' or '\r\n' will not be included.

Remarks

The returned pointer is temporary and will be overwritten in the next reading. If necessary, make a copy with str_c. The encoding of the input text can be changed with stm_set_read_utf.


stm_read_delim ()

Read stream characters until a delimiter character is reached.

const char_t*
stm_read_delim(Stream *stm,
               const uint32_t codepoint);
stm

The stream.

codepoint

The delimiter character.

Return

Pointer to the UTF8 C string read. It will end with the null character '\0'.

Remarks

Useful for reading simple tokens from text streams. If you need more control over tokens use lexscn_token. The delimiter character will be removed from the stream and not included in the result. The returned pointer is temporary and will be overwritten in the next reading. If necessary, make a copy with str_c. The encoding of the input text can be changed with stm_set_read_utf.


stm_read_trim ()

Read the next token delimited by blank spaces.

const char_t*
stm_read_trim(Stream *stm);
stm

The stream.

Return

Pointer to the UTF8 C string read. It will end with the null character '\0'.

Remarks

Useful for reading simple tokens from text streams. It will ignore all the initial blanks and read characters until the first blank is found ( ' ', '\\t', '\\n', '\\v', '\\f', '\\r'). If you need more control over the tokens use lexscn_token. The returned pointer is temporary and will be overwritten in the next reading. If necessary, make a copy with str_c. The encoding of the input text can be changed with stm_set_read_utf.


stm_read_bool ()

Read a bool_t value from the stream.

bool_t
stm_read_bool(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams.


stm_read_i8 ()

Read a int8_t value from the stream.

int8_t
stm_read_i8(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams.


stm_read_i16 ()

Read a int16_t value from the stream.

int16_t
stm_read_i16(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_i32 ()

Read a int32_t value from the stream.

int32_t
stm_read_i32(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_i64 ()

Read a int64_t value from the stream.

int64_t
stm_read_i64(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_u8 ()

Read a uint8_t value from the stream.

uint8_t
stm_read_u8(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams.


stm_read_u16 ()

Read a uint16_t value from the stream.

uint16_t
stm_read_u16(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_u32 ()

Read a uint32_t value from the stream.

uint32_t
stm_read_u32(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_u64 ()

Read a uint64_t value from the stream.

uint64_t
stm_read_u64(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_r32 ()

Read a real32_t value from the stream.

real32_t
stm_read_r32(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_r64 ()

Read a real64_t value from the stream.

real64_t
stm_read_r64(Stream *stm);
stm

The stream.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_read_enum ()

Read a enum value from the stream.

type
stm_read_enum(Stream *stm,
              type);
stm

The stream.

type

The enum type.

Return

Value read.

Remarks

It is a binary reading. Do not use in "pure" text streams. Byte order.


stm_flush ()

Write in the channel the existing information in the cache.

void
stm_flush(Stream *stm);
stm

The stream.

Remarks

To improve performance, write operations on disk streams or sockets are stored in an internal stream cache. This function forces writing on the channel and cleans the buffer. It will be useful with full-duplex protocols where the receiver awaits reply to continue.


stm_pipe ()

Connect two streams, reading data from one and writing it to another.

void
stm_pipe(Stream *from,
         Stream *to,
         const uint32_t n);
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// This example is based in a private protocol.
// Read from socket n-bytes and write them to file.
uint32_t ip;
uint32_t size;
Stream *sockstm;
Stream *filestm;
bsocket_host_ip("www.myserver.com", &ip, NULL);
sockstm = stm_socket(ip, 1647, NULL);
filestm = stm_to_file("C:\Users\peter\image.png", NULL);
stm_writef(sockstm, "Give me file 'peter.png'");
size = stm_read_u32(sockstm, NULL);
stm_pipe(sockstm, filestm, size);
stm_close(&sockstm);
stm_close(&filestm);
from

The input stream (to read).

to

The output stream (to write).

n

The number of bytes to be transferred.

Remarks

The transfer will be made on raw data, regardless of Byte order or UTF encodings. If you are clear that this does not affect, it is much faster than using atomic read/write operations.


stm_lines ()

Iterate over all lines in a Text stream. You should use stm_next to close the loop.

void
stm_lines(const char_t *line,
          Stream *stm);
1
2
3
4
5
6
uint32_t i = 1;
Stream *stm = stm_from_file("/home/john/friends.txt", NULL);
stm_lines(line, stm)
    bstd_printf("Friend %d, name %s\n", i++, line);
stm_next(line, stm);
stm_close(&stm);
line

Name of the variable that will temporarily host the line. Use an internal stream cache, so you should make a copy with str_c if you need to keep it.

stm

The stream.


stm_next ()

Close a loop open by stm_lines.

void
stm_next(const char_t *line,
         Stream *stm);
line

Name of the line variable.

stm

The stream.

❮ Back
Next ❯