pclose(3c) - osol9

1popen(3C)                Standard C Library Functions                popen(3C)
2
3
4

NAME

6       popen, pclose - initiate a pipe to or from a process
7

SYNOPSIS

9       #include <stdio.h>
10
11       FILE *popen(const char *command, const char *mode);
12
13
14       int pclose(FILE *stream);
15
16

DESCRIPTION

18       The popen() function creates a pipe between the calling program and the
19       command to be executed.  The arguments to popen() are pointers to null-
20       terminated  strings.   The command argument consists of a shell command
21       line.  The mode argument is an I/O mode, either r for reading or w  for
22       writing. The value returned is a stream pointer such that one can write
23       to the standard input of the command, if the I/O mode is w, by  writing
24       to  the  file stream (see Intro(3)); and one can read from the standard
25       output of the command, if the I/O mode is r, by reading from  the  file
26       stream.  Because open files are shared, a type r command may be used as
27       an input filter and a type w as an output filter. A trailing F  charac‐
28       ter can also be included in the mode argument as described in fopen(3C)
29       to enable extended FILE facility.
30
31
32       The environment of the executed command will be as if a  child  process
33       were  created within the popen() call using fork(2). If the application
34       is standard-conforming (see standards(5)), the child is created  as  if
35       invoked with the call:
36
37
38       execl("/usr/xpg4/bin/sh", "sh", "-c",command, (char *)0);
39
40
41       otherwise, the child is created as if invoked with the call:
42
43
44       execl("/usr/bin/sh", "sh", "-c",command, (char *)0);
45
46
47       The  pclose() function closes a stream opened by popen() by closing the
48       pipe. It waits for the associated process to terminate and returns  the
49       termination  status  of the process running the command language inter‐
50       preter. This is the value returned by  waitpid(3C).  See  wait.h(3HEAD)
51       for  more  information  on  termination  status. If, however, a call to
52       waitpid() with a pid argument equal to the process ID  of  the  command
53       line  interpreter  causes  the  termination status to be unavailable to
54       pclose(), then pclose() returns −1 with errno set to ECHILD  to  report
55       this condition.
56

RETURN VALUES

58       Upon successful completion, popen() returns a pointer to an open stream
59       that can be used to read or write to the pipe. Otherwise, it returns  a
60       null pointer and may set errno to indicate the error.
61
62
63       Upon  successful completion, pclose() returns the termination status of
64       the command language interpreter as returned by waitpid().   Otherwise,
65       it returns −1 and sets errno to indicate the error.
66

ERRORS

68       The pclose() function will fail if:
69
70       ECHILD    The  status  of  the  child process could not be obtained, as
71                 described in the DESCRIPTION.
72
73
74
75       The popen() function may fail if:
76
77       EMFILE    There are currently FOPEN_MAX or STREAM_MAX streams  open  in
78                 the calling process.
79
80
81       EINVAL    The mode argument is invalid.
82
83
84
85       The  popen() function may also set errno values as described by fork(2)
86       or pipe(2).
87

USAGE

89       If the original and popen() processes concurrently read or write a com‐
90       mon file, neither should use buffered I/O. Problems with an output fil‐
91       ter may be forestalled by careful buffer flushing,  for  example,  with
92       fflush()  (see  fclose(3C)). A security hole exists through the IFS and
93       PATH environment variables.  Full pathnames should  be  used  (or  PATH
94       reset) and IFS should be set to space and tab (" \t").
95
96
97       Even  if  the  process has established a signal handler for SIGCHLD, it
98       will be called when the command terminates.  Even if another thread  in
99       the  same  process  issues  a wait(3C) call, it will interfere with the
100       return value of pclose(). Even if  the  process's  signal  handler  for
101       SIGCHLD  has  been set to ignore the signal, there will be no effect on
102       pclose().
103

EXAMPLES

105       Example 1 popen() example
106
107
108       The following program will print on the standard output (see stdio(3C))
109       the names of files in the current directory with a .c suffix.
110
111
112         #include <stdio.h>
113         #include <stdlib.h>
114         main()
115         {
116                 char *cmd = "/usr/bin/ls *.c";
117                 char buf[BUFSIZ];
118                 FILE *ptr;
119
120                 if ((ptr = popen(cmd, "r")) != NULL) {
121                         while (fgets(buf, BUFSIZ, ptr) != NULL)
122                                 (void) printf("%s", buf);
123                         (void) pclose(ptr);
124                 }
125                 return 0;
126         }
127
128
129       Example 2 system() replacement
130
131
132       The  following function can be used in a multithreaded process in place
133       of the most common usage of the Unsafe system(3C) function:
134
135
136         int my_system(const char *cmd)
137         {
138                 FILE *p;
139
140                 if ((p = popen(cmd, "w")) == NULL)
141                         return (-1);
142                 return (pclose(p));
143         }
144
145

ATTRIBUTES

147       See attributes(5) for descriptions of the following attributes:
148
149
150
151
152       ┌─────────────────────────────┬─────────────────────────────┐
153       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
154       ├─────────────────────────────┼─────────────────────────────┤
155       │Interface Stability          │See below.                   │
156       ├─────────────────────────────┼─────────────────────────────┤
157       │MT-Level                     │Safe                         │
158       └─────────────────────────────┴─────────────────────────────┘
159
160
161       The F character in the mode argument of popen()  is  Evolving.  In  all
162       other  respects  this  function  is  Standard. The pclose() function is
163       Standard.
164