UCommon
ucommon::shell Class Reference

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

#include <shell.h>

Inheritance diagram for ucommon::shell:
Collaboration diagram for ucommon::shell:

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. More...
 
typedef void(* exitproc_t) (void)
 Exit handler.
 
enum  loglevel_t {
  FAIL = 0 , ERR , WARN , NOTIFY ,
  INFO , DEBUG0
}
 Level of error logging. More...
 
enum  logmode_t {
  NONE = 0 , CONSOLE_LOG , USER_LOG , SYSTEM_LOG ,
  SECURITY_LOG
}
 Type of error logging we are using. More...
 
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. More...
 
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. More...
 
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 * execdir () const
 Get the exec directory.
 
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)
 Get an environment variable.
 
const char * getsym (const char *name, const char *value=NULL)
 Get a local symbol.
 
bool is_sym (const char *name) const
 Test if symbol exists.
 
unsigned operator() (void) const
 Return argc count.
 
const char * operator[] (unsigned offset)
 Return parser argv element.
 
char ** parse (const char *string)
 Parse a string as a series of arguments for use in exec calls.
 
void parse (int argc, char **argv)
 Parse the command line arguments using the option table.
 
void restart (char *argv0, char **argv, char **list)
 Execute front-end like gdb based on stripped first argument.
 
void restart (void)
 Make current process restartable.
 
void setsym (const char *name, const char *value)
 Set a local symbol.
 
 shell (const char *string, size_t pagesize=0)
 Construct a shell argument list by parsing a simple command string.
 
 shell (int argc, char **argv, size_t pagesize=0)
 Construct a shell argument list from existing arguments.
 
 shell (size_t pagesize=0)
 Construct an empty shell parser argument list.
 
- Public Member Functions inherited from ucommon::mempager
void assign (mempager &source)
 Assign foreign pager to us.
 
virtual void dealloc (void *memory)
 Return memory back to pager heap.
 
 mempager (const mempager &copy)
 
 mempager (size_t page=0)
 Construct a memory pager.
 
void purge (void)
 Purge all allocated memory and heap pages immediately.
 
unsigned utilization (void)
 Determine fragmentation level of acquired heap pages.
 
virtual ~mempager ()
 Destroy a memory pager.
 
- Public Member Functions inherited from ucommon::memalloc
void assign (memalloc &source)
 Assign foreign pager to us.
 
unsigned max (void) const
 Get the maximum number of pages that are permitted.
 
 memalloc (const memalloc &copy)
 
 memalloc (size_t page=0)
 Construct a memory pager.
 
unsigned pages (void) const
 Get the number of pages that have been allocated from the real heap.
 
void purge (void)
 Purge all allocated memory and heap pages immediately.
 
size_t size (void) const
 Get the size of a memory page.
 
unsigned utilization (void) const
 Determine fragmentation level of acquired heap pages.
 
virtual ~memalloc ()
 Destroy a memory pager.
 

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 errlog (const char *format,...)
 Print error message and continue.
 
static const char * errmsg (errmsg_t id)
 This can be used to get internationalized error messages.
 
static void errmsg (errmsg_t id, const char *text)
 This is used to set internationalized error messages for the shell parser.
 
static fd_t error (void)
 
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 (path_t id)
 Get a system path.
 
static String path (path_t id, const char *directory)
 Get a merged path.
 
static String path (String &prefix, const char *directory)
 Join a prefix with a path.
 
static size_t printf (const char *format,...)
 
static void priority (int pri=1)
 Set priority level and enable priority scheduler.
 
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.
 

Additional Inherited Members

- Protected Member Functions inherited from ucommon::mempager
virtual void * _alloc (size_t size)
 Allocate memory from the pager heap.
 
virtual void _lock (void)
 Lock the memory pager mutex.
 
virtual void _unlock (void)
 Unlock the memory pager mutex.
 
- Protected Member Functions inherited from ucommon::memalloc
page_t * pager (void)
 Acquire a new page from the heap.
 
