/share/doc/psd/04.uprog/p9

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