NAME

term_get_line - Reads a line from the terminal.

SYNOPSIS

#include "l/l_sys_term.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 


int term_get_line
(
	const char *prompt,
	char *line,
	size_t max_size
);

DESCRIPTION

This routine reads a line from the terminal, providing a number of useful features. These include line re-entry, intelligent behaviour under non-blocking reads, and intelligent behaviour on CTL-Z. If these features are not desired, then there is no point in using this routine. If the higher level code has not called term_set_raw_mode_with_no_echo() before the first call to term_get_line(), then term_get_line makes the call. This sets the terminal into raw mode and takes over the echoing of characters. This means that an inadvertant exit under some systems/shells (including sh/csh) can leave the user without character echo. The mode can be reset using term_reset(). However, this is automaticlally done in kjb_cleanup(), and it is recommended that kjb_cleanup() is called instead. kjb_cleanup() is called by kjb_exit(), as well as any abnmormal termination trapped by the KJB library. If the call to term_set_raw_mode_with_no_echo() is in place before the call to term_get_line(), then the call is not made. The simplest way to handle some of these problems is to use the macro KJB_INIT() before using this routine. KJB_INIT sets things up so that most points of exit are covered by the appropriate cleanup. Any signals that are going to be used should be put in place BEFORE the (perhaps implicit) call to term_set_raw_mode_with_no_echo(). This is because term_set_raw_mode_with_no_echo() intercepts the signals. This comment does not apply to signals which are set and unset without any intervening call to term_get_line() provided that they reinstate the previous handler (kjb_set_atn_trap and kjb_unset_atn_trap can be used to do this in the case of SIGINT -- ideally such a facility should be available for signals in general, but .... ) If non-blocking reads are used, thes routine assumes that prompt and max_len are not changed between unsuccessful reads. Once the user has entered a line, then a "new" read begins, and it is OK to change the prompt and the buffer.

RETURNS

On success term_get_line returns the number of bytes placed in the buffer. Since the new line chracter is consumed but not copied, the return is zero for null lines. Alternate return values are all negative. In the case of end of file, EOF returned (the user entered ^D). If the line was truncated, then LINE_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.

DISCLAIMER

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

AUTHOR

Kobus Barnard

DOCUMENTER