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_386 -DLINUX_386_P4
-I/home/kobus/include
-L/home/kobus/load/linux_386_p4 -L/usr/local/lib -L/usr/lib
-lKJB -llapack -lblas -lg2c -lXext -lX11
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.
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
DOCUMENTOR
Kobus Barnard
SEE ALSO
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_fflush
,
kjb_ioctl
,
set_blocking
,
set_no_blocking
,
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
,
get_file_mod_time
,
print_underlined
,
start_stdout_shadow
,
stop_stdout_shadow
,
start_stderr_shadow
,
stop_stderr_shadow
,
kjb_glob
,
kjb_simple_glob