ucommon::shell Class Reference

A utility class for generic shell operations. More...

#include <shell.h>

Inheritance diagram for ucommon::shell:
Inheritance graph
[legend]
Collaboration diagram for ucommon::shell:
Collaboration graph
[legend]

Data Structures

class  charopt
 Character option for shell parsing. More...
class  counteropt
 Counter option for shell parsing. More...
class  errormap
 A class to redefine error messages. More...
class  flagopt
 Flag option for shell parsing. More...
class  groupopt
 Grouping option. More...
class  numericopt
 Numeric option for shell parsing. More...
class  Option
 A base class used to create parsable shell options. More...
class  stringopt
 Text option for shell parsing. More...

Public Types

enum  errmsg_t {
  NOARGS = 0, NOARGUMENT, INVARGUMENT, BADOPTION,
  OPTION_USED, BAD_VALUE, NUMERIC_SET
}
 

Error table index.


typedef void(* exitproc_t )(void)
 Exit handler.
enum  loglevel_t {
  FAIL = 0, ERR, WARN, NOTIFY,
  INFO, DEBUG0
}
 

Level of error logging.


enum  logmode_t {
  NONE = 0, CONSOLE_LOG, USER_LOG, SYSTEM_LOG,
  SECURITY_LOG
}
 

Type of error logging we are using.


typedef bool(* logproc_t )(loglevel_t level, const char *text)
 Log process handler.
typedef cpr_service_t mainproc_t
 Main handler.
enum  numeric_t { NO_NUMERIC, NUMERIC_PLUS, NUMERIC_DASH, NUMERIC_ALL }
 

Numeric mode of parser.


enum  path_t {
  PROGRAM_CONFIG, SERVICE_CONFIG, USER_DEFAULTS, SERVICE_CONTROL,
  USER_HOME = USER_DEFAULTS + 3, SERVICE_DATA, SYSTEM_TEMP, USER_CACHE,
  SERVICE_CACHE, USER_DATA, USER_CONFIG, SYSTEM_CFG,
  SYSTEM_ETC, SYSTEM_VAR, SYSTEM_PREFIX, SYSTEM_SHARE,
  PROGRAM_PLUGINS, PROGRAM_TEMP
}
 

Path types to retrieve.


typedef int pid_t
 Standard type of process id for shell class.

Public Member Functions

unsigned argc (void) const
 Get saved internal argc count for items.
char ** argv (void) const
 Get saved internal argv count for items in this shell object.
const char * argv0 () const
 Get program name (argv0).
void detach (mainproc_t mainentry=(mainproc_t) NULL)
 Detach current process to daemon for service entry.
const char * env (const char *name, const char *value=NULL)
 Get an environment variable.
const char * execdir () const
 Get the exec directory.
const char * get (const char *name, const char *value=NULL)
 Get a local symbol.
char ** getargv (char **argv)
 Get the argument list by parsing options, and return the remaining file arguments.
char * getargv0 (char **argv)
 Parse and extract the argv0 filename alone.
const char * getenv (const char *name, const char *value=NULL)
const char * getsym (const char *name, const char *value=NULL)
bool is_sym (const char *name)
 Test if symbol exists.
unsigned operator() (void)
 Return argc count.
const char * operator[] (unsigned offset)
 Return parser argv element.
void parse (int argc, char **argv)
 Parse the command line arguments using the option table.
char ** parse (const char *string)
 Parse a string as a series of arguments for use in exec calls.
void restart (void)
 Make current process restartable.
void restart (char *argv0, char **argv, char **list)
 Execute front-end like gdb based on stripped first argument.
void set (const char *name, const char *value)
 Set a local symbol.
void setsym (const char *name, const char *value)
 shell (size_t pagesize=0)
 Construct an empty shell parser argument list.
 shell (int argc, char **argv, size_t pagesize=0)
 Construct a shell argument list from existing arguments.
 shell (const char *string, size_t pagesize=0)
 Construct a shell argument list by parsing a simple command string.

Static Public Member Functions

static void bind (const char *name)
 Bind application to text domain for internationalization.
static int cancel (shell::pid_t pid)
 Cancel a child process.
static int condition (bool test, int exitcode)
 Convert condition to exit code if true.
static unsigned count (char **argv)
 Get argc count for an existing array.
static void debug (unsigned level, const char *format,...)
 Print a debug message by debug level.
