Collaboration diagram for API_LowLvl::lib::util:

Data Structures
struct	SprCmdDesc

struct	SprCmdOptDesc

struct	SprCmdBuf

Macros
#define	spr_cmd_aux(aux_array, array_el0,...)

Enumerations
enum	{ SPR_CMD_CIO_PSPEC, SPR_CMD_CIO_WORD, SPR_CMD_CIO_STRING, SPR_CMD_CIO_EXPR, SPR_CMD_CIO_CSTRING, SPR_CMD_CIO_VAROP }

enum	{ SPR_CMD_CIO_USPEC, SPR_CMD_CIO_MSPEC, SPR_CMD_CIO_UNIQ, SPR_CMD_CIO_MULTI, SPR_CMD_CIO_FBACK, SPR_CMD_CIO_SCAT }
	the option can be specified only once or multiple times More...

enum	{ SPR_CMD_CIO_RSPEC, SPR_CMD_CIO_OPT, SPR_CMD_CIO_REQ }

enum	{ SPR_CMD_CIO_SPC, SPR_CMD_CIO_NPRNT, SPR_CMD_CIO_CHECK }

enum	{ SPR_CMD_CIO_EXCL1, SPR_CMD_CIO_EXCL2, SPR_CMD_CIO_EXCL3, SPR_CMD_CIO_EXCL4, SPR_CMD_CIO_EXCL5, SPR_CMD_CIO_EXCL6, SPR_CMD_CIO_EXCL7, SPR_CMD_CIO_EXCL8 }

Functions
unsigned int	spr_util_nr_digits (int nr)

unsigned int	spr_util_list_free (void list_ptr, int offset_next, SprMsgId routine)

unsigned int	spr_util_list_len (const void *list_ptr, int offset_next)

int	spr_util_list_scan (const void list, const void stop_ptr, int offset_next, int offset_field, int field_len, const void *ref_field)

int	spr_util_flags_check (const char flag_str, const char tst_flags)

char *	spr_cmd_strccvt (char *str_in, int quoted_only)

char *	spr_cmd_ci_skip_space (const char str, const char blancs)

char *	spr_cmd_ci_skip_word (const char str, const char blancs)

char *	spr_cmd_ci_skip_cstring (const char str, const char blancs)

char *	spr_cmd_ci_skip_expression (const char str, const char blancs)

char *	spr_cmd_ci_skip_varop (const char str, const char blancs, int *status)

char *	spr_cmd_ci_next_word (const char *parse_ptr, int len, const char *blancs)

int	spr_cmd_ci_get_words (char *str_array, const char str, const char *blancs)

int	spr_cmd_ci_print_cmd (SprStream fd, const char cmd, const char sep_str, const char blancs)

int	spr_cmd_ci_check_flag (const char template_, const char word, int len)

void	spr_cmd_ci_print_opts (SprStream fd, char lm, void dest_ptr, const SprCmdOptDesc od, char *blancs)

int	spr_cmd_ci_check_opts (void dest_ptr, const SprCmdOptDesc od, const char cmd_str, int len, int opt_sep, const char blancs, int flags)

int	spr_cmd_ci_screen_width (SprStream *fd, int fdi, int def_width)

void	spr_ci_print_optsyntax (SprStream fd, const char lm, const SprCmdOptDesc *od, int opt_sep)

void	spr_cmd_ci_print_syntax (SprStream fd, const SprCmdDesc cmd, int detailed)

void	spr_cmd_ci_print_syntax_ (SprStream fd, const char template_, const void const ext_info, int detailed)
	See ci_print_syntax(). More...

int	spr_cmd_ci_hash (char const set, const char *elem, int len, int full_match)

int	spr_cmd_ci_test_syntax (const char Template, const void const ext_info, const char cmd_str, const char *blancs)

SprCmdBuf *	spr_cmd_ci_free_cnt (SprCmdBuf *cmdbuf)
	Free a previously allocated count buffer. More...

int	spr_cmd_ci_init_cnt (const SprCmdDesc cmd_list, SprCmdBuf cmdbuf)