- Protected Attributes inherited from ucommon::memalloc
unsigned limit
 

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.nosp@m.@gnu.nosp@m.telep.nosp@m.hony.nosp@m..org
Examples
shell.cpp.

Definition at line 59 of file shell.h.

Member Typedef Documentation

◆ exitproc_t

typedef void(* ucommon::shell::exitproc_t) (void)

Exit handler.

Definition at line 139 of file shell.h.

◆ logproc_t

typedef bool(* ucommon::shell::logproc_t) (loglevel_t level, const char *text)

Log process handler.

Definition at line 129 of file shell.h.

◆ mainproc_t

typedef cpr_service_t ucommon::shell::mainproc_t

Main handler.

Definition at line 134 of file shell.h.

◆ pid_t

typedef int ucommon::shell::pid_t

Standard type of process id for shell class.

Definition at line 147 of file shell.h.

Member Enumeration Documentation

◆ errmsg_t

Error table index.

Definition at line 99 of file shell.h.

◆ loglevel_t

Level of error logging.

Definition at line 109 of file shell.h.

◆ logmode_t

Type of error logging we are using.

Definition at line 104 of file shell.h.

◆ numeric_t

Numeric mode of parser.

Definition at line 114 of file shell.h.

◆ path_t

Path types to retrieve.

Definition at line 119 of file shell.h.

Constructor & Destructor Documentation

◆ shell() [1/3]

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
stringto parse.
pagesizefor local heap.

◆ shell() [2/3]

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
argcfrom main.
argvfrom main.
pagesizefor local heap.

◆ shell() [3/3]

ucommon::shell::shell ( size_t pagesize = 0)

Construct an empty shell parser argument list.

Parameters
pagesizefor local heap.

Member Function Documentation

◆ argc()

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 732 of file shell.h.

◆ argv()

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 741 of file shell.h.

◆ argv0()

const char * ucommon::shell::argv0 ( ) const
inline

Get program name (argv0).

Definition at line 664 of file shell.h.

◆ bind()

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
nameof text domain for the application.

◆ cancel()

static int ucommon::shell::cancel ( shell::pid_t pid)
static

Cancel a child process.

Parameters
pidof child process to cancel.
Returns
exit code of process, -1 if fails or pid is invalid.

◆ condition()

static int ucommon::shell::condition ( bool test,
int exitcode )
inlinestatic

Convert condition to exit code if true.

Parameters
testcondition.
exitcodeto use if true.

Definition at line 691 of file shell.h.

◆ count()

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

Get argc count for an existing array.

Parameters
argvto count items in.
Returns
argc count of array.

◆ debug()

static void ucommon::shell::debug ( unsigned level,
const char * format,
... )
static

Print a debug message by debug level.

Parameters
levelof debug message.
formatstring to use.

◆ detach()

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
pathto executable.
argvlist of command arguments for the child process.
envof child process can be explicitly set.
stdiohandles for stdin, stdout, and stderr.
Returns
0 if success, -1 on error.

◆ errexit()

static void ucommon::shell::errexit ( int exitcode,
const char * format = NULL,
... )
static

Print error message and exit.

Ignored if exitcode == 0.

Parameters
exitcodeto return to parent process.
formatstring to use.

◆ errlog()

static void ucommon::shell::errlog ( const char * format,
... )
static

Print error message and continue.

Parameters
formatstring to use.

◆ errmsg() [1/2]

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
idof error message to use.
Returns
published text of error message.

◆ errmsg() [2/2]

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
idof message to set.
textfor error message.

◆ error()

static fd_t ucommon::shell::error ( void )
inlinestatic

Definition at line 875 of file shell.h.

◆ execdir()

const char * ucommon::shell::execdir ( ) const
inline

Get the exec directory.

Definition at line 670 of file shell.h.

◆ getargv()

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
argvof first option.
Returns
argv of non-option file list.

◆ getargv0()

char * ucommon::shell::getargv0 ( char ** argv)

Parse and extract the argv0 filename alone.

