interactive.h File Reference

Public API for interactive sessions. More...

Data Structures
struct	i9e_completion_info
	Structure passed as input to the completers. More...
struct	i9e_completion_result
	Completion information returned by the completers. More...
struct	i9e_completer
	A completer is simply a function pointer and name of the command for which it performs completion. More...
struct	i9e_client_info
	The i9e configuration settings of the client. More...

Macros
#define	I9E_DUMMY_COMPLETER(name)
	Define a completer which does nothing. More...

Functions
int	i9e_open (struct i9e_client_info *ici, struct sched *s)
	Register the i9e task and initialize readline. More...
void	i9e_attach_to_stdout (struct btr_node *producer)
	Prepare writing to stdout. More...
void	i9e_print_status_bar (char *buf, unsigned len)
	Print the current status to stderr. More...
void	i9e_close (void)
	Reset the terminal and save the in-memory command line history. More...
void	i9e_signal_dispatch (int sig_num)
	Tell i9e that the caller received a signal. More...
__printf_2_3 void	i9e_log (int ll, const char *fmt,...)
	The log function of the i9e subsystem. More...
int	i9e_poll (struct pollfd *fds, nfds_t nfds, int timeout)
	Wrapper for poll(2) which handles EINTR and returns paraslash error codes. More...
int	i9e_extract_completions (const char *word, char **string_list, char ***result)
	Return the possible completions for a given word. More...
char **	i9e_complete_commands (const char *word, struct i9e_completer *completers)
	Return the list of partially matching words. More...
void	i9e_complete_option (char **opts, struct i9e_completion_info *ci, struct i9e_completion_result *cr)
	Complete according to the given options. More...
int	i9e_print_completions (struct i9e_completer *completers)
	Print possible completions to stdout. More...
int	i9e_get_error (void)
	Return the error state of the i9e task. More...
void	i9e_ll_completer (struct i9e_completion_info *ci, struct i9e_completion_result *cr)
	Complete on severity strings. More...

Detailed Description

Public API for interactive sessions.

Macro Definition Documentation

I9E_DUMMY_COMPLETER

#define I9E_DUMMY_COMPLETER

(

name

)

Value:

                static void name ## _completer( \
                __a_unused struct i9e_completion_info *ciname, \
                struct i9e_completion_result *result) {result->matches = NULL;}

Define a completer which does nothing.

Parameters

name	Determines the name of the function to be defined.

Function Documentation

i9e_open()

int i9e_open	(	struct i9e_client_info *	ici,
		struct sched *	s
	)

Register the i9e task and initialize readline.

Parameters

ici	The i9e configuration parameters set by the caller.
s	The scheduler instance to add the i9e task to.

The caller must allocate and initialize the structure ici points to.

Returns

Standard.

i9e_attach_to_stdout()

void i9e_attach_to_stdout

(

struct btr_node *

producer

)

Prepare writing to stdout.

Parameters

producer

The buffer tree node which produces output.

The i9e subsystem maintains a buffer tree node which may be attached to another node which generates output (a "producer"). When attached, the i9e buffer tree node copies the buffers generated by the producer to stdout.

This function attaches the i9e input queue to an output queue of producer.

References btr_remove_node().

i9e_print_status_bar()

void i9e_print_status_bar	(	char *	buf,
		unsigned	len
	)

Print the current status to stderr.

Parameters

buf	The text to print.
len	The number of bytes in buf.

This clears the bottom line, moves to the beginning of the line and prints the given text. If the length of this text exceeds the width of the terminal, the text is shortened by leaving out a part in the middle.

i9e_close()

void i9e_close

(

void

)

Reset the terminal and save the in-memory command line history.

This should be called before the caller exits.

i9e_signal_dispatch()

void i9e_signal_dispatch

(

int

sig_num

)

Tell i9e that the caller received a signal.

Parameters

sig_num

The number of the signal received.

i9e_log()

__printf_2_3 void i9e_log	(	int	ll,
		const char *	fmt,
			...
	)

The log function of the i9e subsystem.

Parameters

ll	Severity log level.
fmt	Printf-like format string.

This clears the bottom line of the terminal if necessary and writes the string given by fmt to fd[2], where fd[] is the array provided earlier in i9e_open().

i9e_poll()

int i9e_poll	(	struct pollfd *	fds,
		nfds_t	nfds,
		int	timeout
	)

Wrapper for poll(2) which handles EINTR and returns paraslash error codes.

Parameters

fds	See poll(2).
nfds	See poll(2).
timeout	See poll(2).

Returns

See poll(2).

The only difference between this function and xpoll() is that i9e_poll() returns zero if the system call was interrupted while xpoll() restarts the system call in this case.

References ERRNO_TO_PARA_ERROR.

i9e_extract_completions()

int i9e_extract_completions	(	const char *	word,
		char **	string_list,
		char ***	result
	)

Return the possible completions for a given word.

Parameters

word	The word to complete.
string_list	All possible words in this context.
result	String list is returned here.

This function never fails. If no completion was found, a string list of length zero is returned. In any case, the result must be freed by the caller using free_argv().

This function is independent of readline and may be called before i9e_open().

Returns

The number of possible completions.

References alloc().

Referenced by i9e_complete_option(), and i9e_ll_completer().

i9e_complete_commands()

char** i9e_complete_commands	(	const char *	word,
		struct i9e_completer *	completers
	)

Return the list of partially matching words.

Parameters

word	The command to complete.
completers	The array containing all command names.

This is similar to i9e_extract_completions(), but completes on the command names in completers.

Returns

See i9e_extract_completions().

i9e_complete_option()

void i9e_complete_option	(	char **	opts,
		struct i9e_completion_info *	ci,
		struct i9e_completion_result *	cr
	)

Complete according to the given options.

Parameters

opts	All available options.
ci	Information which was passed to the completer.
cr	Result pointer.

This convenience helper can be used to complete an option. The array of all possible options is passed as the first argument. Flags, i.e. options without an argument, are expected to be listed as strings of type "-X" in opts while options which require an argument should be passed with a trailing "=" character like "-X=".

If the word can be uniquely completed to a flag option, an additional space character is appended to the output. For non-flag options no space character is appended.

References i9e_completion_result::dont_append_space, i9e_extract_completions(), i9e_completion_result::matches, and i9e_completion_info::word.

i9e_print_completions()

int i9e_print_completions

(

struct i9e_completer *

completers

)

Print possible completions to stdout.

Parameters

completers

The array of completion functions.

At the end of the output a line starting with "-o=", followed by the (possibly empty) list of completion options is printed. Currently, the only two completion options are "nospace" and "filenames". The former indicates that no space should be appended even for a unique match while the latter indicates that usual filename completion should be performed in addition to the previously printed options.

Returns

Standard.

i9e_get_error()

int i9e_get_error

(

void

)

Return the error state of the i9e task.

This is mainly useful for other tasks to tell whether the i9e task is still running.

Returns

A negative return value of zero means the i9e task terminated. Only in this case it is safe to call i9e_close().

i9e_ll_completer()

void i9e_ll_completer	(	struct i9e_completion_info *	ci,
		struct i9e_completion_result *	cr
	)

Complete on severity strings.

Parameters

ci	See struct i9e_completer.
cr	See struct i9e_completer.

This is used by para_client and para_audioc which need the same completion primitive for the ll server/audiod command. Both define their own completer which is implemented as a trivial wrapper that calls this function.

References i9e_extract_completions(), i9e_completion_result::matches, i9e_completion_info::word, and i9e_completion_info::word_num.