doc popen

[Kevin Ryde]

Bit of a revision of the popen module docs.  The description of
current ports inherited is new.  The WAIT_ANY in the open-input-pipe
example was not good, it makes close-pipe bomb (if that function is
used).




6.2.10 Pipes
------------

The following procedures are similar to the `popen' and `pclose' system
routines.  The code is in a separate "popen" module:

     (use-modules (ice-9 popen))

 -- Scheme Procedure: open-pipe command modes
     Execute the shell COMMAND (a string) in a subprocess.  A pipe to
     the process is created and returned.  MODES specifies whether an
     input or output pipe to the process is created: it should be one of
     the two following values.

      -- Variable: OPEN_READ
      -- Variable: OPEN_WRITE

     For an input pipe, in the child the standard output is the pipe and
     standard input is inherited from Guile's `current-input-port'.
     For an output pipe, in the child the standard input is the pipe and
     standard output is inherited from Guile's `current-output-port'.
     In both cases the standard error in the child is inherited from
     `current-error-port' (*note Default Ports::).

     If those `current-X-ports' are not files of some kind, and hence
     don't have file descriptors for the child, then `/dev/null' is
     used instead.

 -- Scheme Procedure: open-input-pipe command
     Equivalent to `open-pipe' with mode `OPEN_READ'.

          (let* ((port (open-input-pipe "date"))
                 (str  (read-line port)))
            (close-pipe port)
            str)
          => "Mon Mar 11 20:10:44 GMT 2002"

 -- Scheme Procedure: open-output-pipe command
     Equivalent to `open-pipe' with mode `OPEN_WRITE'.

          (let ((port (open-output-pipe "lpr")))
            (display "Something for the line printer.\n" port)
            (if (not (eqv? 0 (status:exit-val (close-pipe port))))
                (error "Cannot print")))

 -- Scheme Procedure: close-pipe port
     Close a pipe created by `open-pipe', wait for the process to
     terminate, and return the wait status code.  The status is as per
     `waitpid' and can be decoded with `status:exit-val' etc (*note
     Processes::)


   `waitpid WAIT_ANY' should not be used when pipes are open, since it
can reap a pipe's child process, causing an error from a subsequent
`close-pipe'.

   `close-port' (*note Closing::) can close a pipe, but it doesn't do
anything with the child process.

   The garbage collector will close a pipe no longer in use, and reap
the child process with `waitpid'.  If the child hasn't yet terminated
the garbage collector doesn't block, but instead checks again in the
next GC.

   Many systems have per-user and system-wide limits on the number of
processes, and a system-wide limit on the number of pipes, so it's
worth closing a pipe explicitly once it's longer needed, rather than
letting the garbage collector pick it up at some later time.