Parameters
argvfrom main.
Returns
argv0 simple path name.

◆ getenv()

const char * ucommon::shell::getenv ( const char * name,
const char * value = NULL )

Get an environment variable.

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

Parameters
nameof symbol.
valueof symbol if not found.
Returns
value of symbol.

◆ getsym()

const char * ucommon::shell::getsym ( const char * name,
const char * value = NULL )

Get a local symbol.

This uses getenv if no local symbol is found.

Parameters
nameof symbol.
valueof symbol if not found.
Returns
value of symbol.

◆ input()

static fd_t ucommon::shell::input ( void )
inlinestatic

Definition at line 869 of file shell.h.

◆ is_sym()

bool ucommon::shell::is_sym ( const char * name) const

Test if symbol exists.

Parameters
nameof symbol.
Returns
true if found.

◆ log() [1/2]

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
nameof logging entity.
levelof error conditions to log.
modeof logging.
handlerfor log messages.

◆ log() [2/2]

static void ucommon::shell::log ( loglevel_t level,
const char * format,
... )
static

Print generic error message at specific error level.

Parameters
levelof error condition.
formatstring to use.

◆ operator()()

unsigned ucommon::shell::operator() ( void ) const
inline

Return argc count.

Returns
argc count.

Definition at line 822 of file shell.h.

◆ operator[]()

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

Return parser argv element.

Parameters
offsetinto array.
Returns
argument string.

Definition at line 749 of file shell.h.

◆ output()

static fd_t ucommon::shell::output ( void )
inlinestatic

Definition at line 872 of file shell.h.

◆ parse() [1/2]

char ** ucommon::shell::parse ( const char * string)

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

Parameters
stringto parse.
Returns
argument array.

◆ parse() [2/2]

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
argcfrom main.
argvfrom main.

◆ path() [1/3]

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
idof path to return.
Returns
path string or emptry string if not supported.

◆ path() [2/3]

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
idof prefix.
directorypath to merge with prefix.

◆ path() [3/3]

static String ucommon::shell::path ( String & prefix,
const char * directory )
static

Join a prefix with a path.

Parameters
prefixto merge with.
directoryor file path to merge.

◆ priority()

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
prilevel for process.

◆ rebind()

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
nameof text domain of plugin or NULL to restore application.

◆ release()

static void ucommon::shell::release ( int exit_code = 0)
static

Detach and release from parent process with exit code.

Parameters
exit_codeto send to parent process.

◆ relocate()

static void ucommon::shell::relocate ( const char * argv0)
static

Set relative prefix.

Used for OS/X relocatable applications.

Parameters
argv0path of executable.

◆ restart()

void ucommon::shell::restart ( char * argv0,
char ** argv,
char ** list )

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

Parameters
argv0of our executable.
argvto pass to child.
listof arguments to execute in front of argv.

◆ security()

static void ucommon::shell::security ( loglevel_t level,
const char * format,
... )
static

Print security error message at specific error level.

Parameters
levelof error condition.
formatstring to use.

◆ setsym()

void ucommon::shell::setsym ( const char * name,
const char * value )

Set a local symbol.

Parameters
nameof symbol to set.
valueof symbol to set.

◆ spawn()

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
pathto executable.
argvlist of command arguments for the child process.
envof child process can be explicitly set.
stdiohandles for stdin, stdout, and stderr.
Returns
process id of child or INVALID_PID_VALUE if fails.

◆ system()

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
commandstring..
envarray to optionally use.
Returns
error code of child process.

◆ systemf()

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
formatof/command string.
Returns
error code of child process.

◆ text()

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
stringto translate.
Returns
translation if found or original text.

◆ texts()

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
singularstring to translate.
pluralstring to translate.
countof objects.
Returns
string to use.

◆ userid()

static String ucommon::shell::userid ( void )
static

Get the system login id.

Returns
login id.

◆ wait()

static int ucommon::shell::wait ( shell::pid_t pid)
static

Wait for a child process to terminate.

This operation blocks.

Parameters
pidof 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: