Manual Pages for UNIX Operating System command usage for man pclose

Standard C Library Functions                            popen(3C)



NAME
     popen, pclose - initiate a pipe to or from a process

SYNOPSIS
     #include 

     FILE *popen(const char *command, const char *mode);


     int pclose(FILE *stream);


DESCRIPTION
     The popen() function creates a pipe between the calling pro-
     gram  and  the  command  to  be  executed.  The arguments to
     popen() are pointers to null-terminated strings.   The  com-
     mand  argument  consists  of a shell command line.  The mode
     argument is an I/O mode, either r for reading or w for writ-
     ing.  The  value  returned is a stream pointer such that one
     can write to the standard input of the command, if  the  I/O
     mode is w, by writing to the file stream (see Intro(3)); and
     one can read from the standard output of the command, if the
     I/O mode is r, by reading from the file stream. Because open
     files are shared, a type r command may be used as  an  input
     filter  and a type w as an output filter. A trailing F char-
     acter can also be included in the mode argument as described
     in fopen(3C) to enable extended FILE facility.


     The environment of the executed command  will  be  as  if  a
     child  process  were  created  within the popen() call using
     fork(2). If  the  application  is  standard-conforming  (see
     standards(5)),  the  child is created as if invoked with the
     call:


     execl("/usr/xpg4/bin/sh", "sh", "-c",command, (char *)0);


     otherwise, the child is created as if invoked with the call:


     execl("/usr/bin/sh", "sh", "-c",command, (char *)0);


     The pclose() function closes a stream opened by  popen()  by
     closing  the  pipe.  It  waits for the associated process to
     terminate and returns the termination status of the  process
     running  the command language interpreter. This is the value
     returned by waitpid(3C). See wait.h(3HEAD) for more informa-
     tion on termination status. If, however, a call to waitpid()
     with a pid argument equal to the process ID of  the  command



SunOS 5.11          Last change: 14 Dec 2006                    1






Standard C Library Functions                            popen(3C)



     line  interpreter  causes  the termination status to be una-
     vailable to pclose(), then pclose() returns  -1  with  errno
     set to ECHILD to report this condition.

RETURN VALUES
     Upon successful completion, popen() returns a pointer to  an
     open  stream  that can be used to read or write to the pipe.
     Otherwise, it returns a null pointer and may  set  errno  to
     indicate the error.


     Upon successful completion, pclose() returns the termination
     status  of  the  command language interpreter as returned by
     waitpid().  Otherwise, it returns -1 and sets errno to indi-
     cate the error.

ERRORS
     The pclose() function will fail if:

     ECHILD    The status of  the  child  process  could  not  be
               obtained, as described in the DESCRIPTION.



     The popen() function may fail if:

     EMFILE    There  are  currently  FOPEN_MAX   or   STREAM_MAX
               streams open in the calling process.


     EINVAL    The mode argument is invalid.



     The popen() function may also set errno values as  described
     by fork(2) or pipe(2).

USAGE
     If the original and popen() processes concurrently  read  or
     write  a common file, neither should use buffered I/O. Prob-
     lems with an output filter may  be  forestalled  by  careful
     buffer   flushing,   for   example,   with   fflush()   (see
     fclose(3C)). A security hole exists through the IFS and PATH
     environment  variables.   Full  pathnames should be used (or
     PATH reset) and IFS should be set to space and tab (" \t").


     Even if the process has established  a  signal  handler  for
     SIGCHLD,  it  will  be  called  when the command terminates.
     Even if another thread in the same process issues a wait(3C)
     call,  it  will interfere with the return value of pclose().
     Even if the process's signal handler for  SIGCHLD  has  been



SunOS 5.11          Last change: 14 Dec 2006                    2






Standard C Library Functions                            popen(3C)



     set  to  ignore  the  signal,  there  will  be  no effect on
     pclose().

EXAMPLES
     Example 1 popen() example


     The following program will print on the standard output (see
     stdio(3C))  the names of files in the current directory with
     a .c suffix.


       #include 
       #include 
       main()
       {
               char *cmd = "/usr/bin/ls *.c";
               char buf[BUFSIZ];
               FILE *ptr;

               if ((ptr = popen(cmd, "r")) != NULL) {
                       while (fgets(buf, BUFSIZ, ptr) != NULL)
                               (void) printf("%s", buf);
                       (void) pclose(ptr);
               }
               return 0;
       }


     Example 2 system() replacement


     The following function can be used in a  multithreaded  pro-
     cess  in  place  of  the  most  common  usage  of the Unsafe
     system(3C) function:


       int my_system(const char *cmd)
       {
               FILE *p;

               if ((p = popen(cmd, "w")) == NULL)
                       return (-1);
               return (pclose(p));
       }


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:





SunOS 5.11          Last change: 14 Dec 2006                    3






Standard C Library Functions                            popen(3C)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|
    | Standard                    | See below.                  |
    |_____________________________|_____________________________|



     For pclose() and all aspects of popen() except the F charac-
     ter in the mode argument, see standards(5).

SEE ALSO
     ksh(1),  pipe(2),  fclose(3C),  fopen(3C),  posix_spawn(3C),
     stdio(3C), system(3C), wait(3C), waitpid(3C), wait.h(3HEAD),
     attributes(5), standards(5)




































SunOS 5.11          Last change: 14 Dec 2006                    4