/share/doc/psd/04.uprog/p3

https://bitbucket.org/freebsd/freebsd-head/ · #! · 469 lines · 467 code · 2 blank · 0 comment · 0 complexity · 5617acf5ab47dfd1ee9a79bfe2f5665c 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. .\" @(#)p3 8.1 (Berkeley) 6/8/93
  40. .\"
  41. .NH
  42. THE STANDARD I/O LIBRARY
  43. .PP
  44. The ``Standard I/O Library''
  45. is a collection of routines
  46. intended to provide
  47. efficient
  48. and portable
  49. I/O services
  50. for most C programs.
  51. The standard I/O library is available on each system that supports C,
  52. so programs that confine
  53. their system interactions
  54. to its facilities
  55. can be transported from one system to another essentially without change.
  56. .PP
  57. In this section, we will discuss the basics of the standard I/O library.
  58. The appendix contains a more complete description of its capabilities.
  59. .NH 2
  60. File Access
  61. .PP
  62. The programs written so far have all
  63. read the standard input and written the standard output,
  64. which we have assumed are magically pre-defined.
  65. The next step
  66. is to write a program that accesses
  67. a file that is
  68. .ul
  69. not
  70. already connected to the program.
  71. One simple example is
  72. .IT wc ,
  73. which counts the lines, words and characters
  74. in a set of files.
  75. For instance, the command
  76. .P1
  77. wc x.c y.c
  78. .P2
  79. prints the number of lines, words and characters
  80. in
  81. .UL x.c
  82. and
  83. .UL y.c
  84. and the totals.
  85. .PP
  86. The question is how to arrange for the named files
  87. to be read \(em
  88. that is, how to connect the file system names
  89. to the I/O statements which actually read the data.
  90. .PP
  91. The rules are simple.
  92. Before it can be read or written
  93. a file has to be
  94. .ul
  95. opened
  96. by the standard library function
  97. .UL fopen .
  98. .UL fopen
  99. takes an external name
  100. (like
  101. .UL x.c
  102. or
  103. .UL y.c ),
  104. does some housekeeping and negotiation with the operating system,
  105. and returns an internal name
  106. which must be used in subsequent
  107. reads or writes of the file.
  108. .PP
  109. This internal name is actually a pointer,
  110. called a
  111. .IT file
  112. .IT pointer ,
  113. to a structure
  114. which contains information about the file,
  115. such as the location of a buffer,
  116. the current character position in the buffer,
  117. whether the file is being read or written,
  118. and the like.
  119. Users don't need to know the details,
  120. because part of the standard I/O definitions
  121. obtained by including
  122. .UL stdio.h
  123. is a structure definition called
  124. .UL FILE .
  125. The only declaration needed for a file pointer
  126. is exemplified by
  127. .P1
  128. FILE *fp, *fopen();
  129. .P2
  130. This says that
  131. .UL fp
  132. is a pointer to a
  133. .UL FILE ,
  134. and
  135. .UL fopen
  136. returns a pointer to
  137. a
  138. .UL FILE .
  139. .UL FILE \& (
  140. is a type name, like
  141. .UL int ,
  142. not a structure tag.
  143. .PP
  144. The actual call to
  145. .UL fopen
  146. in a program
  147. is
  148. .P1
  149. fp = fopen(name, mode);
  150. .P2
  151. The first argument of
  152. .UL fopen
  153. is the
  154. name
  155. of the file,
  156. as a character string.
  157. The second argument is the
  158. mode,
  159. also as a character string,
  160. which indicates how you intend to
  161. use the file.
  162. The only allowable modes are
  163. read
  164. .UL \&"r" ), (
  165. write
  166. .UL \&"w" ), (
  167. or append
  168. .UL \&"a" ). (
  169. .PP
  170. If a file that you open for writing or appending does not exist,
  171. it is created
  172. (if possible).
  173. Opening an existing file for writing causes the old contents
  174. to be discarded.
  175. Trying to read a file that does not exist
  176. is an error,
  177. and there may be other causes of error
  178. as well
  179. (like trying to read a file
  180. when you don't have permission).
  181. If there is any error,
  182. .UL fopen
  183. will return the null pointer
  184. value
  185. .UL NULL
  186. (which is defined as zero in
  187. .UL stdio.h ).
  188. .PP
  189. The next thing needed is a way to read or write the file
  190. once it is open.
  191. There are several possibilities,
  192. of which
  193. .UL getc
  194. and
  195. .UL putc
  196. are the simplest.
  197. .UL getc
  198. returns the next character from a file;
  199. it needs the file pointer to tell it what file.
  200. Thus
  201. .P1
  202. c = getc(fp)
  203. .P2
  204. places in
  205. .UL c
  206. the next character from the file referred to by
  207. .UL fp ;
  208. it returns
  209. .UL EOF
  210. when it reaches end of file.
  211. .UL putc
  212. is the inverse of
  213. .UL getc :
  214. .P1
  215. putc(c, fp)
  216. .P2
  217. puts the character
  218. .UL c
  219. on the file
  220. .UL fp
  221. and returns
  222. .UL c .
  223. .UL getc
  224. and
  225. .UL putc
  226. return
  227. .UL EOF
  228. on error.
  229. .PP
  230. When a program is started, three files are opened automatically,
  231. and file pointers are provided for them.
  232. These files are the standard input,
  233. the standard output,
  234. and the standard error output;
  235. the corresponding file pointers are
  236. called
  237. .UL stdin ,
  238. .UL stdout ,
  239. and
  240. .UL stderr .
  241. Normally these are all connected to the terminal,
  242. but
  243. may be redirected to files or pipes as described in
  244. Section 2.2.
  245. .UL stdin ,
  246. .UL stdout
  247. and
  248. .UL stderr
  249. are pre-defined in the I/O library
  250. as the standard input, output and error files;
  251. they may be used anywhere an object of type
  252. .UL FILE\ *
  253. can be.
  254. They are
  255. constants, however,
  256. .ul
  257. not
  258. variables,
  259. so don't try to assign to them.
  260. .PP
  261. With some of the preliminaries out of the way,
  262. we can now write
  263. .IT wc .
  264. The basic design
  265. is one that has been found
  266. convenient for many programs:
  267. if there are command-line arguments, they are processed in order.
  268. If there are no arguments, the standard input
  269. is processed.
  270. This way the program can be used stand-alone
  271. or as part of a larger process.
  272. .P1
  273. #include <stdio.h>
  274. main(argc, argv) /* wc: count lines, words, chars */
  275. int argc;
  276. char *argv[];
  277. {
  278. int c, i, inword;
  279. FILE *fp, *fopen();
  280. long linect, wordct, charct;
  281. long tlinect = 0, twordct = 0, tcharct = 0;
  282. i = 1;
  283. fp = stdin;
  284. do {
  285. if (argc > 1 && (fp=fopen(argv[i], "r")) == NULL) {
  286. fprintf(stderr, "wc: can't open %s\en", argv[i]);
  287. continue;
  288. }
  289. linect = wordct = charct = inword = 0;
  290. while ((c = getc(fp)) != EOF) {
  291. charct++;
  292. if (c == '\en')
  293. linect++;
  294. if (c == ' ' || c == '\et' || c == '\en')
  295. inword = 0;
  296. else if (inword == 0) {
  297. inword = 1;
  298. wordct++;
  299. }
  300. }
  301. printf("%7ld %7ld %7ld", linect, wordct, charct);
  302. printf(argc > 1 ? " %s\en" : "\en", argv[i]);
  303. fclose(fp);
  304. tlinect += linect;
  305. twordct += wordct;
  306. tcharct += charct;
  307. } while (++i < argc);
  308. if (argc > 2)
  309. printf("%7ld %7ld %7ld total\en", tlinect, twordct, tcharct);
  310. exit(0);
  311. }
  312. .P2
  313. The function
  314. .UL fprintf
  315. is identical to
  316. .UL printf ,
  317. save that the first argument is a file pointer
  318. that specifies the file to be
  319. written.
  320. .PP
  321. The function
  322. .UL fclose
  323. is the inverse of
  324. .UL fopen ;
  325. it breaks the connection between the file pointer and the external name
  326. that was established by
  327. .UL fopen ,
  328. freeing the
  329. file pointer for another file.
  330. Since there is a limit on the number
  331. of files
  332. that a program may have open simultaneously,
  333. it's a good idea to free things when they are no longer needed.
  334. There is also another reason to call
  335. .UL fclose
  336. on an output file
  337. \(em it flushes the buffer
  338. in which
  339. .UL putc
  340. is collecting output.
  341. .UL fclose \& (
  342. is called automatically for each open file
  343. when a program terminates normally.)
  344. .NH 2
  345. Error Handling \(em Stderr and Exit
  346. .PP
  347. .UL stderr
  348. is assigned to a program in the same way that
  349. .UL stdin
  350. and
  351. .UL stdout
  352. are.
  353. Output written on
  354. .UL stderr
  355. appears on the user's terminal
  356. even if the standard output is redirected.
  357. .IT wc
  358. writes its diagnostics on
  359. .UL stderr
  360. instead of
  361. .UL stdout
  362. so that if one of the files can't
  363. be accessed for some reason,
  364. the message
  365. finds its way to the user's terminal instead of disappearing
  366. down a pipeline
  367. or into an output file.
  368. .PP
  369. The program actually signals errors in another way,
  370. using the function
  371. .UL exit
  372. to terminate program execution.
  373. The argument of
  374. .UL exit
  375. is available to whatever process
  376. called it (see Section 6),
  377. so the success or failure
  378. of the program can be tested by another program
  379. that uses this one as a sub-process.
  380. By convention, a return value of 0
  381. signals that all is well;
  382. non-zero values signal abnormal situations.
  383. .PP
  384. .UL exit
  385. itself
  386. calls
  387. .UL fclose
  388. for each open output file,
  389. to flush out any buffered output,
  390. then calls
  391. a routine named
  392. .UL _exit .
  393. The function
  394. .UL _exit
  395. causes immediate termination without any buffer flushing;
  396. it may be called directly if desired.
  397. .NH 2
  398. Miscellaneous I/O Functions
  399. .PP
  400. The standard I/O library provides several other I/O functions
  401. besides those we have illustrated above.
  402. .PP
  403. Normally output with
  404. .UL putc ,
  405. etc., is buffered (except to
  406. .UL stderr );
  407. to force it out immediately, use
  408. .UL fflush(fp) .
  409. .PP
  410. .UL fscanf
  411. is identical to
  412. .UL scanf ,
  413. except that its first argument is a file pointer
  414. (as with
  415. .UL fprintf )
  416. that specifies the file from which the input comes;
  417. it returns
  418. .UL EOF
  419. at end of file.
  420. .PP
  421. The functions
  422. .UL sscanf
  423. and
  424. .UL sprintf
  425. are identical to
  426. .UL fscanf
  427. and
  428. .UL fprintf ,
  429. except that the first argument names a character string
  430. instead of a file pointer.
  431. The conversion is done from the string
  432. for
  433. .UL sscanf
  434. and into it for
  435. .UL sprintf .
  436. .PP
  437. .UL fgets(buf,\ size,\ fp)
  438. copies the next line from
  439. .UL fp ,
  440. up to and including a newline,
  441. into
  442. .UL buf ;
  443. at most
  444. .UL size-1
  445. characters are copied;
  446. it returns
  447. .UL NULL
  448. at end of file.
  449. .UL fputs(buf,\ fp)
  450. writes the string in
  451. .UL buf
  452. onto file
  453. .UL fp .
  454. .PP
  455. The function
  456. .UL ungetc(c,\ fp)
  457. ``pushes back'' the character
  458. .UL c
  459. onto the input stream
  460. .UL fp ;
  461. a subsequent call to
  462. .UL getc ,
  463. .UL fscanf ,
  464. etc.,
  465. will encounter
  466. .UL c .
  467. Only one character of pushback per file is permitted.