int	spr_cmd_ci_check_cnt (SprCmdBuf cmdbuf, int msg_level, SprMsgId routine)

SprCmdBuf *	spr_cmd_ci_init_cmdbuf (SprCmdBuf *cmdbuf)

SprCmdBuf *	spr_cmd_ci_free_cmdbuf (SprCmdBuf *cmdbuf)

int	spr_cmd_ci_init_find (const char template_, const void const ext_info, const char cmd_str, const char blancs, SprCmdBuf cmdbuf)

int	spr_cmd_ci_decode (const SprCmdDesc cmd_list, const char cmd, const char blancs, SprCmdBuf cmdbuf)

int	spr_cmd_ci_decode_ (const SprCmdDesc cmd_list, const char cmd, const char blancs, SprCmdBuf cmdbuf)
	The OLD, non dynamical counter part of ci_decode(). More...

void	spr_cmd_ci_print_help_ (SprStream fd, const SprCmdDesc cmd_list, const char matchstr, const char blancs, int matchcnt, int help_level)

void	spr_cmd_ci_print_help (SprStream fd, const char min_match, int help_level, SprCmdBuf *cmdbuf)
	Print help for a command. Only the command(s) that match min_match for all words specified in the string will be printed. The commands listed are those used in the last ci_decode() with the specified cmdbuf. The amount of output is also controled by help_level More...

void	spr_cmd_ci_online_help (SprStream help_dest, int help_flag, SprCmdBuf cmdbuf)

char *	spr_cmd_ci_arg_ptr (SprCmdBuf *cmdbuf)

char *	spr_cmd_ci_get_arg (const char defval, SprCmdBuf cmdbuf)

int	spr_cmd_ci_get_flag (const char defflag, SprCmdBuf cmdbuf)

int	spr_cmd_ci_get_enum (const char defstr, SprCmdBuf cmdbuf)

int	spr_cmd_ci_get_opts (void dest_ptr, SprCmdBuf cmdbuf)

int	spr_cmd_wait_for_child (int pid)

int	spr_cmd_ci_exec (char Stdin, char Stdout, char Stderr, const char flags, const char *exec_str,...)

int	spr_cmd_execute_string (int waitfor, char *string)
	returns child ID More...

int	spr_cmd_ci_shell (const char exec_str, const char shell)

int	spr_cmd_ci_system (const char *exec_str)

char *	spr_cmd_ci_prompt (SprStream fd_in, SprStream fd_out, char buf[], int max_len, const char *prompt)

int	spr_str_indexdec (int n, const char str, int i1, int *i2)

int	spr_str_mindexdec (int n, int N, const char *str, int istart[], int iend[])

Variables
const char *const	spr_cmd_yes_no_flags []

char	spr_cmd_snull []

const SprCmdBuf	spr_cmd_empty_cmdbuf
	empty cmdbuf More...

Detailed Description

Macro Definition Documentation

#define spr_cmd_aux	(	aux_array,
		array_el0,
		...
	)

Specify the auxilary data (an array of pointers) so that the parser still can track the elements (by simply restating each element of the array).

Enumeration Type Documentation

anonymous enum

argument is a word, string, expression, C-string, name or operator

Enumerator
SPR_CMD_CIO_PSPEC
SPR_CMD_CIO_WORD
SPR_CMD_CIO_STRING
SPR_CMD_CIO_EXPR
SPR_CMD_CIO_CSTRING
SPR_CMD_CIO_VAROP

anonymous enum

the option can be specified only once or multiple times

Enumerator
SPR_CMD_CIO_USPEC
SPR_CMD_CIO_MSPEC
SPR_CMD_CIO_UNIQ
SPR_CMD_CIO_MULTI
SPR_CMD_CIO_FBACK
SPR_CMD_CIO_SCAT

anonymous enum

Enumerator
SPR_CMD_CIO_RSPEC
SPR_CMD_CIO_OPT
SPR_CMD_CIO_REQ

anonymous enum

Enumerator
SPR_CMD_CIO_SPC
SPR_CMD_CIO_NPRNT
SPR_CMD_CIO_CHECK

anonymous enum

