libcommands.tex 1.78 KB
Newer Older
Fred Drake's avatar
Fred Drake committed
1
\section{\module{commands} ---
Fred Drake's avatar
Fred Drake committed
2
         Utilities for running commands}
3

4
\declaremodule{standard}{commands}
5 6
  \platform{Unix}
\modulesynopsis{Utility functions for running external commands.}
Fred Drake's avatar
Fred Drake committed
7
\sectionauthor{Sue Williams}{sbw@provis.com}
8

9

Fred Drake's avatar
Fred Drake committed
10 11 12 13
The \module{commands} module contains wrapper functions for
\function{os.popen()} which take a system command as a string and
return any output generated by the command and, optionally, the exit
status.
14

15
The \module{commands} module defines the following functions:
16 17 18


\begin{funcdesc}{getstatusoutput}{cmd}
Fred Drake's avatar
Fred Drake committed
19 20 21 22 23
Execute the string \var{cmd} in a shell with \function{os.popen()} and
return a 2-tuple \code{(\var{status}, \var{output})}.  \var{cmd} is
actually run as \code{\{ \var{cmd} ; \} 2>\&1}, so that the returned
output will contain output or error messages. A trailing newline is
stripped from the output. The exit status for the command can be
24
interpreted according to the rules for the C function
Fred Drake's avatar
Fred Drake committed
25
\cfunction{wait()}.
26 27 28
\end{funcdesc}

\begin{funcdesc}{getoutput}{cmd}
Fred Drake's avatar
Fred Drake committed
29 30
Like \function{getstatusoutput()}, except the exit status is ignored
and the return value is a string containing the command's output.  
31 32 33 34
\end{funcdesc}

\begin{funcdesc}{getstatus}{file}
Return the output of \samp{ls -ld \var{file}} as a string.  This
Fred Drake's avatar
Fred Drake committed
35 36
function uses the \function{getoutput()} function, and properly
escapes backslashes and dollar signs in the argument.
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
\end{funcdesc}

Example:

\begin{verbatim}
>>> import commands
>>> commands.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> commands.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> commands.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
>>> commands.getoutput('ls /bin/ls')
'/bin/ls'
>>> commands.getstatus('/bin/ls')
'-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
\end{verbatim}