Data Structures | Public Types | Public Member Functions | Static Public Member Functions

ucc::shell Class Reference

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

#include <shell.h>

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

Data Structures

class  charopt
 Character option for shell parsing. More...
class  errormap
 A class to redefine error messages. More...
class  flagopt
 Flag option for shell parsing. 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
}
 

Error table index.


typedef iobuf io_t
 Buffered i/o type for pipes and stdio.
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 = IOBuffer::BUF_RD, WR = IOBuffer::BUF_WR, RDWR = IOBuffer::BUF_RDWR }
 

Pipe I/O mode.


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).
int detach (const char *path, char **argv, char **env=NULL, fd_t *stdio=NULL)
 Create a detached process.
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.
unsigned operator() (void)
 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.
 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.
 shell (size_t pagesize=0)
 Construct an empty shell parser argument list.

Static Public Member Functions

static int cancel (shell::pid_t pid)
 Cancel a child process.
static int cancel (shell::pipe_t pointer)
 Cancel a child pipe.
static unsigned count (char **argv)
 Get argc count for an existing array.
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 help (void)
 Display shell options.
static fd_t input (void)
static fd_t output (void)
static char ** parse (shell &args, const char *string)
 Parse shell arguments directly into a shell object.
static size_t printf (const char *format,...)
 Print to standard output.
static size_t printf (pipe_t pipe, const char *format,...)
 Print to a pipe object.
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 shell::pid_t spawn (const char *path, char **argv, char **env=NULL, fd_t *stdio=NULL)
 Spawn a child process.
static shell::pipe_t spawn (const char *path, char **argv, pmode_t mode, size_t size=512, char **env=NULL)
 Spawn a child pipe.
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 int wait (shell::pipe_t pointer)
 Wait for a child pipe to terminate.
static int wait (shell::pid_t pid)
 Wait for a child process to terminate.
static size_t write (pipe_t pipe, String &string)
static size_t write (String &string)
static size_t writes (const char *string)
static size_t writes (pipe_t pipe, 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 58 of file shell.h.


Constructor & Destructor Documentation

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

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

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

Parameters:
string to parse.
pagesize for local heap.
ucc::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.
ucc::shell::shell ( size_t  pagesize = 0  ) 

Construct an empty shell parser argument list.

Parameters:
pagesize for local heap.

Member Function Documentation

unsigned ucc::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 602 of file shell.h.

char** ucc::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 611 of file shell.h.

static int ucc::shell::cancel ( shell::pipe_t  pointer  )  [static]

Cancel a child pipe.

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

Parameters:
pointer to pipe of child process to cancel.
Returns:
exit code of process, -1 if fails or pid is invalid.
static int ucc::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 unsigned ucc::shell::count ( char **  argv  )  [static]

Get argc count for an existing array.

Parameters:
argv to count items in.
Returns:
argc count of array.
int ucc::shell::detach ( const char *  path,
char **  argv,
char **  env = NULL,
fd_t *  stdio = NULL 
)

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 explicity set.
stdio handles for stdin, stdout, and stderr.
Returns:
0 if success, -1 on error.
static void ucc::shell::errexit ( int  exitcode,
const char *  format = NULL,
  ... 
) [static]

Print error message and exit.

Parameters:
exitcode to return to parent process.
format string to use.
static void ucc::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* ucc::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.
char** ucc::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* ucc::shell::getargv0 ( char **  argv  ) 

Parse and extract the argv0 filename alone.

Parameters:
argv from main.
Returns:
argv0 simple path name.
const char* ucc::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:
name of symbol.
value of symbol if not found.
Returns:
value of symbol.
unsigned ucc::shell::operator() ( void   )  [inline]

Return argc count.

Returns:
argc count.

Definition at line 692 of file shell.h.

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

Return parser argv element.

Parameters:
offset into array.
Returns:
argument string.

Definition at line 619 of file shell.h.

static char** ucc::shell::parse ( shell args,
const char *  string 
) [inline, static]

Parse shell arguments directly into a shell object.

Parameters:
args table.
string to parse.
Returns:
argument array.

Definition at line 542 of file shell.h.

char** ucc::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.
void ucc::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.
static size_t ucc::shell::printf ( const char *  format,
  ... 
) [static]

Print to standard output.

Parameters:
format string to use.
static size_t ucc::shell::printf ( pipe_t  pipe,
const char *  format,
  ... 
) [static]

Print to a pipe object.

Parameters:
pipe to write to.
format string to use.
Returns:
number of bytes written.
static size_t ucc::shell::readln ( pipe_t  pipe,
char *  buffer,
size_t  size 
) [static]

Read a line from a pipe object.

Parameters:
pipe to read from.
buffer to save into.
size of buffer.
Returns:
number of bytes read.
static shell::pipe_t ucc::shell::spawn ( const char *  path,
char **  argv,
pmode_t  mode,
size_t  size = 512,
char **  env = NULL 
) [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:
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.
Returns:
pipe object or NULL on failure.
static shell::pid_t ucc::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 ucc::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 ucc::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 int ucc::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:
pointer to pipe of child process to wait for.
Returns:
exit code of process, -1 if fails or pid is invalid.
static int ucc::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: