NAME

dget_line - Gets a line into a null terimated string from a device.

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 dget_line
(
	int des,
	char *line,
	size_t max_len
);

DESCRIPTION

The routine dget_line reads a null terminated string representing one line from the device designated by the descriptor "des" 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, then the extra 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 dget_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 des 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 dget_line returns the number of bytes placed in the buffer. Since the new line chracter is consumed but not copied, the return may be zero 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_DGET_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 4), 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

SEE ALSO

set_low_level_io_options , kjb_read_exact , kjb_read , kjb_read_2 , safe_pipe_write , kjb_write , kjb_write_2 , kjb_fread_exact , kjb_fread , kjb_fread_2 , kjb_fwrite , kjb_fwrite_2 , kjb_safe_fflush , kjb_fflush , kjb_ioctl , set_blocking , set_no_blocking , stdin_get_line , fget_line , fput_line , kjb_mkdir , kjb_mkdir_2 , kjb_unlink , kjb_unlink_2 , kjb_rmdir , kjb_fopen , kjb_freopen , kjb_fdopen , kjb_fclose , kjb_realpath , get_fd_name , get_user_fd_name , kjb_fseek , kjb_ftell , kjb_fputs , kjb_fgetc , kjb_fputc , pso , p_stderr , kjb_fprintf , pdo , kjb_vfprintf , is_file , is_directory , fp_get_path_type , get_path_type , get_file_size , fp_get_byte_size , get_file_age , stream_younger , stream_older , get_file_mod_time , kjb_isatty , print_underlined , start_stdout_shadow , stop_stdout_shadow , start_stderr_shadow , stop_stderr_shadow , enable_stdout , disable_stdout , kjb_glob , kjb_simple_glob