Enumerator
SPR_CMD_CIO_EXCL1
SPR_CMD_CIO_EXCL2
SPR_CMD_CIO_EXCL3
SPR_CMD_CIO_EXCL4
SPR_CMD_CIO_EXCL5
SPR_CMD_CIO_EXCL6
SPR_CMD_CIO_EXCL7
SPR_CMD_CIO_EXCL8

Function Documentation

unsigned int spr_util_nr_digits ( int nr )

Returns the number of characters needed to print the given number.

unsigned int spr_util_list_free	(	void *	list_ptr,
		int	offset_next,
		SprMsgId *	routine
	)

Used to free a single linked list when no dynamically allocated is added to the basic list structure.
A typical call is

free_list(&list,offsetof(List,next),routine);

Returns: The number of freed elements.

Parameters

list_ptr	address of pointer to 1st element
offset_next	offset of the 'next'-field
routine	name of the calling routine

unsigned int spr_util_list_len	(	const void *	list_ptr,
		int	offset_next
	)

Count the number of elements in a basic list structure. A typical call is

get_list_len(list,offsetof(List,next));

Returns: The number of elements in the list.

Parameters

list_ptr	pointer to 1st element
offset_next	offset of the 'next'-field

int spr_util_list_scan	(	const void *	list,
		const void *	stop_ptr,
		int	offset_next,
		int	offset_field,
		int	field_len,
		const void *	ref_field
	)

Scan a single linked list for the occurence of some data in one of its fields. If field_len equals -1, the routine assumes that the field is a pointer and the value to test for is the ref_field pointer itself and not the data it points to. If offset_field equals -1, the routine scans for a list element at the location specified by ref_field.
Typical calls are:

spr_util_list_scan(list,offsetof(List,next),offsetof(list,field),sizeof(Field),&ref_el);
spr_util_list_scan(list,offsetof(List,next),offsetof(list,field),-1,ptr);
spr_util_list_scan(list,offsetof(List,next),-1,0,address);

Returns: The number of blocks in the list that have the requested field.

Parameters

list	pointer to 1st element
stop_ptr	address of the terminator
offset_next	offset of the 'next'-field
offset_field	offset of the field to check
field_len	length of the field to check
ref_field	reference field

int spr_util_flags_check	(	const char *	flag_str,
		const char *	tst_flags
	)

Check if any of the specified character flags in tst_flags occures in the given flag string flag_str. If any of the two strings is NULL, a (1) is returned.

Parameters

flag_str	string to check
tst_flags	flags to check for

char* spr_cmd_strccvt	(	char *	str_in,
		int	quoted_only
	)

On-site conversion of a string containing C-escape sequences to a string containing the desired codes. If the quoted_only flag is set, only strings that are surrounded by double quotes are converted (and the double quotes are removed). "Note:" This routine does not use strccpy(), as this routine is not available on all machines.

char* spr_cmd_ci_skip_space	(	const char *	str,
		const char *	blancs
	)

Skip all leading white space in a string. If (blancs==NULL), the default blancs of the system are used.

Parameters

str	string
blancs	allowed spaces

char* spr_cmd_ci_skip_word	(	const char *	str,
		const char *	blancs
	)

Skip all leading NON white space in a string. If (blancs==NULL), the default blancs of the system are used.

Parameters

str	string
blancs	allowed spaces

char* spr_cmd_ci_skip_cstring	(	const char *	str,
		const char *	blancs
	)

Skip a word (NON white space characters) in a string. If a '"' character is encountered, all characters until the closing '"' are included, disregarded of the occurence of any white space character. If (blancs==NULL), the default blancs of the system are used.

Parameters

str	string
blancs	allowed spaces

char* spr_cmd_ci_skip_expression	(	const char *	str,
		const char *	blancs
	)

Skip an expression (NON white space characters) in a string. The end of an expression is the first white space character that does not occure within a string and after all opened brackets are closed. No special test are performed to ensure the correct order of the brackets.

Parameters

str	string
blancs	allowed spaces

char* spr_cmd_ci_skip_varop	(	const char *	str,
		const char *	blancs,
		int *	status
	)

