/share/doc/psd/04.uprog/p5

https://bitbucket.org/freebsd/freebsd-head/ · #! · 577 lines · 570 code · 7 blank · 0 comment · 0 complexity · 229c1d86de66d6783b7fbfa72cd2ecf0 MD5 · raw file

  1. .\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
  2. .\"
  3. .\" Redistribution and use in source and binary forms, with or without
  4. .\" modification, are permitted provided that the following conditions are
  5. .\" met:
  6. .\"
  7. .\" Redistributions of source code and documentation must retain the above
  8. .\" copyright notice, this list of conditions and the following
  9. .\" disclaimer.
  10. .\"
  11. .\" Redistributions in binary form must reproduce the above copyright
  12. .\" notice, this list of conditions and the following disclaimer in the
  13. .\" documentation and/or other materials provided with the distribution.
  14. .\"
  15. .\" All advertising materials mentioning features or use of this software
  16. .\" must display the following acknowledgement:
  17. .\"
  18. .\" This product includes software developed or owned by Caldera
  19. .\" International, Inc. Neither the name of Caldera International, Inc.
  20. .\" nor the names of other contributors may be used to endorse or promote
  21. .\" products derived from this software without specific prior written
  22. .\" permission.
  23. .\"
  24. .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
  25. .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
  26. .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  27. .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  28. .\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
  29. .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
  30. .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  31. .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  32. .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  33. .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  34. .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  35. .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36. .\"
  37. .\" $FreeBSD$
  38. .\"
  39. .\" @(#)p5 8.1 (Berkeley) 6/8/93
  40. .\"
  41. .NH
  42. PROCESSES
  43. .PP
  44. It is often easier to use a program written
  45. by someone else than to invent one's own.
  46. This section describes how to
  47. execute a program from within another.
  48. .NH 2
  49. The ``System'' Function
  50. .PP
  51. The easiest way to execute a program from another
  52. is to use
  53. the standard library routine
  54. .UL system .
  55. .UL system
  56. takes one argument, a command string exactly as typed
  57. at the terminal
  58. (except for the newline at the end)
  59. and executes it.
  60. For instance, to time-stamp the output of a program,
  61. .P1
  62. main()
  63. {
  64. system("date");
  65. /* rest of processing */
  66. }
  67. .P2
  68. If the command string has to be built from pieces,
  69. the in-memory formatting capabilities of
  70. .UL sprintf
  71. may be useful.
  72. .PP
  73. Remember than
  74. .UL getc
  75. and
  76. .UL putc
  77. normally buffer their input;
  78. terminal I/O will not be properly synchronized unless
  79. this buffering is defeated.
  80. For output, use
  81. .UL fflush ;
  82. for input, see
  83. .UL setbuf
  84. in the appendix.
  85. .NH 2
  86. Low-Level Process Creation \(em Execl and Execv
  87. .PP
  88. If you're not using the standard library,
  89. or if you need finer control over what
  90. happens,
  91. you will have to construct calls to other programs
  92. using the more primitive routines that the standard
  93. library's
  94. .UL system
  95. routine is based on.
  96. .PP
  97. The most basic operation is to execute another program
  98. .ul
  99. without
  100. .IT returning ,
  101. by using the routine
  102. .UL execl .
  103. To print the date as the last action of a running program,
  104. use
  105. .P1
  106. execl("/bin/date", "date", NULL);
  107. .P2
  108. The first argument to
  109. .UL execl
  110. is the
  111. .ul
  112. file name
  113. of the command; you have to know where it is found
  114. in the file system.
  115. The second argument is conventionally
  116. the program name
  117. (that is, the last component of the file name),
  118. but this is seldom used except as a place-holder.
  119. If the command takes arguments, they are strung out after
  120. this;
  121. the end of the list is marked by a
  122. .UL NULL
  123. argument.
  124. .PP
  125. The
  126. .UL execl
  127. call
  128. overlays the existing program with
  129. the new one,
  130. runs that, then exits.
  131. There is
  132. .ul
  133. no
  134. return to the original program.
  135. .PP
  136. More realistically,
  137. a program might fall into two or more phases
  138. that communicate only through temporary files.
  139. Here it is natural to make the second pass
  140. simply an
  141. .UL execl
  142. call from the first.
  143. .PP
  144. The one exception to the rule that the original program never gets control
  145. back occurs when there is an error, for example if the file can't be found
  146. or is not executable.
  147. If you don't know where
  148. .UL date
  149. is located, say
  150. .P1
  151. execl("/bin/date", "date", NULL);
  152. execl("/usr/bin/date", "date", NULL);
  153. fprintf(stderr, "Someone stole 'date'\en");
  154. .P2
  155. .PP
  156. A variant of
  157. .UL execl
  158. called
  159. .UL execv
  160. is useful when you don't know in advance how many arguments there are going to be.
  161. The call is
  162. .P1
  163. execv(filename, argp);
  164. .P2
  165. where
  166. .UL argp
  167. is an array of pointers to the arguments;
  168. the last pointer in the array must be
  169. .UL NULL
  170. so
  171. .UL execv
  172. can tell where the list ends.
  173. As with
  174. .UL execl ,
  175. .UL filename
  176. is the file in which the program is found, and
  177. .UL argp[0]
  178. is the name of the program.
  179. (This arrangement is identical to the
  180. .UL argv
  181. array for program arguments.)
  182. .PP
  183. Neither of these routines provides the niceties of normal command execution.
  184. There is no automatic search of multiple directories \(em
  185. you have to know precisely where the command is located.
  186. Nor do you get the expansion of metacharacters like
  187. .UL < ,
  188. .UL > ,
  189. .UL * ,
  190. .UL ? ,
  191. and
  192. .UL []
  193. in the argument list.
  194. If you want these, use
  195. .UL execl
  196. to invoke the shell
  197. .UL sh ,
  198. which then does all the work.
  199. Construct a string
  200. .UL commandline
  201. that contains the complete command as it would have been typed
  202. at the terminal, then say
  203. .P1
  204. execl("/bin/sh", "sh", "-c", commandline, NULL);
  205. .P2
  206. The shell is assumed to be at a fixed place,
  207. .UL /bin/sh .
  208. Its argument
  209. .UL -c
  210. says to treat the next argument
  211. as a whole command line, so it does just what you want.
  212. The only problem is in constructing the right information
  213. in
  214. .UL commandline .
  215. .NH 2
  216. Control of Processes \(em Fork and Wait
  217. .PP
  218. So far what we've talked about isn't really all that useful by itself.
  219. Now we will show how to regain control after running
  220. a program with
  221. .UL execl
  222. or
  223. .UL execv .
  224. Since these routines simply overlay the new program on the old one,
  225. to save the old one requires that it first be split into
  226. two copies;
  227. one of these can be overlaid, while the other waits for the new,
  228. overlaying program to finish.
  229. The splitting is done by a routine called
  230. .UL fork :
  231. .P1
  232. proc_id = fork();
  233. .P2
  234. splits the program into two copies, both of which continue to run.
  235. The only difference between the two is the value of
  236. .UL proc_id ,
  237. the ``process id.''
  238. In one of these processes (the ``child''),
  239. .UL proc_id
  240. is zero.
  241. In the other
  242. (the ``parent''),
  243. .UL proc_id
  244. is non-zero; it is the process number of the child.
  245. Thus the basic way to call, and return from,
  246. another program is
  247. .P1
  248. if (fork() == 0)
  249. execl("/bin/sh", "sh", "-c", cmd, NULL); /* in child */
  250. .P2
  251. And in fact, except for handling errors, this is sufficient.
  252. The
  253. .UL fork
  254. makes two copies of the program.
  255. In the child, the value returned by
  256. .UL fork
  257. is zero, so it calls
  258. .UL execl
  259. which does the
  260. .UL command
  261. and then dies.
  262. In the parent,
  263. .UL fork
  264. returns non-zero
  265. so it skips the
  266. .UL execl.
  267. (If there is any error,
  268. .UL fork
  269. returns
  270. .UL -1 ).
  271. .PP
  272. More often, the parent wants to wait for the child to terminate
  273. before continuing itself.
  274. This can be done with
  275. the function
  276. .UL wait :
  277. .P1
  278. int status;
  279. if (fork() == 0)
  280. execl(...);
  281. wait(&status);
  282. .P2
  283. This still doesn't handle any abnormal conditions, such as a failure
  284. of the
  285. .UL execl
  286. or
  287. .UL fork ,
  288. or the possibility that there might be more than one child running simultaneously.
  289. (The
  290. .UL wait
  291. returns the
  292. process id
  293. of the terminated child, if you want to check it against the value
  294. returned by
  295. .UL fork .)
  296. Finally, this fragment doesn't deal with any
  297. funny behavior on the part of the child
  298. (which is reported in
  299. .UL status ).
  300. Still, these three lines
  301. are the heart of the standard library's
  302. .UL system
  303. routine,
  304. which we'll show in a moment.
  305. .PP
  306. The
  307. .UL status
  308. returned by
  309. .UL wait
  310. encodes in its low-order eight bits
  311. the system's idea of the child's termination status;
  312. it is 0 for normal termination and non-zero to indicate
  313. various kinds of problems.
  314. The next higher eight bits are taken from the argument
  315. of the call to
  316. .UL exit
  317. which caused a normal termination of the child process.
  318. It is good coding practice
  319. for all programs to return meaningful
  320. status.
  321. .PP
  322. When a program is called by the shell,
  323. the three file descriptors
  324. 0, 1, and 2 are set up pointing at the right files,
  325. and all other possible file descriptors
  326. are available for use.
  327. When this program calls another one,
  328. correct etiquette suggests making sure the same conditions
  329. hold.
  330. Neither
  331. .UL fork
  332. nor the
  333. .UL exec
  334. calls affects open files in any way.
  335. If the parent is buffering output
  336. that must come out before output from the child,
  337. the parent must flush its buffers
  338. before the
  339. .UL execl .
  340. Conversely,
  341. if a caller buffers an input stream,
  342. the called program will lose any information
  343. that has been read by the caller.
  344. .NH 2
  345. Pipes
  346. .PP
  347. A
  348. .ul
  349. pipe
  350. is an I/O channel intended for use
  351. between two cooperating processes:
  352. one process writes into the pipe,
  353. while the other reads.
  354. The system looks after buffering the data and synchronizing
  355. the two processes.
  356. Most pipes are created by the shell,
  357. as in
  358. .P1
  359. ls | pr
  360. .P2
  361. which connects the standard output of
  362. .UL ls
  363. to the standard input of
  364. .UL pr .
  365. Sometimes, however, it is most convenient
  366. for a process to set up its own plumbing;
  367. in this section, we will illustrate how
  368. the pipe connection is established and used.
  369. .PP
  370. The system call
  371. .UL pipe
  372. creates a pipe.
  373. Since a pipe is used for both reading and writing,
  374. two file descriptors are returned;
  375. the actual usage is like this:
  376. .P1
  377. int fd[2];
  378. stat = pipe(fd);
  379. if (stat == -1)
  380. /* there was an error ... */
  381. .P2
  382. .UL fd
  383. is an array of two file descriptors, where
  384. .UL fd[0]
  385. is the read side of the pipe and
  386. .UL fd[1]
  387. is for writing.
  388. These may be used in
  389. .UL read ,
  390. .UL write
  391. and
  392. .UL close
  393. calls just like any other file descriptors.
  394. .PP
  395. If a process reads a pipe which is empty,
  396. it will wait until data arrives;
  397. if a process writes into a pipe which
  398. is too full, it will wait until the pipe empties somewhat.
  399. If the write side of the pipe is closed,
  400. a subsequent
  401. .UL read
  402. will encounter end of file.
  403. .PP
  404. To illustrate the use of pipes in a realistic setting,
  405. let us write a function called
  406. .UL popen(cmd,\ mode) ,
  407. which creates a process
  408. .UL cmd
  409. (just as
  410. .UL system
  411. does),
  412. and returns a file descriptor that will either
  413. read or write that process, according to
  414. .UL mode .
  415. That is,
  416. the call
  417. .P1
  418. fout = popen("pr", WRITE);
  419. .P2
  420. creates a process that executes
  421. the
  422. .UL pr
  423. command;
  424. subsequent
  425. .UL write
  426. calls using the file descriptor
  427. .UL fout
  428. will send their data to that process
  429. through the pipe.
  430. .PP
  431. .UL popen
  432. first creates the
  433. the pipe with a
  434. .UL pipe
  435. system call;
  436. it then
  437. .UL fork s
  438. to create two copies of itself.
  439. The child decides whether it is supposed to read or write,
  440. closes the other side of the pipe,
  441. then calls the shell (via
  442. .UL execl )
  443. to run the desired process.
  444. The parent likewise closes the end of the pipe it does not use.
  445. These closes are necessary to make end-of-file tests work properly.
  446. For example, if a child that intends to read
  447. fails to close the write end of the pipe, it will never
  448. see the end of the pipe file, just because there is one writer
  449. potentially active.
  450. .P1
  451. #include <stdio.h>
  452. #define READ 0
  453. #define WRITE 1
  454. #define tst(a, b) (mode == READ ? (b) : (a))
  455. static int popen_pid;
  456. popen(cmd, mode)
  457. char *cmd;
  458. int mode;
  459. {
  460. int p[2];
  461. if (pipe(p) < 0)
  462. return(NULL);
  463. if ((popen_pid = fork()) == 0) {
  464. close(tst(p[WRITE], p[READ]));
  465. close(tst(0, 1));
  466. dup(tst(p[READ], p[WRITE]));
  467. close(tst(p[READ], p[WRITE]));
  468. execl("/bin/sh", "sh", "-c", cmd, 0);
  469. _exit(1); /* disaster has occurred if we get here */
  470. }
  471. if (popen_pid == -1)
  472. return(NULL);
  473. close(tst(p[READ], p[WRITE]));
  474. return(tst(p[WRITE], p[READ]));
  475. }
  476. .P2
  477. The sequence of
  478. .UL close s
  479. in the child
  480. is a bit tricky.
  481. Suppose
  482. that the task is to create a child process that will read data from the parent.
  483. Then the first
  484. .UL close
  485. closes the write side of the pipe,
  486. leaving the read side open.
  487. The lines
  488. .P1
  489. close(tst(0, 1));
  490. dup(tst(p[READ], p[WRITE]));
  491. .P2
  492. are the conventional way to associate the pipe descriptor
  493. with the standard input of the child.
  494. The
  495. .UL close
  496. closes file descriptor 0,
  497. that is, the standard input.
  498. .UL dup
  499. is a system call that
  500. returns a duplicate of an already open file descriptor.
  501. File descriptors are assigned in increasing order
  502. and the first available one is returned,
  503. so
  504. the effect of the
  505. .UL dup
  506. is to copy the file descriptor for the pipe (read side)
  507. to file descriptor 0;
  508. thus the read side of the pipe becomes the standard input.
  509. (Yes, this is a bit tricky, but it's a standard idiom.)
  510. Finally, the old read side of the pipe is closed.
  511. .PP
  512. A similar sequence of operations takes place
  513. when the child process is supposed to write
  514. from the parent instead of reading.
  515. You may find it a useful exercise to step through that case.
  516. .PP
  517. The job is not quite done,
  518. for we still need a function
  519. .UL pclose
  520. to close the pipe created by
  521. .UL popen .
  522. The main reason for using a separate function rather than
  523. .UL close
  524. is that it is desirable to wait for the termination of the child process.
  525. First, the return value from
  526. .UL pclose
  527. indicates whether the process succeeded.
  528. Equally important when a process creates several children
  529. is that only a bounded number of unwaited-for children
  530. can exist, even if some of them have terminated;
  531. performing the
  532. .UL wait
  533. lays the child to rest.
  534. Thus:
  535. .P1
  536. #include <signal.h>
  537. pclose(fd) /* close pipe fd */
  538. int fd;
  539. {
  540. register r, (*hstat)(), (*istat)(), (*qstat)();
  541. int status;
  542. extern int popen_pid;
  543. close(fd);
  544. istat = signal(SIGINT, SIG_IGN);
  545. qstat = signal(SIGQUIT, SIG_IGN);
  546. hstat = signal(SIGHUP, SIG_IGN);
  547. while ((r = wait(&status)) != popen_pid && r != -1);
  548. if (r == -1)
  549. status = -1;
  550. signal(SIGINT, istat);
  551. signal(SIGQUIT, qstat);
  552. signal(SIGHUP, hstat);
  553. return(status);
  554. }
  555. .P2
  556. The calls to
  557. .UL signal
  558. make sure that no interrupts, etc.,
  559. interfere with the waiting process;
  560. this is the topic of the next section.
  561. .PP
  562. The routine as written has the limitation that only one pipe may
  563. be open at once, because of the single shared variable
  564. .UL popen_pid ;
  565. it really should be an array indexed by file descriptor.
  566. A
  567. .UL popen
  568. function, with slightly different arguments and return value is available
  569. as part of the standard I/O library discussed below.
  570. As currently written, it shares the same limitation.