static int detach (const char *path, char **argv, char **env=NULL, fd_t *stdio=NULL)
 Create a detached process.
static void errexit (int exitcode, const char *format=NULL,...)
 Print error message and exit.
static void errmsg (errmsg_t id, const char *text)
 This is used to set internationalized error messages for the shell parser.
static const char * errmsg (errmsg_t id)
 This can be used to get internationalized error messages.
static fd_t error (void)
static void error (const char *format,...)
 Print error message and continue.
static void exiting (exitproc_t)
static char * getline (const char *prompt, char *buffer, size_t size)
static long getNumeric (void)
static char * getpass (const char *prompt, char *buffer, size_t size)
static void help (void)
 Display shell options.
static int inkey (const char *prompt=NULL)
static fd_t input (void)
static void log (const char *name, loglevel_t level=ERR, logmode_t mode=USER_LOG, logproc_t handler=(logproc_t) NULL)
 Set logging level and state.
static void log (loglevel_t level, const char *format,...)
 Print generic error message at specific error level.
static fd_t output (void)
static String path (String &prefix, const char *directory)
 Join a prefix with a path.
static String path (path_t id, const char *directory)
 Get a merged path.
static String path (path_t id)
 Get a system path.
static size_t printf (const char *format,...)
 Print to standard output.
static void priority (int pri=1)
 Set priority level and enable priority scheduler.
static size_t read (String &string)
static size_t readln (char *address, size_t size)
static void rebind (const char *name=NULL)
 Rebind is used to change the text domain.
static void release (int exit_code=0)
 Detach and release from parent process with exit code.
static void relocate (const char *argv0)
 Set relative prefix.
static void security (loglevel_t level, const char *format,...)
 Print security error message at specific error level.
static void setNumeric (numeric_t)
static shell::pid_t spawn (const char *path, char **argv, char **env=NULL, fd_t *stdio=NULL)
 Spawn a child process.
static int system (const char *command, const char **env=NULL)
 A shell system call.
static int systemf (const char *format,...)
 A shell system call that can be issued using a formatted string.
static const char * text (const char *string)
 Text translation and localization.
static const char * texts (const char *singular, const char *plural, unsigned long count)
 Plural text translation and localization.
static String userid (void)
 Get the system login id.
static int wait (shell::pid_t pid)
 Wait for a child process to terminate.
static size_t write (String &string)
static size_t writes (const char *string)

Detailed Description

A utility class for generic shell operations.

This includes utilities to parse and expand arguments, and to call system shell services. This also includes a common shell class to parse and process command line arguments which are managed through a local heap.

Author:
David Sugar <dyfet@gnutelephony.org>

Definition at line 62 of file shell.h.


Constructor & Destructor Documentation

ucommon::shell::shell ( const char *  string,
size_t  pagesize = 0 
)

Construct a shell argument list by parsing a simple command string.

This separates a string into a list of command line arguments which can be used with exec functions.

Parameters:
string to parse.
pagesize for local heap.
ucommon::shell::shell ( int  argc,
char **  argv,
size_t  pagesize = 0 
)

Construct a shell argument list from existing arguments.

This copies and on some platforms expands the argument list originally passed to main.

Parameters:
argc from main.
argv from main.
pagesize for local heap.
ucommon::shell::shell ( size_t  pagesize = 0  ) 

Construct an empty shell parser argument list.

Parameters:
pagesize for local heap.

Member Function Documentation

unsigned ucommon::shell::argc ( void   )  const [inline]

Get saved internal argc count for items.

This may be items that remain after shell expansion and options have been parsed.

Returns:
count of remaining arguments.

Definition at line 690 of file shell.h.

char** ucommon::shell::argv ( void   )  const [inline]

Get saved internal argv count for items in this shell object.

This may be filename items only that remain after shell expansion and options that have been parsed.

Returns:
list of remaining arguments.

Definition at line 699 of file shell.h.

static void ucommon::shell::bind ( const char *  name  )  [static]

Bind application to text domain for internationalization.

This is useful if the argv0 argument can vary because of a symlinked executable. This is the name of the .po/.mo message files for your application. If bind is not called before shell processing, then the argv0 is used as the bind name. Bind can be called multiple times to change the default message catalog name of the application, and this usage may be needed for plugins, though it's generally recommended to use only once, and at the start of main().

Parameters:
name of text domain for the application.
static int ucommon::shell::cancel ( shell::pid_t  pid  )  [static]