Skip a variable name, an numerical constant, a C-operator, or a C-string.

Parameters

str	string
blancs	allowed spaces
status	'-' or '+' can be either a sign as part of a number or an operand

char* spr_cmd_ci_next_word	(	const char **	parse_ptr,
		int *	len,
		const char *	blancs
	)

Finds the next word in a string. The default blanks of the system can be used by setting blancs to NULL. Initialise the search by setting the parse_ptr to the beginning of the string to parse.

Returns: A pointer to the first/next word and a pointer to the empty string if there were no words left.

Note: The word is not terminated with a '\0'. Instead of a '\0' termination, the length of the word is returned in len.

Parameters

parse_ptr	parse pointer
len	length of next word
blancs	allowed word separators

int spr_cmd_ci_get_words	(	char **	str_array,
		const char *	str,
		const char *	blancs
	)

Count the number of words in a string, and optionaly (str_array != NULL), store them in a NULL terminated array of strings. Note that the destination array must be large enough.

Returns: The number of words found or (-1) on error.

Parameters

str_array	array of words
str	string to parse
blancs	allowed word separators

int spr_cmd_ci_print_cmd	(	SprStream *	fd,
		const char *	cmd,
		const char *	sep_str,
		const char *	blancs
	)

Print the words in the cmd string separated by the sep_str. If (fd == NULL), nothing is printed. "Return value:" The number of words in the string.

Parameters

fd	destination file
cmd	command to print
sep_str	string separating each word
blancs	the field separators

int spr_cmd_ci_check_flag	(	const char *	template_,
		const char *	word,
		int	len
	)

Match the string in word (length=len) against the flags described in the template. If (len == -1), len is set to strlen(word).
The template must be of the form:

  <don't care> '<' <flag1> '/' <flag2> '/' .... '>' <don't care>

The bracket pair < > can be replaced by any other bracket pair out of the set:

  [ ]  { } ( ).

Returns: Number of the flag: the last flag: 0, the 2nd last: 1, ...
A (-1) is returned if there is no matching flag.

Example:: ci_check_flag("%F[on/off]","off",-1)

will return 0.

Parameters

template_	flag description
word	flag to decode
len	length of the flag

void spr_cmd_ci_print_opts	(	SprStream *	fd,
		char *	lm,
		void *	dest_ptr,
		const SprCmdOptDesc *	od,
		char *	blancs
	)

Print the results after decoding a list of option specifications.

Parameters

fd	file to print to
lm	print as left margin
dest_ptr	common dest. offset
od	describes the options
blancs	blancs to ignore

int spr_cmd_ci_check_opts	(	void *	dest_ptr,
		const SprCmdOptDesc *	od,
		const char *	cmd_str,
		int	len,
		int	opt_sep,
		const char *	blancs,
		int	flags
	)

Check and/or decode a list of option specifications.
The option description list is an array of elements of the type OptDesc. The list is terminated with a special end element. The elements are structures, with the following fields:
{"option",type,flags,"def_val","explanation",offset,ext_info_ptr}

The last element should be:
{NULL,0,0,NULL,NULL,0,NULL}

Explanation:

option: The option specifier to trigger on.
type: The type of the value following the option.
flags: Bits flags specifing some a the characteristics of the option.
def_val: The default value. A NULL indicates no default value. For dynamical allocated strings, the spr_cmd_snull value can be specified, meaning that the string pointer should have the NULL value. For flags, a spr_cmd_snull value indicates that the flag should be set to its default value before or after decoding all options. Note the a default value will only be set if none of the options refering to the same offset have been specified.
explanation: A short explanation, describing the option.
offset: The offset of the field in a structure where the decoded value must be set.
ext_info_ptr: A pointer to the extra information needed by some types.

Possible types:

