ucommon
Data Structures | Public Types | Public Member Functions | Static Public Member Functions
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  iobuf
 Process pipe with I/O buffering. More...
class  numericopt
 Numeric option for shell parsing. More...
class  Option
 A base class used to create parsable shell options. More...
class  pipeio
 A class to control a process that is piped. 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.
typedef iobuf io_t
 Buffered i/o type for pipes and stdio.
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, 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.
typedef pipeiopipe_t
 Convenience low level pipe object type.
enum  pmode_t { RD = BufferProtocol::BUF_RD, WR = BufferProtocol::BUF_WR, RDWR = BufferProtocol::BUF_RDWR }
 Pipe I/O mode.

Public Member Functions

unsigned argc (void)
 Get saved internal argc count for items.
char ** argv (void)
 Get saved internal argv count for items in this shell object.
char * argv0 ()
 Get program name (argv0).
void detach (mainproc_t mainentry=(mainproc_t)((void *) 0))
 Detach current process to daemon for service entry.
char * execdir ()
 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.
char * getenv (char *name, char *value=((void *) 0))
 Get an environment variable.
char * getsym (char *name, char *value=((void *) 0))
 Get a local symbol.
bool issym (char *name)
 Test if symbol exists.
unsigned operator() (void)
 Return argc count.
char * operator[] (unsigned offset)
 Return parser argv element.
char ** parse (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 (char *name, char *value)
 Set a local symbol.
 shell (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
virtual void * _alloc (size_t size)
 Allocate memory from the pager heap.
virtual void dealloc (void *memory)
 Return memory back to pager heap.
 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
unsigned getAlloc (void)
 Get the size of a memory page.
unsigned getLimit (void)
 Get the maximum number of pages that are permitted.
unsigned getPages (void)
 Get the number of pages that have been allocated from the real heap.
 memalloc (size_t page=0)
 Construct a memory pager.
virtual ~memalloc ()
 Destroy a memory pager.
- Public Member Functions inherited from ucommon::MemoryProtocol
void * alloc (size_t size)
 Convenience function.
char * dup (const char *string)
 Duplicate NULL terminated string into allocated memory.
void * dup (void *memory, size_t size)
 Duplicate existing memory block into allocated memory.
void * zalloc (size_t size)
 Allocate memory from the pager heap.

Static Public Member Functions

static void bind (char *name)
 Bind application to text domain for internationalization.
static int cancel (shell::pid_t pid)
 Cancel a child process.
static int cancel (shell::pipe_t pointer)
 Cancel a child pipe.
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, char *format,...)
 Print a debug message by debug level.
static int detach (char *path, char **argv, char **env=((void *) 0), fd_t *stdio=((void *) 0))
 Create a detached process.
static void errexit (int exitcode, char *format=((void *) 0),...)
 Print error message and exit.
static char * errmsg (errmsg_t id)
 This can be used to get internationalized error messages.
static void errmsg (errmsg_t id, char *text)
 This is used to set internationalized error messages for the shell parser.
static void error (char *format,...)
 Print error message and continue.
static fd_t error (void)
static void exiting (exitproc_t)
static char * getline (char *prompt, char *buffer, size_t size)
static long getNumeric (void)
static char * getpass (char *prompt, char *buffer, size_t size)
static void help (void)
 Display shell options.
static int inkey (char *prompt=((void *) 0))
static fd_t input (void)
static void log (loglevel_t level, char *format,...)
 Print generic error message at specific error level.
static void log (char *name, loglevel_t level=ERR, logmode_t mode=USER_LOG, logproc_t handler=(logproc_t)((void *) 0))
 Set logging level and state.
static fd_t output (void)
static char ** parse (shell &args, char *string)
 Parse shell arguments directly into a shell object.
static String path (path_t id)
 Get a system path.
static String path (path_t id, char *directory)
 Get a merged path.
static String path (String &prefix, char *directory)
 Join a prefix with a path.
static size_t printf (char *format,...)
 Print to standard output.
static size_t printf (pipe_t pipe, char *format,...)
 Print to a pipe object.
static void priority (int pri=1)
 Set priority level and enable priority scheduler.
static size_t read (String &string)
static size_t read (pipe_t pipe, String &string)
static size_t readln (char *address, size_t size)
static size_t readln (pipe_t pipe, char *buffer, size_t size)
 Read a line from a pipe object.
static void rebind (char *name=((void *) 0))
 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 (char *argv0)
 Set relative prefix.
static void security (loglevel_t level, char *format,...)
 Print security error message at specific error level.
static void setNumeric (numeric_t)
static shell::pid_t spawn (char *path, char **argv, char **env=((void *) 0), fd_t *stdio=((void *) 0))
 Spawn a child process.
static shell::pipe_t spawn (char *path, char **argv, pmode_t mode, size_t size=512, char **env=((void *) 0))
 Spawn a child pipe.
static int system (char *command, char **env=((void *) 0))
 A shell system call.
static int systemf (char *format,...)
 A shell system call that can be issued using a formatted string.
static char * text (char *string)
 Text translation and localization.
static char * texts (char *singular, 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 int wait (shell::pipe_t pointer)
 Wait for a child pipe to terminate.
static size_t write (String &string)
static size_t write (pipe_t pipe, String &string)
static size_t writes (char *string)
static size_t writes (pipe_t pipe, char *string)

Additional Inherited Members

- Protected Member Functions inherited from ucommon::mempager
virtual void _lock (void)
 Lock the memory pager mutex.
virtual void _unlock (void)
 Unlock the memory pager mutex.
- 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

Definition at line 62 of file shell.h.

Constructor & Destructor Documentation

ucommon::shell::shell ( 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.
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.
ucommon::shell::shell ( size_t  pagesize = 0)

Construct an empty shell parser argument list.

Parameters
pagesizefor local heap.

Member Function Documentation

unsigned ucommon::shell::argc ( void  )
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 864 of file shell.h.

char** ucommon::shell::argv ( void  )
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 873 of file shell.h.

static void ucommon::shell::bind ( 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.
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.
static int ucommon::shell::cancel ( shell::pipe_t  pointer)
static

Cancel a child pipe.

If the pipe io handle is dynamic, it is deleted.

Parameters
pointerto pipe 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 
)
inlinestatic

Convert condition to exit code if true.

Parameters
testcondition.
exitcodeto use if true.

Definition at line 787 of file shell.h.

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.
static void ucommon::shell::debug ( unsigned  level,
char *  format,
  ... 
)
static

Print a debug message by debug level.

Parameters
levelof debug message.
formatstring to use.
static int ucommon::shell::detach ( char *  path,
char **  argv,
char **  env = ((void *) 0),
fd_t *  stdio = ((void *) 0) 
)
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.
static void ucommon::shell::errexit ( int  exitcode,
char *  format = ((void *) 0),
  ... 
)
static

Print error message and exit.

Ignored if exitcode == 0.

Parameters
exitcodeto return to parent process.
formatstring to use.
static 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.
static void ucommon::shell::errmsg ( errmsg_t  id,
char *  text 
)
static

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

Parameters
idof message to set.
textfor error message.
static void ucommon::shell::error ( char *  format,
  ... 
)
static

Print error message and continue.

Parameters
formatstring to use.
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.
char* ucommon::shell::getargv0 ( char **  argv)

Parse and extract the argv0 filename alone.

Parameters
argvfrom main.
Returns
argv0 simple path name.
char* ucommon::shell::getenv ( char *  name,
char *  value = ((void *) 0) 
)

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.
char* ucommon::shell::getsym ( char *  name,
char *  value = ((void *) 0) 
)

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.
bool ucommon::shell::issym ( char *  name)

Test if symbol exists.

Parameters
nameof symbol.
Returns
true if found.
static void ucommon::shell::log ( loglevel_t  level,
char *  format,
  ... 
)
static

Print generic error message at specific error level.

Parameters
levelof error condition.
formatstring to use.
static void ucommon::shell::log ( char *  name,
loglevel_t  level = ERR,
logmode_t  mode = USER_LOG,
logproc_t  handler = (logproc_t)((void *) 0) 
)
static

Set logging level and state.

Parameters
nameof logging entity.
levelof error conditions to log.
modeof logging.
handlerfor log messages.
unsigned ucommon::shell::operator() ( void  )
inline

Return argc count.

Returns
argc count.

Definition at line 982 of file shell.h.

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

Return parser argv element.

Parameters
offsetinto array.
Returns
argument string.

Definition at line 881 of file shell.h.

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

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

Parameters
stringto parse.
Returns
argument array.
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.
static char** ucommon::shell::parse ( shell args,
char *  string 
)
inlinestatic

Parse shell arguments directly into a shell object.

Parameters
argstable.
stringto parse.
Returns
argument array.

Definition at line 753 of file shell.h.

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.
static String ucommon::shell::path ( path_t  id,
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.
static String ucommon::shell::path ( String prefix,
char *  directory 
)
static

Join a prefix with a path.

Parameters
prefixto merge with.
directoryor file path to merge.
static size_t ucommon::shell::printf ( char *  format,
  ... 
)
static

Print to standard output.

Parameters
formatstring to use.
static size_t ucommon::shell::printf ( pipe_t  pipe,
char *  format,
  ... 
)
static

Print to a pipe object.

Parameters
pipeto write to.
formatstring to use.
Returns
number of bytes written.
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.
static size_t ucommon::shell::readln ( pipe_t  pipe,
char *  buffer,
size_t  size 
)
static

Read a line from a pipe object.

Parameters
pipeto read from.
bufferto save into.
sizeof buffer.
Returns
number of bytes read.
static void ucommon::shell::rebind ( char *  name = ((void *) 0))
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.
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.
static void ucommon::shell::relocate ( char *  argv0)
static

Set relative prefix.

Used for OS/X relocatable applications.

Parameters
argv0path of executable.
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.
static void ucommon::shell::security ( loglevel_t  level,
char *  format,
  ... 
)
static

Print security error message at specific error level.

Parameters
levelof error condition.
formatstring to use.
void ucommon::shell::setsym ( char *  name,
char *  value 
)

Set a local symbol.

Parameters
nameof symbol to set.
valueof symbol to set.
static shell::pid_t ucommon::shell::spawn ( char *  path,
char **  argv,
char **  env = ((void *) 0),
fd_t *  stdio = ((void *) 0) 
)
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.
static shell::pipe_t ucommon::shell::spawn ( char *  path,
char **  argv,
pmode_t  mode,
size_t  size = 512,
char **  env = ((void *) 0) 
)
static

Spawn a child pipe.

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.
modeof pipe, rd only, wr only, or rdwr.
sizeof pipe buffer.
envof child process can be explicitly set.
Returns
pipe object or NULL on failure.
static int ucommon::shell::system ( char *  command,
char **  env = ((void *) 0) 
)
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.
static int ucommon::shell::systemf ( 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.
static char* ucommon::shell::text ( 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.
static char* ucommon::shell::texts ( char *  singular,
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.
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
pidof process to wait for.
Returns
exit code of process, -1 if fails or pid is invalid.
static int ucommon::shell::wait ( shell::pipe_t  pointer)
static

Wait for a child pipe to terminate.

This operation blocks. If the pipe io handle is dynamic, it is deleted.

Parameters
pointerto pipe of child 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: