UCommon
|
A utility class for generic shell operations. More...
#include <shell.h>
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 pipeio * | pipe_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. | |
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) |
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.
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.
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.
argc | from main. |
argv | from main. |
pagesize | for local heap. |
ucommon::shell::shell | ( | size_t | pagesize = 0 | ) |
Construct an empty shell parser argument list.
pagesize | for local heap. |
unsigned ucommon::shell::argc | ( | void | ) | [inline] |
char** ucommon::shell::argv | ( | void | ) | [inline] |
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().
name | of text domain for the application. |
static int ucommon::shell::cancel | ( | shell::pid_t | pid | ) | [static] |
Cancel a child process.
pid | of child process to cancel. |
static int ucommon::shell::cancel | ( | shell::pipe_t | pointer | ) | [static] |
Cancel a child pipe.
If the pipe io handle is dynamic, it is deleted.
pointer | to pipe of child process to cancel. |
static int ucommon::shell::condition | ( | bool | test, |
int | exitcode | ||
) | [inline, static] |
static unsigned ucommon::shell::count | ( | char ** | argv | ) | [static] |
Get argc count for an existing array.
argv | to count items in. |
static void ucommon::shell::debug | ( | unsigned | level, |
char * | format, | ||
... | |||
) | [static] |
Print a debug message by debug level.
level | of debug message. |
format | string 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.
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. |
static void ucommon::shell::errexit | ( | int | exitcode, |
char * | format = ((void *) 0) , |
||
... | |||
) | [static] |
Print error message and exit.
Ignored if exitcode == 0.
exitcode | to return to parent process. |
format | string 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.
id | of error message to use. |
static void ucommon::shell::errmsg | ( | errmsg_t | id, |
char * | text | ||
) | [static] |
This is used to set internationalized error messages for the shell parser.
id | of message to set. |
text | for error message. |
static void ucommon::shell::error | ( | char * | format, |
... | |||
) | [static] |
Print error message and continue.
format | string 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.
argv | of first option. |
char* ucommon::shell::getargv0 | ( | char ** | argv | ) |
Parse and extract the argv0 filename alone.
argv | from main. |
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.
name | of symbol. |
value | of symbol if not found. |
char* ucommon::shell::getsym | ( | char * | name, |
char * | value = ((void *) 0) |
||
) |
Get a local symbol.
This uses getenv if no local symbol is found.
name | of symbol. |
value | of symbol if not found. |
bool ucommon::shell::issym | ( | char * | name | ) |
Test if symbol exists.
name | of symbol. |
static void ucommon::shell::log | ( | loglevel_t | level, |
char * | format, | ||
... | |||
) | [static] |
Print generic error message at specific error level.
level | of error condition. |
format | string 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.
name | of logging entity. |
level | of error conditions to log. |
mode | of logging. |
handler | for log messages. |
unsigned ucommon::shell::operator() | ( | void | ) | [inline] |
char* ucommon::shell::operator[] | ( | unsigned | offset | ) | [inline] |
char** ucommon::shell::parse | ( | char * | string | ) |
Parse a string as a series of arguments for use in exec calls.
string | to parse. |
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.
argc | from main. |
argv | from main. |
static char** ucommon::shell::parse | ( | shell & | args, |
char * | string | ||
) | [inline, static] |
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.
id | of path to return. |
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.
id | of prefix. |
directory | path to merge with prefix. |
static String ucommon::shell::path | ( | String & | prefix, |
char * | directory | ||
) | [static] |
Join a prefix with a path.
prefix | to merge with. |
directory | or file path to merge. |
static size_t ucommon::shell::printf | ( | char * | format, |
... | |||
) | [static] |
Print to standard output.
format | string to use. |
static size_t ucommon::shell::printf | ( | pipe_t | pipe, |
char * | format, | ||
... | |||
) | [static] |
Print to a pipe object.
pipe | to write to. |
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.
pri | level for process. |
static size_t ucommon::shell::readln | ( | pipe_t | pipe, |
char * | buffer, | ||
size_t | size | ||
) | [static] |
Read a line from a pipe object.
pipe | to read from. |
buffer | to save into. |
size | of buffer. |
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.
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.
exit_code | to send to parent process. |
static void ucommon::shell::relocate | ( | char * | argv0 | ) | [static] |
Set relative prefix.
Used for OS/X relocatable applications.
argv0 | path of executable. |
void ucommon::shell::restart | ( | char * | argv0, |
char ** | argv, | ||
char ** | list | ||
) |
Execute front-end like gdb based on stripped first argument.
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, |
char * | format, | ||
... | |||
) | [static] |
Print security error message at specific error level.
level | of error condition. |
format | string to use. |
void ucommon::shell::setsym | ( | char * | name, |
char * | value | ||
) |
Set a local symbol.
name | of symbol to set. |
value | of 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.
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. |
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.
path | to executable. |
argv | list of command arguments for the child process. |
mode | of pipe, rd only, wr only, or rdwr. |
size | of pipe buffer. |
env | of child process can be explicitly set. |
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.
command | string.. |
env | array to optionally use. |
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.
format | of/command string. |
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.
string | to translate. |
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().
singular | string to translate. |
plural | string to translate. |
count | of objects. |
static String ucommon::shell::userid | ( | void | ) | [static] |
Get the system login id.
static int ucommon::shell::wait | ( | shell::pid_t | pid | ) | [static] |
Wait for a child process to terminate.
This operation blocks.
pid | of process to wait for. |
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.
pointer | to pipe of child process to wait for. |