F.1.17. rascal_reads

This function retreives a line of text from the connection's incoming buffer. A line of text is a sequence of 8-bit characters terminated by an LF character.

rrid_t rascal_reads(
	rrid_t conn,
	char *buffer,
	unsigned int *buffer_size,
	int flags OPTIONAL



Handle of the connection that the data must be retreived from. If the handle does not correspond to a valid stream oriented connection, an error is reported. This function can not be used on datagram connections.

buffer, buffer_size

Location and dimension of the buffer that receives the a NUL-terminated C-string. On success, buffer_size is updated with the number of actually copied bytes, excluding the (trailing) NUL character. (That is, the maximum possible value of buffer_size on return is the initial value minus one.)


A bit mask that modifies the behaviour of the function. By default (when zero is used for flags), the function does the following:

  1. Copies the data to the specified destination, excluding all trailing CR and LF characters. If the destination is not large enough, the data is truncated.
  2. Removes the data from the connection's incoming buffer, up to and including the LF character.

A combination of the following flags can be used to modify this behaviour:

Table F.2. rascal_reads flags

RRF_UNTRIMMEDTells the function to include trailing CR and LF characters in the destination buffer.
RRF_PEEKPrevents the function from removing the data from the connection's incoming buffer; the data is copied to the specified destination and remains in the buffer.
RRF_MEASUREPrevents the function from extracting anything; instead, size is updated with the length of the buffer that would be enough to receive the whole string, without truncation. Other flags that modify the copied string (such as RRF_UNTRIMMED) are taken into consideration.

Return value. 

If everything goes well, the function returns REC_SUCCESS. If the connection's incoming buffer did not contain an LF character, the function returns REC_NO_DATA. Descriptions of other error messages can be retreived using rascal_get_errmsg.


char buffer[1024];
unsigned int size = sizeof(buffer);

while (rascal_isok(rascal_reads(rid, buffer, &size))) {
	printf(">> %s\n", buffer);
	size = sizeof(buffer);