NAME

fget_line - Reads a line from a stream into a null terminated string.

SYNOPSIS

#include "l/l_sys_io.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


long fget_line
(
	FILE *fp,
	char *line,
	size_t max_len
);

DESCRIPTION

This routine is similar to fgets(3C). It reads a null terminated string representing one line from the file/device represented by the parameter "fp" into the buffer pointed to by the parameter "line". The new line character is consumed but not returned. At most max_len characters are placed into "line" including the NULL. If there are more than max_len-1 characters on the line, the extra ones are purged, and a truncated version of the line is left in the buffer and TRUNCATED is returned. The maximum number of characters that can be read is also limited by an internal buffer. If the number of characters exceed the size of the internal buffer, then TRUNCATED is also returned. Since fget_line is intended for reading text, extremely long lines are not expected. The exact limit is given by GET_LINE_BUFF_SIZE which is defined in l_sys_io.h. An internal buffer is needed to get the proper behaviour on non-blocking reads. If the device corresponding to fp has been set non-blocking then this routine will return WOULD_BLOCK until an entire line can be returned. Similarly, if EOF is read before the new line is reached, then EOF is returned until an entire line can be read. Thus if a separate process is writing to a file, and this routine is used to read that file, then a loop on EOF will read the file by lines, which can simplify parsing. This function is not re-entrant (i.e., not thread-safe).

RETURNS

On success fget_line returns the number of bytes placed in the buffer, excluding the NULL. Since the new line chracter is consumed but not copied, zero is returned for null lines. Alternate return values are all negative. In the case of end of file, EOF returned. If the line was truncated, then TRUNCATED is returned. Depending on the signal traps and options in place, INTERRUPTED is an additional possible return value. In the case of non-blocking reads WOULD_BLOCK is returned unless a complete line can be returned. ERROR is returned for unexpected problems and an error message is set.

NOTE

Since the number of characters is limted by the internal buffer which is less than LONG_MAX, there will not be overflow in the return of the number of bytes. This routine is meant for reading relatively short ascii lines.

NOTE

The behaviour on non-blocking and EOF assumes that all calls in a sequence trying to read a given line are made with the same file pointer (there is only one buffer). This is only relavent for situations where one is actively waiting for additional input to arrive (due to some other process).

NOTE

This routine is not designed for performance. The assumption is that line at a time reads correspond to small amounts of I/O.

MACROS

BUFF_FGET_LINE(FILE fp, char line[]) The max_len parameter is set to sizeof(line) with the appropriate cast. Using sizeof to set the buffer size is recomended where applicable, as the code will not be broken if the buffer size changes. HOWEVER, neither this method, nor the macro, is applicable if line is NOT a character array. If line is declared by "char* line", then the size of line is the number of bytes in a character pointer (usually 8), which is NOT what is normally intended. You have been WARNED!

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Kobus Barnard

DOCUMENTER

Kobus Barnard

NAME

SYNOPSIS

DESCRIPTION

RETURNS

NOTE

NOTE

NOTE

MACROS

DISCLAIMER

AUTHOR

DOCUMENTER

SEE ALSO