Cancel a child process.

Parameters:
pid of child process to cancel.
Returns:
exit code of process, -1 if fails or pid is invalid.
static int ucommon::shell::condition ( bool  test,
int  exitcode 
) [inline, static]

Convert condition to exit code if true.

Parameters:
test condition.
exitcode to use if true.

Definition at line 637 of file shell.h.

static unsigned ucommon::shell::count ( char **  argv  )  [static]

Get argc count for an existing array.

Parameters:
argv to count items in.
Returns:
argc count of array.
static void ucommon::shell::debug ( unsigned  level,
const char *  format,
  ... 
) [static]

Print a debug message by debug level.

Parameters:
level of debug message.
format string to use.
static int ucommon::shell::detach ( const char *  path,
char **  argv,
char **  env = NULL,
fd_t *  stdio = NULL 
) [static]

Create a detached process.

This creates a new child process that is completely detached from the current process.

Parameters:
path to executable.
argv list of command arguments for the child process.
env of child process can be explicitly set.
stdio handles for stdin, stdout, and stderr.
Returns:
0 if success, -1 on error.
const char* ucommon::shell::env ( const char *  name,
const char *  value = NULL 
)

Get an environment variable.

This creates a local copy of the variable in pager memory.

Parameters:
name of symbol.
value of symbol if not found.
Returns:
value of symbol.
static void ucommon::shell::errexit ( int  exitcode,
const char *  format = NULL,
  ... 
) [static]

Print error message and exit.

Ignored if exitcode == 0.

Parameters:
exitcode to return to parent process.
format string to use.
static void ucommon::shell::errmsg ( errmsg_t  id,
const char *  text 
) [static]

This is used to set internationalized error messages for the shell parser.

Parameters:
id of message to set.
text for error message.
static const char* ucommon::shell::errmsg ( errmsg_t  id  )  [static]

This can be used to get internationalized error messages.

The internal text for shell parser errors are passed through here.

Parameters:
id of error message to use.
Returns:
published text of error message.
static void ucommon::shell::error ( const char *  format,
  ... 
) [static]

Print error message and continue.

Parameters:
format string to use.
const char* ucommon::shell::get ( const char *  name,
const char *  value = NULL 
)

Get a local symbol.

This uses getenv if no local symbol is found.

Parameters:
name of symbol.
value of symbol if not found.
Returns:
value of symbol.
char** ucommon::shell::getargv ( char **  argv  ) 

Get the argument list by parsing options, and return the remaining file arguments.

This is used by parse, and can be fed by main by posting ++argv.

Parameters:
argv of first option.
Returns:
argv of non-option file list.
char* ucommon::shell::getargv0 ( char **  argv  ) 

Parse and extract the argv0 filename alone.

Parameters:
argv from main.
Returns:
argv0 simple path name.
bool ucommon::shell::is_sym ( const char *  name  ) 

Test if symbol exists.

Parameters:
name of symbol.
Returns:
true if found.
static void ucommon::shell::log ( const char *  name,
loglevel_t  level = ERR,
logmode_t  mode = USER_LOG,
logproc_t  handler = (logproc_t) NULL 
) [static]

Set logging level and state.

Parameters:
name of logging entity.
level of error conditions to log.
mode of logging.
handler for log messages.
static void ucommon::shell::log ( loglevel_t  level,
const char *  format,
  ... 
) [static]

Print generic error message at specific error level.

Parameters:
level of error condition.
format string to use.
unsigned ucommon::shell::operator() ( void   )  [inline]

Return argc count.

Returns:
argc count.

Definition at line 780 of file shell.h.

const char* ucommon::shell::operator[] ( unsigned  offset  )  [inline]

Return parser argv element.

Parameters:
offset into array.
Returns:
argument string.

Definition at line 707 of file shell.h.

void ucommon::shell::parse ( int  argc,
char **  argv 
)

Parse the command line arguments using the option table.

File arguments will be expanded for wildcards on some platforms. The argv will be set to the first file argument after all options are parsed.

Parameters:
argc from main.
argv from main.
char** ucommon::shell::parse ( const char *  string  ) 

Parse a string as a series of arguments for use in exec calls.

Parameters:
string to parse.
Returns:
argument array.
static String ucommon::shell::path ( String prefix,
const char *  directory 
) [static]

Join a prefix with a path.

Parameters:
prefix to merge with.
directory or file path to merge.
static String ucommon::shell::path ( path_t  id,
const char *  directory 
) [static]

Get a merged path.

If the path requested is a full path, then the prefix is ignored.

Parameters:
id of prefix.
directory path to merge with prefix.
static String ucommon::shell::path ( path_t  id  )  [static]

Get a system path.

This is used to get directories for application specific data stores and default paths for config keys.

Parameters:
id of path to return.
Returns:
path string or emptry string if not supported.
static size_t ucommon::shell::printf ( const char *  format,
  ... 
) [static]

Print to standard output.

Parameters:
format string to use.
static void ucommon::shell::priority ( int  pri = 1  )  [static]

Set priority level and enable priority scheduler.

This activates the realtime priority scheduler when a priority > 0 is requested for the process, assuming scheduler support exists and the process is sufficiently privileged. Negative priorities are essentially the same as nice.

Parameters:
pri level for process.
static void ucommon::shell::rebind ( const char *  name = NULL  )  [static]

Rebind is used to change the text domain.

This may be needed in applications which have separately built plugins that have thier own message catalogs. Normally the plugin would call bind itself at initialization, and then use rebind to select either the application's domain, or the plugins. On systems without internationalization, this has no effect.

Parameters:
name of text domain of plugin or NULL to restore application.
static void ucommon::shell::release ( int  exit_code = 0  )  [static]

Detach and release from parent process with exit code.

Parameters:
exit_code to send to parent process.
static void ucommon::shell::relocate ( const char *  argv0  )  [static]

Set relative prefix.

Used for OS/X relocatable applications.

Parameters:
argv0 path of executable.
void ucommon::shell::restart ( char *  argv0,
char **  argv,
char **  list 
)

Execute front-end like gdb based on stripped first argument.

Parameters:
argv0 of our executable.
argv to pass to child.
list of arguments to execute in front of argv.
static void ucommon::shell::security ( loglevel_t  level,
const char *  format,
  ... 
) [static]

Print security error message at specific error level.

Parameters:
level of error condition.
format string to use.
void ucommon::shell::set ( const char *  name,
const char *  value 
)

Set a local symbol.

Parameters:
name of symbol to set.
value of symbol to set.
static shell::pid_t ucommon::shell::spawn ( const char *  path,
char **  argv,
char **  env = NULL,
fd_t *  stdio = NULL 
) [static]

Spawn a child process.

This creates a new child process. If the executable path is a pure filename, then the $PATH will be used to find it. The argv array may be created from a string with the shell string parser.

Parameters:
path to executable.
argv list of command arguments for the child process.
env of child process can be explicitly set.
stdio handles for stdin, stdout, and stderr.
Returns:
process id of child or INVALID_PID_VALUE if fails.
static int ucommon::shell::system ( const char *  command,
const char **  env = NULL 
) [static]

A shell system call.

This uses the native system shell to invoke the command.

Parameters:
command string..
env array to optionally use.
Returns:
error code of child process.
static int ucommon::shell::systemf ( const char *  format,
  ... 
) [static]

A shell system call that can be issued using a formatted string.

This uses the native system shell to invoke the command.

Parameters:
format of/command string.
Returns:
error code of child process.
static const char* ucommon::shell::text ( const char *  string  )  [static]

Text translation and localization.

This function does nothing but return the original string if no internationalization support is available. If internationalization support exists, then it may return a substituted translation based on the current locale. This offers a single function that can be safely used either when internationalization support is present, or it is absent, eliminating the need for the application to be coded differently based on awareness of support.

Parameters:
string to translate.
Returns:
translation if found or original text.
static const char* ucommon::shell::texts ( const char *  singular,
const char *  plural,
unsigned long  count 
) [static]

Plural text translation and localization.

This does nothing but return single or plural forms if no internationalization is enabled. Else it uses ngettext().

Parameters:
singular string to translate.
plural string to translate.
count of objects.
Returns:
string to use.
static String ucommon::shell::userid ( void   )  [static]

Get the system login id.

Returns:
login id.
static int ucommon::shell::wait ( shell::pid_t  pid  )  [static]

Wait for a child process to terminate.

This operation blocks.

Parameters:
pid of process to wait for.
Returns:
exit code of process, -1 if fails or pid is invalid.

The documentation for this class was generated from the following file:

Generated on 30 Jul 2013 for UCommon by  doxygen 1.6.1