INT,SHORT,BYTE: An integer, short integer or byte value.
FLOAT,DOUBLE: A float or double value.
CHAR: A single character.
DYNSTRING: A dynamically allocated string.
ENUMI,ENUMS,ENUMB: An enumeration. The ext_info_ptr must point to a NULL terminated array of strings with the names of all possible values. The resulting index is stored in an integer, short integer or byte.
FLAG_TRUE,FLAG_FALSE: Set the flag (of the type char) at the specified offset to TRUE or FALSE. If spr_cmd_snull is defined as default value, the flag will be set to FALSE or TRUE if the option was not specified.
FLAG_TOGGLE: Toggle the flag (of the type char). If spr_cmd_snull is defined as default value, the flag will be set to FALSE before the decoding starts.
FLAG_NDX: Set the integer at the specified offset to the value stored in the ext_info_ptr field. See ndx2ext_info() also.

Possible flags:

CIO_OPT: The option is optional (default).
CIO_REQ: The option is required.
CIO_UNIQ: The option may only be specified once (default).
CIO_MULTI: The option may be specified multiple times. Only the last value is stored.
CIO_SCAT: The DYNSTRING option may be specified multiple times. The resulting string is the concatenation of all specified string, separated by the given option separator opt_sep.
CIO_FBACK: If this option was already specified then search for another matching option.
CIO_SPC: The option specifier must be followed by one or more spaces.
CIO_NPRNT: The option and value should not be printed by the ci_print_opts() routine.
CIO_WORD: The DYNSTRING value is / may be a word. See also ci_skip_word().
CIO_STRING: The DYNSTRING value is / may be a string. See also ci_skip_cstring().
CIO_CSTRING: The DYNSTRING value is / may be a string. If the string is surrounded by double quotes, it is converted using strccvt(). See also ci_skip_cstring().
CIO_EXPR: The DYNSTRING value is / may be an expression. See also ci_skip_expression().

The default values for the flags may be specified in two ways:

Passing them as argument in the flags parameter.
The flags in the first option, if its 'option' field has the value spr_cmd_snull.

The flags parameter may also contain the 'CIO_CHECK' bit-flag. In that case, no error messages are given for non matching options.

Returns

(1): The string could be parsed successfully.
(0): Some options int the string were not recognized.
(-1): The string could not be parsed due to memory problems.

Parameters

dest_ptr	common dest. offset
od	describes the options
cmd_str	str to match with the template
len	length of the cmd_str
opt_sep	separator between options
blancs	blancs to ignore
flags	extra flags

int spr_cmd_ci_screen_width	(	SprStream *	fd,
		int	fdi,
		int	def_width
	)

Determine the width (nr. of characters per line) for a given output device. If the request fails, the default width def_width is returned.
Currently non operational for Windows.

void spr_ci_print_optsyntax	(	SprStream *	fd,
		const char *	lm,
		const SprCmdOptDesc *	od,
		int	opt_sep
	)

void spr_cmd_ci_print_syntax	(	SprStream *	fd,
		const SprCmdDesc *	cmd,
		int	detailed
	)

Print the command syntax. If the detailed flag is set, the syntax of any incorporated option lists is also given.

void spr_cmd_ci_print_syntax_	(	SprStream *	fd,
		const char *	template_,
		const void const	ext_info,
		int	detailed
	)

See ci_print_syntax().

int spr_cmd_ci_hash	(	char const	set,
		const char *	elem,
		int	len,
		int	full_match
	)

A comabination of hash() and hashn() that works also with non '\0' terminated strings.

Parameters

set	set to search in
elem	element to search for
len	size of the element
full_match	no abbreviations allowed

int spr_cmd_ci_test_syntax	(	const char *	Template,
		const void const	ext_info,
		const char *	cmd_str,
		const char *	blancs
	)

Test if the command fits to the given template. The fields separators can be passed by the argument blancs. If (blancs == NULL), the default blancs of the system are used. If the command fits, the number of items in the command string is returned. If the command does not fit, minus the number of the item in the command string that did fit is returned.

Parameters

Template	template to match with
ext_info	extra info (enums, ...)
cmd_str	str to match with the template
blancs	allowed word separators

SprCmdBuf* spr_cmd_ci_free_cnt ( SprCmdBuf * cmdbuf )

Free a previously allocated count buffer.

Parameters

cmdbuf buffer to hold results

int spr_cmd_ci_init_cnt	(	const SprCmdDesc *	cmd_list,
		SprCmdBuf *	cmdbuf
	)

Initialise a count buffer, so that the number of times each command was invoked can be counted. Those counts enable you to check if all required commands were evaluated at least once, and they also allow you if any command was requested multiple times. This option only works if the command buffer is allocated dynamically (ci_init_cmdbuf(NULL)).

Returns: (-1) on error, otherwise the number of command in cmd_list is returned.

Parameters

cmd_list	the command templates
cmdbuf	buffer to hold results

int spr_cmd_ci_check_cnt	(	SprCmdBuf *	cmdbuf,
		int	msg_level,
		SprMsgId *	routine
	)

Check if all required commands were evaluated at least once, and if non of the commands that have the 's' (single) flag set were requested multiple times. This option only works if the command buffer is allocated dynamically (ci_init_cmdbuf(NULL)).

Returns: (-1) on error, otherwise the number of commands in the cmd_list use when calling spr_cmd_ci_init_cnt() is returned.

Parameters

cmdbuf	buffer to hold results
msg_level	print msgs at the given level
routine	use this name as routine name

SprCmdBuf* spr_cmd_ci_init_cmdbuf ( SprCmdBuf * cmdbuf )

Initialize the command parser buffer, only required when using the dynamical mode.

Parameters

cmdbuf buffer to initialize

SprCmdBuf* spr_cmd_ci_free_cmdbuf ( SprCmdBuf * cmdbuf )

Free the data allocated by the command parser buffer, only required when using the dynamical mode.

Parameters

cmdbuf buffer to deallocate

int spr_cmd_ci_init_find	(	const char *	template_,
		const void const	ext_info,
		const char *	cmd_str,
		const char *	blancs,
		SprCmdBuf *	cmdbuf
	)

Initialize/reset the argument search pointers. The initialization is done automaticaly by ci_decode().

Note: A direct call to ci_init_find will automatically select the dynamical allocation strategy, requiring an extra ci_init_cmdbuf() and ci_free_cmdbuf() call.

Parameters

template_	search template
ext_info	extra info (enums, ...)
cmd_str	string to parse
blancs	allowed white spaces
cmdbuf	buffer to initialize

int spr_cmd_ci_decode	(	const SprCmdDesc *	cmd_list,
		const char *	cmd,
		const char *	blancs,
		SprCmdBuf *	cmdbuf
	)

Search the number of the command template that match to the given command string (cmd). The white space characters used as field separators are given by the parameter blancs. The default blancs of the system can be used by calling the procedure with a NULL pointer as blancs. The pointers for argument searching are also set and initialized for later use. If (cmdbuf == NULL) then an internal buffer is used.

Note: The initialization routine, ci_init_cmdbuf() should be called before this routine is called.

Returns: The cmd_nr assigned to the matching template.
(-1) if there was no matching command template.
(-2) if there was an error (only in dyn. mode).

Parameters

cmd_list	the command templates
cmd	the command to match
blancs	the field separators
cmdbuf	buffer to hold results

int spr_cmd_ci_decode_	(	const SprCmdDesc *	cmd_list,
		const char *	cmd,
		const char *	blancs,
		SprCmdBuf *	cmdbuf
	)

The OLD, non dynamical counter part of ci_decode().

Parameters

cmd_list	the command templates
cmd	the command to match
blancs	the field separators
cmdbuf	buffer to hold results

void spr_cmd_ci_print_help_	(	SprStream *	fd,
		const SprCmdDesc *	cmd_list,
		const char *	matchstr,
		const char *	blancs,
		int	matchcnt,
		int	help_level
	)

Print help for a command. Only the command(s) for which at leasts the first matchcnt items match with the matchstr string will be printed.
The amount of output is also controled by help_level:

0: print nothing.
1: print syntax only.
2: print syntax and explanation if there was a unique fit.
3: print syntax and explanation if at least some itmes in matchstr match.
4: print syntax and explanation for all matching commands.

Parameters

fd	destination file
cmd_list	definition of the known commands
matchstr	text to match
blancs	delimiters
matchcnt	minimal #items in matchstr that must match
help_level	how much help is wanted

