## SHELL | Welcome Gallery Handbook |
| Manual page for SHELL(PL)

## `#shell` option`` command`[#endshell]
`

## DESCRIPTION

Execute the given shell command, and optionally display or capture the results.`` An option may be given; available options (described below) are `#dump` (the default), `#processrows`, `#dumptab`, `#dumphtml`, and `#dumpsilent`.``

command may use a single line construct or a multi-line construct formatted as in example 3 below. `#endshell` must be used to terminate a multi-line construct.``

The command's exit status is available in the @_STATUS script variable; 0 generally indicates success.``

Using #shell in ploticus scripts

## EXAMPLES

Example 1: `#shell date`

Example 2:

        #shell rm /tmp/myfile*
        #if @_STATUS != 0
          Command failed.
        #endif

Example 3:

        #shell
         cat /etc/vstab |
         grep "^afx"
       #endshell

## OPTIONS

An option may be given to specify how command results should be displayed or captured. If no option is given, `#dump` is done by default.`` The options all begin with a pound sign (#) so as not to be confused with command content.``

#dump

  Display all results immediately without any processing.`` Example:

       #shell #dump ls -l

#dumptab

  Display all results immediately in tab-delimited field format.`` Fields will be parsed in each result line, then the fields will be displayed separated by tabs.`` Use the $shellfielddelim() function to control shell result field parsing.`` Example:

       #shell #dumptab
          cat mydata | grep "^Jan"
       #endshell

#dumphtml

  Display all results immediately in HTML table row format.`` Fields will be parsed in each result line, then the fields will be displayed separated by tabs.`` Use the $shellfielddelim() function function to control shell result field parsing.``

#dumpsilent

  all rows of results will be retrieved then discarded. Used to get a count of the number of rows.`` Example:

       #shell #dumpsilent cat mydata | grep "^Jan"
       #set N = $shellrowcount()

#processrows

  Indicates that results will be retrieved and processed later one line at a time using the `$shellrow()` function . When processing rows, retrieved fields are available as script variables.`` Example:

             #shell #processrows cat mydata | grep "^Jan"
             #if @_STATUS != 0
               Command error @_STATUS.
               #exit
             #endif

             // get the result rows..
             #while $shellrow( A, B, C) = 0

               // now access the fields as variables..

               #if @B = 1
       	    ...etc..

             #endloop

## SHELL-RELATED FUNCTIONS

The following functions are related to the execution of shell commands.``

$shellrow( args )

  Read one line of shell command results, and perhaps parse into fields.`` Returns 0 on success, 1 if no more result lines, or an error code > 1.`` args may be passed in one of several forms.`` If args is a comma-delimited list of variable names, these variables will be set to values of parsed fields. If args is `#varvaluepair` the first parsed field will be taken as a variable name and the second field as the value (any trailing colon (:) will be removed from the variable name).`` No args should be supplied if the command generates a field name header.``

  Example 1: `#set STAT = $shellrow( name, address, phone )`

  Example 2: `#set STAT = $shellrow( #varvaluepair )`

  Code example (assume that the given shell command produces three whitespace delimited fields (date, action, description):

       	#call $shellfielddelim( whitespace )
       	#shell cat mydata | grep "^Jan"
       	#loop
       	  #set STAT = $shellrow( DATE, ACTION, DESC )
       	  #if @STAT != 0
                   #break
               #endif
               ...

$shellrowcount()

  Return the number of rows resulting from the most recent #shell command, that were processed.``

  Example: `#set N = $shellrowcount()`

$shellreadheader()

  For shell commands that generate a field name header, this function loads the header. It should be called before $shellrow().

  Example:

       	#call $shellfielddelim( tab )
       	#shell mycommand
       	#call $shellreadheader
       	#loop
       	  #set STAT = $shellrow()
       	  #if @STAT != 0
                   #break
               #endif
               ...
             #endloop

$shellfielddelim( s )

  Set the delimitation method for parsing shell command result fields.`` Allowable values for s are `tab`, `whitespace`, or `line` (which takes the entire line, sans newline, as a field). Default is `line`.``

  Example: `#call shellfielddelim( whitespace )`

$shellstripchars( chars, varname1, .. varnameN )

  Remove shell metacharacters (etc.) from user-supplied variables that are to be used to build a shell command to stop hackers from entering character combinations that would let them invoke their own shell commands. See the discussion of cgi shell security concerns for more information.`` chars is a set of characters to be removed.`` chars may be omitted; in this case a basic set of exploitable characters (`", ', `, $, \, and ;` ) will be removed from variables (see example 1).`` varnames are the names of variable(s) from which the dangerous characters will be removed.``

  Example 1: `#call $shellstripchars( NAME, ADDRESS )`

  Example 2: `#call $shellstripchars( "\"'`\$*();|^", NAME, ADDRESS, PHONE )`

## SECURITY CONCERNS

[Note: the following information is offered only a guide; developers are completely responsible for fully examining and understanding the security of their own systems.]

A security risk exists when user-supplied values are used to build shell commands.`` Devious users can enter input that, unless precautions are taken, can cause the shell to execute other commands. For example, suppose a program takes a user search string and uses it to build a grep command:

        #cgivar SEARCH
        #shell grep "@SEARCH" /data/*

A devious user could enter something like this: `foo" /etc/passwd; rm *; echo "hi` and remove all files in the program's current directory.``

This security hole is especially relevant to CGI programs, which are often accessible by the world, and may run in priveledged mode.``

To limit this security hole: 1) remove characters that could be exploited (I would start with these:`" ' ` $ \ ;` ) from variables that will be used to build shell commands (the function $shellstripchars() is available for doing this); 2) enclose all user-supplied variables in double quotes in the shell command
data display engine
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` September 17, 2001.