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.