Doc/lib/libcommands.tex

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