home *** CD-ROM | disk | FTP | other *** search
/ minnie.tuhs.org / unixen.tar / unixen / PDP-11 / Trees / V7 / usr / doc / uprog / p9 < prev   
Encoding:
Text File  |  1979-01-10  |  12.6 KB  |  641 lines

  1. .sp 100
  2. .TL
  3. .ft R
  4. Appendix \(em The Standard I/O Library
  5. .AU
  6. D. M. Ritchie
  7. .AI
  8. .MH
  9. .PP
  10. The standard I/O library
  11. was designed with the following goals in mind.
  12. .IP 1.
  13. It must be as efficient as possible, both in time and in space,
  14. so that there will be no hesitation in using it
  15. no matter how critical the application.
  16. .IP 2.
  17. It must be simple to use, and also free of the magic
  18. numbers and mysterious calls
  19. whose use mars the understandability and portability
  20. of many programs using older packages.
  21. .IP 3.
  22. The interface provided should be applicable on all machines,
  23. whether or not the programs which implement it are directly portable
  24. to other systems,
  25. or to machines other than the PDP-11 running a version of
  26. .UC UNIX .
  27. .SH
  28. 1.  General Usage
  29. .PP
  30. Each program using the library must have the line
  31. .P1
  32.         #include <stdio.h>
  33. .P2
  34. which defines certain macros and variables.
  35. The routines are in the normal C library,
  36. so no special library argument is needed for loading.
  37. All names in the include file intended only for internal use begin
  38. with an underscore
  39. .UL _
  40. to reduce the possibility
  41. of collision with a user name.
  42. The names intended to be visible outside the package are
  43. .IP \f3stdin\f1 10
  44. The name of the standard input file
  45. .IP \f3stdout\f1 10
  46. The name of the standard output file
  47. .IP \f3stderr\f1 10
  48. The name of the standard error file
  49. .IP \f3EOF\f1 10
  50. is actually \-1, and is the value returned by
  51. the read routines on end-of-file or error.
  52. .IP \f3NULL\f1 10
  53. is a notation for the null pointer, returned by
  54. pointer-valued functions
  55. to indicate an error
  56. .IP \f3FILE\f1 10
  57. expands to
  58. .UL struct
  59. .UL _iob
  60. and is a useful
  61. shorthand when declaring pointers
  62. to streams.
  63. .IP \f3BUFSIZ\f1 10
  64. is a number (viz. 512)
  65. of the size suitable for an I/O buffer supplied by the user.
  66. See
  67. .UL setbuf ,
  68. below.
  69. .IP \f3getc,\ getchar,\ putc,\ putchar,\ feof,\ ferror,\ f\&ileno\f1 10
  70. .br
  71. are defined as macros.
  72. Their actions are described below;
  73. they are mentioned here
  74. to point out that it is not possible to
  75. redeclare them
  76. and that they are not actually functions;
  77. thus, for example, they may not have breakpoints set on them.
  78. .PP
  79. The routines in this package
  80. offer the convenience of automatic buffer allocation
  81. and output flushing where appropriate.
  82. The names
  83. .UL stdin ,
  84. .UL stdout ,
  85. and
  86. .UL stderr
  87. are in effect constants and may not be assigned to.
  88. .SH
  89. 2.  Calls
  90. .nr PD .4v
  91. .LP
  92. .UL FILE\ *fopen(filename,\ type)\ char\ *filename,\ *type;
  93. .nr PD 0
  94. .IP
  95. .br
  96. opens the file and, if needed, allocates a buffer for it.
  97. .UL filename
  98. is a character string specifying the name.
  99. .UL type
  100. is a character string (not a single character).
  101. It may be
  102. .UL \&"r" ,
  103. .UL \&"w" ,
  104. or
  105. .UL \&"a"
  106. to indicate
  107. intent to read, write, or append.
  108. The value returned is a file pointer.
  109. If it is
  110. .UL  NULL
  111. the attempt to open failed.
  112. .ne 3
  113. .nr PD .4v
  114. .LP
  115. .UL FILE\ *freopen(filename,\ type,\ ioptr)\ char\ *filename,\ *type;\ FILE\ *ioptr;
  116. .nr PD 0
  117. .IP
  118. .br
  119. The stream named by
  120. .UL ioptr
  121. is closed, if necessary, and then reopened
  122. as if by
  123. .UL fopen .
  124. If the attempt to open fails,
  125. .UL  NULL
  126. is returned,
  127. otherwise
  128. .UL ioptr ,
  129. which will now refer to the new file.
  130. Often the reopened stream is
  131. .UL stdin
  132. or
  133. .UL stdout .
  134. .nr PD .4v
  135. .LP
  136. .UL int\ getc(ioptr)\ FILE\ *ioptr;
  137. .nr PD 0
  138. .IP
  139. returns the next character from the stream named by
  140. .UL ioptr ,
  141. which is a pointer to a file such as returned by
  142. .UL fopen ,
  143. or the name
  144. .UL stdin .
  145. The integer
  146. .UL  EOF
  147. is returned on end-of-file or when
  148. an error occurs.
  149. The null character
  150. .UL \e0
  151. is a legal character.
  152. .nr PD .4v
  153. .LP
  154. .UL int\ fgetc(ioptr)\ FILE\ *ioptr;
  155. .nr PD 0
  156. .IP
  157. .br
  158. acts like
  159. .UL getc
  160. but is a genuine function,
  161. not a macro,
  162. so it can be pointed to, passed as an argument, etc.
  163. .nr PD .4v
  164. .LP
  165. .UL putc(c,\ ioptr)\ FILE\ *ioptr;
  166. .nr PD 0
  167. .IP
  168. .br
  169. .UL putc
  170. writes the character
  171. .UL c
  172. on the output stream named by
  173. .UL ioptr ,
  174. which is a value returned from
  175. .UL fopen
  176. or perhaps
  177. .UL stdout
  178. or
  179. .UL stderr .
  180. The character is returned as value,
  181. but
  182. .UL  EOF
  183. is returned on error.
  184. .nr PD .4v
  185. .LP
  186. .UL fputc(c,\ ioptr)\ FILE\ *ioptr;
  187. .nr PD 0
  188. .IP
  189. .br
  190. acts like
  191. .UL putc
  192. but is a genuine
  193. function, not a macro.
  194. .nr PD .4v
  195. .LP
  196. .UL fclose(ioptr)\ FILE\ *ioptr;
  197. .nr PD 0
  198. .IP
  199. .br
  200. The file corresponding to
  201. .UL ioptr
  202. is closed after any buffers are emptied.
  203. A buffer allocated by the I/O system is freed.
  204. .UL fclose
  205. is automatic on normal termination of the program.
  206. .nr PD .4v
  207. .LP
  208. .UL fflush(ioptr)\ FILE\ *ioptr;
  209. .nr PD 0
  210. .IP
  211. .br
  212. Any buffered information on the (output) stream named by
  213. .UL ioptr
  214. is written out.
  215. Output files are normally buffered
  216. if and only if they are not directed to the terminal;
  217. however,
  218. .UL stderr
  219. always starts off unbuffered and remains so unless
  220. .UL setbuf
  221. is used, or unless it is reopened.
  222. .nr PD .4v
  223. .LP
  224. .UL exit(errcode);
  225. .nr PD 0
  226. .IP
  227. .br
  228. terminates the process and returns its argument as status
  229. to the parent.
  230. This is a special version of the routine
  231. which calls
  232. .UL fflush
  233. for each output file.
  234. To terminate without flushing,
  235. use
  236. .UL _exit .
  237. .nr PD .4v
  238. .LP
  239. .UL feof(ioptr)\ FILE\ *ioptr;
  240. .nr PD 0
  241. .IP
  242. .br
  243. returns non-zero when end-of-file
  244. has occurred on the specified input stream.
  245. .nr PD .4v
  246. .LP
  247. .UL ferror(ioptr)\ FILE\ *ioptr;
  248. .nr PD 0
  249. .IP
  250. .br
  251. returns non-zero when an error has occurred while reading
  252. or writing the named stream.
  253. The error indication lasts until the file has been closed.
  254. .nr PD .4v
  255. .LP
  256. .UL getchar();
  257. .nr PD 0
  258. .IP
  259. .br
  260. is identical to
  261. .UL getc(stdin) .
  262. .nr PD .4v
  263. .LP
  264. .UL putchar(c);
  265. .nr PD 0
  266. .IP
  267. .br
  268. is identical to
  269. .UL putc(c,\ stdout) .
  270. .nr PD .4v
  271. .nr PD .4v
  272. .ne 2
  273. .LP
  274. .UL char\ *fgets(s,\ n,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
  275. .nr PD 0
  276. .IP
  277. .br
  278. reads up to
  279. .UL n-1
  280. characters from the stream
  281. .UL ioptr
  282. into the character pointer
  283. .UL s .
  284. The read terminates with a newline character.
  285. The newline character is placed in the buffer
  286. followed by a null character.
  287. .UL fgets
  288. returns the first argument,
  289. or
  290. .UL  NULL
  291. if error or end-of-file occurred.
  292. .nr PD .4v
  293. .nr PD .4v
  294. .LP
  295. .UL fputs(s,\ ioptr)\ char\ *s;\ FILE\ *ioptr;
  296. .nr PD 0
  297. .IP
  298. .br
  299. writes the null-terminated string (character array)
  300. .UL s
  301. on the stream
  302. .UL ioptr .
  303. No newline is appended.
  304. No value is returned.
  305. .nr PD .4v
  306. .LP
  307. .UL ungetc(c,\ ioptr)\ FILE\ *ioptr;
  308. .nr PD 0
  309. .IP
  310. .br
  311. The argument character
  312. .UL c
  313. is pushed back on the input stream named by
  314. .UL ioptr .
  315. Only one character may be pushed back.
  316. .ne 5
  317. .nr PD .4v
  318. .LP
  319. .UL printf(format,\ a1,\ ...)\ char\ *format;
  320. .br
  321. .UL fprintf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
  322. .br
  323. .UL sprintf(s,\ format,\ a1,\ ...)char\ *s,\ *format;
  324. .br
  325. .nr PD 0
  326. .IP
  327. .UL printf
  328. writes on the standard output.
  329. .UL fprintf
  330. writes on the named output stream.
  331. .UL sprintf
  332. puts characters in the character array (string)
  333. named by
  334. .UL s .
  335. The specifications are as described in section
  336. .UL printf (3)
  337. of the
  338. .ul
  339. .UC UNIX
  340. .ul
  341. Programmer's Manual.
  342. .nr PD .4v
  343. .LP
  344. .UL scanf(format,\ a1,\ ...)\ char\ *format;
  345. .br
  346. .UL fscanf(ioptr,\ format,\ a1,\ ...)\ FILE\ *ioptr;\ char\ *format;
  347. .br
  348. .UL sscanf(s,\ format,\ a1,\ ...)\ char\ *s,\ *format;
  349. .nr PD 0
  350. .IP
  351. .br
  352. .UL scanf
  353. reads from the standard input.
  354. .UL fscanf
  355. reads from the named input stream.
  356. .UL sscanf
  357. reads from the character string
  358. supplied as
  359. .UL s .
  360. .UL scanf
  361. reads characters, interprets
  362. them according to a format, and stores the results in its arguments.
  363. Each routine expects as arguments
  364. a control string
  365. .UL format ,
  366. and a set of arguments,
  367. .I
  368. each of which must be a pointer,
  369. .R
  370. indicating where the converted input should be stored.
  371. .if t .sp .4v
  372. .UL scanf
  373. returns as its value the number of successfully matched and assigned input
  374. items.
  375. This can be used to decide how many input items were found.
  376. On end of file,
  377. .UL EOF
  378. is returned; note that this is different
  379. from 0, which means that the next input character does not
  380. match what was called for in the control string.
  381. .RE
  382. .nr PD .4v
  383. .LP
  384. .UL fread(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
  385. .nr PD 0
  386. .IP
  387. .br
  388. reads
  389. .UL nitems
  390. of data beginning at
  391. .UL ptr
  392. from file
  393. .UL ioptr .
  394. No advance notification
  395. that binary I/O is being done is required;
  396. when, for portability reasons,
  397. it becomes required, it will be done
  398. by adding an additional character to the mode-string on the
  399. .UL fopen
  400. call.
  401. .nr PD .4v
  402. .LP
  403. .UL fwrite(ptr,\ sizeof(*ptr),\ nitems,\ ioptr)\ FILE\ *ioptr;
  404. .nr PD 0
  405. .IP
  406. .br
  407. Like
  408. .UL fread ,
  409. but in the other direction.
  410. .nr PD .4v
  411. .LP
  412. .UL rewind(ioptr)\ FILE\ *ioptr;
  413. .nr PD 0
  414. .IP
  415. .br
  416. rewinds the stream
  417. named by
  418. .UL ioptr .
  419. It is not very useful except on input,
  420. since a rewound output file is still open only for output.
  421. .nr PD .4v
  422. .LP
  423. .UL system(string)\ char\ *string;
  424. .nr PD 0
  425. .IP
  426. .br
  427. The
  428. .UL string
  429. is executed by the shell as if typed at the terminal.
  430. .nr PD .4v
  431. .LP
  432. .UL getw(ioptr)\ FILE\ *ioptr;
  433. .nr PD 0
  434. .IP
  435. .br
  436. returns the next word from the input stream named by
  437. .UL ioptr .
  438. .UL EOF
  439. is returned on end-of-file or error,
  440. but since this a perfectly good
  441. integer
  442. .UL feof
  443. and
  444. .UL ferror
  445. should be used.
  446. A ``word'' is 16 bits on the
  447. .UC PDP-11.
  448. .nr PD .4v
  449. .LP
  450. .UL putw(w,\ ioptr)\ FILE\ *ioptr;
  451. .nr PD 0
  452. .IP
  453. .br
  454. writes the integer
  455. .UL w
  456. on the named output stream.
  457. .nr PD .4v
  458. .LP
  459. .UL setbuf(ioptr,\ buf)\ FILE\ *ioptr;\ char\ *buf;
  460. .nr PD 0
  461. .IP
  462. .br
  463. .UL setbuf
  464. may be used after a stream has been opened
  465. but before I/O has started.
  466. If
  467. .UL buf
  468. is
  469. .UL NULL ,
  470. the stream will be unbuffered.
  471. Otherwise the buffer supplied will be used.
  472. It must be a character array of sufficient size:
  473. .P1
  474. char    buf[BUFSIZ];
  475. .P2
  476. .nr PD .4v
  477. .LP
  478. .UL fileno(ioptr)\ FILE\ *ioptr;
  479. .nr PD 0
  480. .IP
  481. .br
  482. returns the integer file descriptor associated with the file.
  483. .nr PD .4v
  484. .LP
  485. .UL fseek(ioptr,\ offset,\ ptrname)\ FILE\ *ioptr;\ long\ offset;
  486. .nr PD 0
  487. .IP
  488. .br
  489. The location of the next byte in the stream
  490. named by
  491. .UL ioptr
  492. is adjusted.
  493. .UL offset
  494. is a long integer.
  495. If
  496. .UL ptrname
  497. is 0, the offset is measured from the beginning of the file;
  498. if
  499. .UL ptrname
  500. is 1, the offset is measured from the current read or
  501. write pointer;
  502. if
  503. .UL ptrname
  504. is 2, the offset is measured from the end of the file.
  505. The routine accounts properly for any buffering.
  506. (When this routine is used on
  507. .UC UNIX \& non-
  508. systems,
  509. the offset must be a value returned from
  510. .UL ftell
  511. and the ptrname must be 0).
  512. .ne 3
  513. .nr PD .4v
  514. .LP
  515. .UL long\ ftell(ioptr)\ FILE\ *ioptr;
  516. .nr PD 0
  517. .IP
  518. .br
  519. The byte offset, measured from the beginning of the file,
  520. associated with the named stream is returned.
  521. Any buffering is properly accounted for.
  522. (On
  523. .UC UNIX \& non-
  524. systems the value of this call is useful only
  525. for handing to
  526. .UL fseek ,
  527. so as to position the file to the same place it was when
  528. .UL ftell
  529. was called.)
  530. .nr PD .4v
  531. .LP
  532. .UL getpw(uid,\ buf)\ char\ *buf;
  533. .nr PD 0
  534. .IP
  535. .br
  536. The password file is searched for the given integer user ID.
  537. If an appropriate line is found, it is copied into
  538. the character array
  539. .UL buf ,
  540. and 0 is returned.
  541. If no line is found corresponding to the user ID
  542. then 1 is returned.
  543. .nr PD .4v
  544. .LP
  545. .UL char\ *malloc(num);
  546. .nr PD 0
  547. .IP
  548. .br
  549. allocates
  550. .UL num
  551. bytes.
  552. The pointer returned is sufficiently well aligned to be usable for any purpose.
  553. .UL NULL
  554. is returned if no space is available.
  555. .nr PD .4v
  556. .LP
  557. .UL char\ *calloc(num,\ size);
  558. .nr PD 0
  559. .IP
  560. .br
  561. allocates space for
  562. .UL num
  563. items each of size
  564. .UL size .
  565. The space is guaranteed to be set to 0 and the pointer is
  566. sufficiently well aligned to be usable for any purpose.
  567. .UL NULL
  568. is returned if no space is available .
  569. .nr PD .4v
  570. .LP
  571. .UL cfree(ptr)\ char\ *ptr;
  572. .nr PD 0
  573. .IP
  574. .br
  575. Space is returned to the pool used by
  576. .UL calloc .
  577. Disorder can be expected if the pointer was not obtained
  578. from
  579. .UL calloc .
  580. .nr PD .4v
  581. .LP
  582. The following are macros whose definitions may be obtained by including
  583. .UL <ctype.h> .
  584. .nr PD .4v
  585. .LP
  586. .UL isalpha(c)
  587. returns non-zero if the argument is alphabetic.
  588. .nr PD .4v
  589. .LP
  590. .UL isupper(c)
  591. returns non-zero if the argument is upper-case alphabetic.
  592. .nr PD .4v
  593. .LP
  594. .UL islower(c)
  595. returns non-zero if the argument is lower-case alphabetic.
  596. .nr PD .4v
  597. .LP
  598. .UL isdigit(c)
  599. returns non-zero if the argument is a digit.
  600. .nr PD .4v
  601. .LP
  602. .UL isspace(c)
  603. returns non-zero if the argument is a spacing character:
  604. tab, newline, carriage return, vertical tab,
  605. form feed, space.
  606. .nr PD .4v
  607. .LP
  608. .UL ispunct(c)
  609. returns non-zero if the argument is
  610. any punctuation character, i.e., not a space, letter,
  611. digit or control character.
  612. .nr PD .4v
  613. .LP
  614. .UL isalnum(c)
  615. returns non-zero if the argument is a letter or a digit.
  616. .nr PD .4v
  617. .LP
  618. .UL isprint(c)
  619. returns non-zero if the argument is printable \(em
  620. a letter, digit, or punctuation character.
  621. .nr PD .4v
  622. .LP
  623. .UL iscntrl(c)
  624. returns non-zero if the argument is a control character.
  625. .nr PD .4v
  626. .LP
  627. .UL isascii(c)
  628. returns non-zero if the argument is an ascii character, i.e., less than octal 0200.
  629. .nr PD .4v
  630. .LP
  631. .UL toupper(c)
  632. returns the upper-case character corresponding to the lower-case
  633. letter
  634. .UL c.
  635. .nr PD .4v
  636. .LP
  637. .UL tolower(c)
  638. returns the lower-case character corresponding to the upper-case
  639. letter
  640. .UL c .
  641.