void spr_cmd_ci_print_help	(	SprStream *	fd,
		const char *	min_match,
		int	help_level,
		SprCmdBuf *	cmdbuf
	)

Print help for a command. Only the command(s) that match min_match for all words specified in the string will be printed. The commands listed are those used in the last ci_decode() with the specified cmdbuf.
The amount of output is also controled by help_level

see ci_print_help_() for more details.

Parameters

fd	destination file
min_match	minimal text to match
help_level	how much help is wanted
cmdbuf	last used cmd-parameters

void spr_cmd_ci_online_help	(	SprStream *	help_dest,
		int	help_flag,
		SprCmdBuf *	cmdbuf
	)

Print a standard message, indicating that the given command was invalid, and if the help_flag is set, print also the correct syntax of the last decoded command.

Parameters

help_dest	destination file
help_flag	also print the correct syntax
cmdbuf	info on last decoded command

char* spr_cmd_ci_arg_ptr ( SprCmdBuf * cmdbuf )

finds the first/next arguments in a command accordingly to the template.

Returns: Pointer to the remaining arguments in the original buffer. If the last word was found a pointer to the empty string is returned (pointer to the terminating null in the original buffer).

Parameters

cmdbuf info on last decoded command

char* spr_cmd_ci_get_arg	(	const char *	defval,
		SprCmdBuf *	cmdbuf
	)

finds the first/next argument in a command accordingly to the parameters in cmdbuf.

Returns: Pointer to the argument (null terminated string). The argument is copied to a static data area, it is overwritten by the next call to ci_get_arg(). If the last word was found, defval is returned. If (defval == NULL), the default value supplied in the template is returned (or NULL if no default value is available).

Parameters

defval	returned if no word was found
cmdbuf	info on last decoded command

int spr_cmd_ci_get_flag	(	const char *	defflag,
		SprCmdBuf *	cmdbuf
	)

Gets the flag number for the next argument. Find the first/next argument in a command accordingly to the parameters in cmdbuf. If (defflag == NULL), the default flag supplied in the template is used, a (-1) is returned if no default value is available.

Returns: Flag number (see ci_check_flag).
-1 on error (next arg was no flag).

Parameters

defflag	flag used if no word was found
cmdbuf	info on last decoded command

int spr_cmd_ci_get_enum	(	const char *	defstr,
		SprCmdBuf *	cmdbuf
	)

Gets the number for the next argument. Find the first/next argument in a command accordingly to the parameters in cmdbuf. If (defstr == NULL), the default flag supplied in the template is used, a (-1) is returned if no default value is available.

Returns: The index number (see hash).
-1 on error (next arg was no flag).

Parameters

defstr	flag used if no word was found
cmdbuf	info on last decoded command

int spr_cmd_ci_get_opts	(	void *	dest_ptr,
		SprCmdBuf *	cmdbuf
	)

Decode the specified options (see ci_check_opts()).

Returns: -1 on error, 0 otherwise.

Parameters

dest_ptr	common dest. offset
cmdbuf	info on last decoded command

int spr_cmd_wait_for_child ( int pid )

Wait for the termination of a child process.

Returns: (~error_code) if the program returned a non zero return code, otherwise the child pid itself is returned.

Note: Currently non operational for Windows.

int spr_cmd_ci_exec	(	char *	Stdin,
		char *	Stdout,
		char *	Stderr,
		const char *	flags,
		const char *	exec_str,
			...
	)

Execute a command. All default streams may be redirected. The following characters in the flags string can be set:

'w': Wait until the process is finished.
'i': Isolate the command in a separated session (incompatible with 'w').
'h': Disable the Hang Up signal.
'p': Parse the exec_str to form the base command and its arguments.
'1': Do not truncate stdout (append to the existing file).
'2': Do not truncate stderr (append to the existing file).

Returns

(-1): if the child process could not be created (out of memory),
(~error_code): if the invoked program ends with an error
(child_pid): if no error occurs (or if the programs termination is not waited for).

Parameters

Stdin	new file to use as stdin
Stdout	new file to use as stdout
Stderr	new file to use as stderr
flags	extra options
exec_str	command to execute

