sys/src/cmd/python/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{subprocess} module provides more powerful facilities for
  16 spawning new processes and retrieving their results.  Using the
  17 \module{subprocess} module is preferable to using the \module{commands}
  18 module.
  19
  20 The \module{commands} module defines the following functions:
  21
  22
  23 \begin{funcdesc}{getstatusoutput}{cmd}
  24 Execute the string \var{cmd} in a shell with \function{os.popen()} and
  25 return a 2-tuple \code{(\var{status}, \var{output})}.  \var{cmd} is
  26 actually run as \code{\{ \var{cmd} ; \} 2>\&1}, so that the returned
  27 output will contain output or error messages. A trailing newline is
  28 stripped from the output. The exit status for the command can be
  29 interpreted according to the rules for the C function
  30 \cfunction{wait()}.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{getoutput}{cmd}
  34 Like \function{getstatusoutput()}, except the exit status is ignored
  35 and the return value is a string containing the command's output.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{getstatus}{file}
  39 Return the output of \samp{ls -ld \var{file}} as a string.  This
  40 function uses the \function{getoutput()} function, and properly
  41 escapes backslashes and dollar signs in the argument.
  42 \end{funcdesc}
  43
  44 Example:
  45
  46 \begin{verbatim}
  47 >>> import commands
  48 >>> commands.getstatusoutput('ls /bin/ls')
  49 (0, '/bin/ls')
  50 >>> commands.getstatusoutput('cat /bin/junk')
  51 (256, 'cat: /bin/junk: No such file or directory')
  52 >>> commands.getstatusoutput('/bin/junk')
  53 (256, 'sh: /bin/junk: not found')
  54 >>> commands.getoutput('ls /bin/ls')
  55 '/bin/ls'
  56 >>> commands.getstatus('/bin/ls')
  57 '-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
  58 \end{verbatim}
  59
  60 \begin{seealso}
  61   \seemodule{subprocess}{Module for spawning and managing subprocesses.}
  62 \end{seealso}