Penguin
Recent Changes
Annotated edit history of pclose(3) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 POPEN
2 !!!POPEN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 ERRORS
8 CONFORMING TO
9 BUGS
10 HISTORY
11 SEE ALSO
12 ----
13 !!NAME
14
15
16 popen, pclose - process I/O
17 !!SYNOPSIS
18
19
20 __#include __
21
22
23 __FILE *popen(const char *__''command''__, const char
24 *__''type''__);__
25
26
27 __int pclose(FILE *__''stream''__);__
28 !!DESCRIPTION
29
30
31 The __popen()__ function opens a process by creating a
32 pipe, forking, and invoking the shell. Since a pipe is by
33 definition unidirectional, the ''type'' argument may
34 specify only reading or writing, not both; the resulting
35 stream is correspondingly read-only or
36 write-only.
37
38
39 The ''command'' argument is a pointer to a
40 null-terminated string containing a shell command line. This
41 command is passed to ''/bin/sh'' using the __-c__
42 flag; interpretation, if any, is performed by the shell. The
43 ''mode'' argument is a pointer to a null-terminated
44 string which must be either `r' for reading or `w' for
45 writing.
46
47
48 The return value from __popen()__ is a normal standard
49 I/O stream in all respects save that it must be closed with
50 __pclose()__ rather than __fclose()__. Writing to such
51 a stream writes to the standard input of the command; the
52 command's standard output is the same as that of the process
53 that called __popen()__, unless this is altered by the
54 command itself. Conversely, reading from a ``popened''
55 stream reads the command's standard output, and the
56 command's standard input is the same as that of the process
57 that called __popen__.
58
59
60 Note that output __popen__ streams are fully buffered by
61 default.
62
63
64 The __pclose__ function waits for the associated process
65 to terminate and returns the exit status of the command as
66 returned by __wait4__.
67 !!RETURN VALUE
68
69
70 The __popen__ function returns __NULL__ if the
71 fork(2) or pipe(2) calls fail, or if it cannot
72 allocate memory.
73
74
75 The __pclose__ function returns -1 if __wait4__
76 returns an error, or some other error is
77 detected.
78 !!ERRORS
79
80
81 The __popen__ function does not set ''errno'' if
82 memory allocation fails. If the underlying __fork()__ or
83 __pipe()__ fails, ''errno'' is set appropriately. If
84 the ''mode'' argument is invalid, and this condition is
85 detected, ''errno'' is set to __EINVAL__.
86
87
88 If __pclose()__ cannot obtain the child status,
89 ''errno'' is set to __ECHILD__.
90 !!CONFORMING TO
91
92
93 POSIX.2
94 !!BUGS
95
96
97 Since the standard input of a command opened for reading
98 shares its seek offset with the process that called
99 __popen()__, if the original process has done a buffered
100 read, the command's input position may not be as expected.
101 Similarly, the output from a command opened for writing may
102 become intermingled with that of the original process. The
103 latter can be avoided by calling fflush(3) before
104 __popen__.
105
106
107 Failure to execute the shell is indistinguishable from the
108 shell's failure to execute command, or an immediate exit of
109 the command. The only hint is an exit status of
110 127.
111 !!HISTORY
112
113
114 A __popen()__ and a __pclose()__ function appeared in
115 Version 7 AT__
116 !!SEE ALSO
117
118
119 fork(2), sh(1), pipe(2),
2 perry 120 wait4(2), fflush(3), fclose(3),
1 perry 121 fopen(3), stdio(3),
122 system(3)
123 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.