logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

popen.3p (7214B)


  1. '\" et
  2. .TH POPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. popen
  12. \(em initiate pipe streams to or from a process
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. FILE *popen(const char *\fIcommand\fP, const char *\fImode\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpopen\fR()
  23. function shall execute the command specified by the string
  24. .IR command .
  25. It shall create a pipe between the calling program and the executed
  26. command, and shall return a pointer to a stream that can be used to
  27. either read from or write to the pipe.
  28. .P
  29. The environment of the executed command shall be as if a child process
  30. were created within the
  31. \fIpopen\fR()
  32. call using the
  33. \fIfork\fR()
  34. function, and the child invoked the
  35. .IR sh
  36. utility using the call:
  37. .sp
  38. .RS 4
  39. .nf
  40. execl(\fIshell path\fP, "sh", "-c", \fIcommand\fP, (char *)0);
  41. .fi
  42. .P
  43. .RE
  44. .P
  45. where
  46. .IR "shell path"
  47. is an unspecified pathname for the
  48. .IR sh
  49. utility.
  50. .P
  51. The
  52. \fIpopen\fR()
  53. function shall ensure that any streams from previous
  54. \fIpopen\fR()
  55. calls that remain open in the parent process are closed in the new
  56. child process.
  57. .P
  58. The
  59. .IR mode
  60. argument to
  61. \fIpopen\fR()
  62. is a string that specifies I/O mode:
  63. .IP " 1." 4
  64. If
  65. .IR mode
  66. is
  67. .IR r ,
  68. when the child process is started, its file descriptor STDOUT_FILENO
  69. shall be the writable end of the pipe, and the file descriptor
  70. \fIfileno\fR(\fIstream\fR) in the calling process, where
  71. .IR stream
  72. is the stream pointer returned by
  73. \fIpopen\fR(),
  74. shall be the readable end of the pipe.
  75. .IP " 2." 4
  76. If
  77. .IR mode
  78. is
  79. .IR w ,
  80. when the child process is started its file descriptor STDIN_FILENO
  81. shall be the readable end of the pipe, and the file descriptor
  82. \fIfileno\fR(\fIstream\fR) in the calling process, where
  83. .IR stream
  84. is the stream pointer returned by
  85. \fIpopen\fR(),
  86. shall be the writable end of the pipe.
  87. .IP " 3." 4
  88. If
  89. .IR mode
  90. is any other value, the result is unspecified.
  91. .P
  92. After
  93. \fIpopen\fR(),
  94. both the parent and the child process shall be capable of executing
  95. independently before either terminates.
  96. .P
  97. Pipe streams are byte-oriented.
  98. .SH "RETURN VALUE"
  99. Upon successful completion,
  100. \fIpopen\fR()
  101. shall return a pointer to an open stream that can be used to read
  102. or write to the pipe. Otherwise, it shall return a null pointer and
  103. may set
  104. .IR errno
  105. to indicate the error.
  106. .SH ERRORS
  107. The
  108. \fIpopen\fR()
  109. function shall fail if:
  110. .TP
  111. .BR EMFILE
  112. {STREAM_MAX}
  113. streams are currently open in the calling process.
  114. .P
  115. The
  116. \fIpopen\fR()
  117. function may fail if:
  118. .TP
  119. .BR EMFILE
  120. {FOPEN_MAX}
  121. streams are currently open in the calling process.
  122. .TP
  123. .BR EINVAL
  124. The
  125. .IR mode
  126. argument is invalid.
  127. .P
  128. The
  129. \fIpopen\fR()
  130. function may also set
  131. .IR errno
  132. values as described by
  133. .IR "\fIfork\fR\^(\|)"
  134. or
  135. .IR "\fIpipe\fR\^(\|)".
  136. .LP
  137. .IR "The following sections are informative."
  138. .SH EXAMPLES
  139. .SS "Using popen(\|) to Obtain a List of Files from the ls Utility"
  140. .P
  141. The following example demonstrates the use of
  142. \fIpopen\fR()
  143. and
  144. \fIpclose\fR()
  145. to execute the command
  146. .IR ls *
  147. in order to obtain a list of files in the current directory:
  148. .sp
  149. .RS 4
  150. .nf
  151. #include <stdio.h>
  152. \&...
  153. .P
  154. FILE *fp;
  155. int status;
  156. char path[PATH_MAX];
  157. .P
  158. fp = popen("ls *", "r");
  159. if (fp == NULL)
  160. /* Handle error */;
  161. .P
  162. while (fgets(path, PATH_MAX, fp) != NULL)
  163. printf("%s", path);
  164. .P
  165. status = pclose(fp);
  166. if (status == -1) {
  167. /* Error reported by pclose() */
  168. ...
  169. } else {
  170. /* Use macros described under wait() to inspect `status\(aq in order
  171. to determine success/failure of command executed by popen() */
  172. ...
  173. }
  174. .fi
  175. .P
  176. .RE
  177. .SH "APPLICATION USAGE"
  178. Since open files are shared, a mode
  179. .IR r
  180. command can be used as an input filter and a mode
  181. .IR w
  182. command as an output filter.
  183. .P
  184. Buffered reading before opening an input filter may leave the standard
  185. input of that filter mispositioned. Similar problems with an output
  186. filter may be prevented by careful buffer flushing; for example, with
  187. .IR "\fIfflush\fR\^(\|)".
  188. .P
  189. A stream opened by
  190. \fIpopen\fR()
  191. should be closed by
  192. \fIpclose\fR().
  193. .P
  194. The behavior of
  195. \fIpopen\fR()
  196. is specified for values of
  197. .IR mode
  198. of
  199. .IR r
  200. and
  201. .IR w .
  202. Other modes such as
  203. .IR rb
  204. and
  205. .IR wb
  206. might be supported by specific implementations, but these would not be
  207. portable features. Note that historical implementations of
  208. \fIpopen\fR()
  209. only check to see if the first character of
  210. .IR mode
  211. is
  212. .IR r .
  213. Thus, a
  214. .IR mode
  215. of
  216. .IR "robert the robot"
  217. would be treated as
  218. .IR mode
  219. .IR r ,
  220. and a
  221. .IR mode
  222. of
  223. .IR "anything else"
  224. would be treated as
  225. .IR mode
  226. .IR w .
  227. .P
  228. If the application calls
  229. \fIwaitpid\fR()
  230. or
  231. \fIwaitid\fR()
  232. with a
  233. .IR pid
  234. argument greater than 0, and it still has a stream that was called with
  235. \fIpopen\fR()
  236. open, it must ensure that
  237. .IR pid
  238. does not refer to the process started by
  239. \fIpopen\fR().
  240. .P
  241. To determine whether or not the environment specified in the Shell and Utilities volume of POSIX.1\(hy2017 is
  242. present, use the function call:
  243. .sp
  244. .RS 4
  245. .nf
  246. sysconf(_SC_2_VERSION)
  247. .fi
  248. .P
  249. .RE
  250. .P
  251. (See
  252. .IR "\fIsysconf\fR\^(\|)").
  253. .SH RATIONALE
  254. The
  255. \fIpopen\fR()
  256. function should not be used by programs that have set user (or group)
  257. ID privileges. The
  258. \fIfork\fR()
  259. and
  260. .IR exec
  261. family of functions (except
  262. \fIexeclp\fR()
  263. and
  264. \fIexecvp\fR()),
  265. should be used instead. This prevents any unforeseen manipulation of
  266. the environment of the user that could cause execution of commands not
  267. anticipated by the calling program.
  268. .P
  269. If the original and
  270. \fIpopen\fR()ed
  271. processes both intend to read or write or read and write a common file,
  272. and either will be using FILE-type C functions (\c
  273. \fIfread\fR(),
  274. \fIfwrite\fR(),
  275. and so on), the rules for sharing file handles must be observed (see
  276. .IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams").
  277. .SH "FUTURE DIRECTIONS"
  278. None.
  279. .SH "SEE ALSO"
  280. .IR "Section 2.5" ", " "Standard I/O Streams",
  281. .IR "\fIfork\fR\^(\|)",
  282. .IR "\fIpclose\fR\^(\|)",
  283. .IR "\fIpipe\fR\^(\|)",
  284. .IR "\fIsysconf\fR\^(\|)",
  285. .IR "\fIsystem\fR\^(\|)",
  286. .IR "\fIwait\fR\^(\|)",
  287. .IR "\fIwaitid\fR\^(\|)"
  288. .P
  289. The Base Definitions volume of POSIX.1\(hy2017,
  290. .IR "\fB<stdio.h>\fP"
  291. .P
  292. The Shell and Utilities volume of POSIX.1\(hy2017,
  293. .IR "\fIsh\fR\^"
  294. .\"
  295. .SH COPYRIGHT
  296. Portions of this text are reprinted and reproduced in electronic form
  297. from IEEE Std 1003.1-2017, Standard for Information Technology
  298. -- Portable Operating System Interface (POSIX), The Open Group Base
  299. Specifications Issue 7, 2018 Edition,
  300. Copyright (C) 2018 by the Institute of
  301. Electrical and Electronics Engineers, Inc and The Open Group.
  302. In the event of any discrepancy between this version and the original IEEE and
  303. The Open Group Standard, the original IEEE and The Open Group Standard
  304. is the referee document. The original Standard can be obtained online at
  305. http://www.opengroup.org/unix/online.html .
  306. .PP
  307. Any typographical or formatting errors that appear
  308. in this page are most likely
  309. to have been introduced during the conversion of the source files to
  310. man page format. To report such errors, see
  311. https://www.kernel.org/doc/man-pages/reporting_bugs.html .