int spr_cmd_execute_string	(	int	waitfor,
		char *	string
	)

returns child ID

Prepares a new process and executes the specified program. Hence execute() performs similar tasks as system(), but it does so in a safer, more controlled, manner.

The specified string is broken into the command and its arguments using the default blanks of the system (spaces, tabulations or 'newlines').

If waitfor is TRUE this function awaits for the specified action to terminate before continuing. Otherwise (if it is FALSE) the action is called and this function moves on, not waiting for the action to terminate; this is the equivalent of a command ran in background (using '&').

With respect to the program name it is important to know that if only the program name is specified (e.g. 'example') the environment variable 'PATH' will be consulted to decide which program to execute. However if you specify a path name with it (if at least one '/' is present) then the PATH is not consulted (e.g. './example').

If this function encounters some kind of problem -1 is returned. Otherwise the child process identification number is returned; unless if waitfor is TRUE, then the return status of the child is returned.

execute_string() can be particularly usefull in combination with kill(). If you want to launch a number of processes in background (waitfor == FALSE) then you can make sure that you do not leave zombie processes behind after terminating the main process if you call kill() with the child process identification number as first argument. All this works because execute_string() executes the specified program in a child process.

Example:

main(int argc,char *argv[])
{int ChildId;
 ...
 ChildId = execute_string("example arg1 arg2",FALSE);
 if(ChildId == -1)
   printf("ERROR: ...");
 ...
 kill(ChildId,SIGTERM);
 exit(0);
 exit(0);
}

Parameters

waitfor	flag TRUE or FALSE
string	character string

int spr_cmd_ci_shell	(	const char *	exec_str,
		const char *	shell
	)

calls the requested shell. If the exec_str is empty, then the shell itself is invoked.

Returns

(-1): if the child process could not be created (out of memory),
(~error_code): if the invoked program ends with an error
(child_pid): if no error occures.

Parameters

exec_str	unix/shell command to execute
shell	shell to use

int spr_cmd_ci_system ( const char * exec_str )

Calls the SHELL used by the user (sh, csh, ksh, ...). If the exec_str is emty, then the shell itself is invoked.
For the return value: see ci_shell.

Parameters

exec_str unix shell command to execute

char* spr_cmd_ci_prompt	(	SprStream *	fd_in,
		SprStream *	fd_out,
		char	buf[],
		int	max_len,
		const char *	prompt
	)

Prompts for input and read a string. The leading blancs (space,tabs) are stripped of. Also the final return is removed. If the line was empty (only blancs), the routine prompts for a new line. If (prompt == NULL) then no prompt is written. The procedure returns a pointer to the buffer. A NULL pointer is returned if one tries to read pat the end of the file. A NULL pointer is also returned if (buf == NULL) or (max_len <= 0).

Parameters

fd_in	file to read from
fd_out	file to write prompt to
buf	destination buffer
max_len	size of the buffer
prompt	prompt string

int spr_str_indexdec	(	int	n,
		const char *	str,
		int *	i1,
		int *	i2
	)

Parses the string str which must have as format "i1:i2" and interprets the two values.

Argument n specifies the upper boundary of the range, which is defined as [0:n-1]. If the string str contains a single integer it is interpreted as "i1:i1". If the string str contains a negative upper or lower boundary, then it is interpreted as "n-<negative_value>". If the str is empty, then "0:n-1" is interpreted;

Returns: 0 if everything was OK and (-1) on error.

int spr_str_mindexdec	(	int	n,
		int	N,
		const char *	str,
		int	istart[],
		int	iend[]
	)

This is a variation of the function spr_str_indexdec(), it accepts a composite input string of the type "i1:j1,i2,i3:j3,...". Argument n specifies the upper boundary of the range, which is defined as [0:n-1]. The indices are returned in the arrays istart and iend. Argument N specified the maximum number of substrings that istart and iend can hold.

Returns: the number of valid substrings that are encountered.

Variable Documentation

const char* const spr_cmd_yes_no_flags[]

char spr_cmd_snull[]

const SprCmdBuf spr_cmd_empty_cmdbuf

empty cmdbuf

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation