Doc/lib/libcommands.tex

   1 % Documentation written by Sue Williams.
   2
   3 \section{Standard Module \module{commands}}
   4 \stmodindex{commands}
   5 \label{module-commands}
   6
   7 The \module{commands} module contains wrapper functions for
   8 \function{os.popen()} which take a system command as a string and
   9 return any output generated by the command and, optionally, the exit
  10 status.
  11
  12 The \module{commands} module is only usable on systems which support
  13 \function{os.popen()} (currently \UNIX{}).  It defines the following
  14 functions:
  15
  16
  17 \begin{funcdesc}{getstatusoutput}{cmd}
  18 Execute the string \var{cmd} in a shell with \function{os.popen()} and
  19 return a 2-tuple \code{(\var{status}, \var{output})}.  \var{cmd} is
  20 actually run as \code{\{ \var{cmd} ; \} 2>\&1}, so that the returned
  21 output will contain output or error messages. A trailing newline is
  22 stripped from the output. The exit status for the command can be
  23 interpreted according to the rules for the \C{} function
  24 \cfunction{wait()}.
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{getoutput}{cmd}
  28 Like \function{getstatusoutput()}, except the exit status is ignored
  29 and the return value is a string containing the command's output.
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{getstatus}{file}
  33 Return the output of \samp{ls -ld \var{file}} as a string.  This
  34 function uses the \function{getoutput()} function, and properly
  35 escapes backslashes and dollar signs in the argument.
  36 \end{funcdesc}
  37
  38 Example:
  39
  40 \begin{verbatim}
  41 >>> import commands
  42 >>> commands.getstatusoutput('ls /bin/ls')
  43 (0, '/bin/ls')
  44 >>> commands.getstatusoutput('cat /bin/junk')
  45 (256, 'cat: /bin/junk: No such file or directory')
  46 >>> commands.getstatusoutput('/bin/junk')
  47 (256, 'sh: /bin/junk: not found')
  48 >>> commands.getoutput('ls /bin/ls')
  49 '/bin/ls'
  50 >>> commands.getstatus('/bin/ls')
  51 '-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
  52 \end{verbatim}