home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_100 / 163_02 / sclib.scr < prev    next >
Text File  |  1987-06-03  |  36KB  |  1,347 lines
  1. .tm 6
  2. .fo left
  3. :gdoc sec= 'IBM Internal Use Only'
  4. :frontm.
  5. :titlep
  6. :title.Small-c I/O and Utility Library
  7. :title.for the IBM Personal Computer
  8. :title.Release 1.05
  9. :title stitle= 'Small-c I/O and Utility Library'.
  10. :author.Daniel. R. Hicks
  11. :address
  12. :aline.RCH38DB(HICKS)
  13. :eaddress
  14. :etitlep
  15.  
  16. :toc.
  17.  
  18. :body
  19. :h0.Small-c I/O and Utility Library
  20.  
  21. .kp on
  22. :h4. abort(status)
  23. :p.Declarations:
  24. :sl compact
  25. :li.int status;
  26. :esl
  27. :p.:hp2.abort:ehp2.
  28. terminates execution of the program and returns to DOS.
  29. :hp2.abort:ehp2. differs from :hp2.exit:ehp2. in that it produces
  30. a diagnostic dump of stack frame addresses (using :hp2.traceback:ehp2.)
  31. before exiting.  Like
  32. :hp2.exit:ehp2., :hp2.abort:ehp2. attempts to close open files before
  33. returning to DOS.  :hp2.abort:ehp2. does not set the DOS 2.0 return
  34. code.
  35.  
  36. .kp on
  37. :h4. abs(i)
  38. :p.Declarations:
  39. :sl compact
  40. :li.int i;
  41. :esl
  42. :p.:hp2.abs:ehp2.
  43. returns the absolute value of the integer argument.
  44.  
  45. .kp on
  46. :h4. assert(expression)
  47. :p.Declarations:
  48. :sl compact
  49. :li.#include <assert.h>
  50. :li.int expression;
  51. :esl
  52. :p.:hp2.assert:ehp2.
  53. causes an :hp2.abort:ehp2. with a diagnostic message when
  54. :hp2.expression:ehp2.
  55. is false.
  56.  
  57. .kp on
  58. :h4. atoi(nptr)
  59. :p.Declarations:
  60. :sl compact
  61. :li.char *nptr;
  62. :esl
  63. :p.:hp2.atoi:ehp2.
  64. converts the ASCII character string pointed to by
  65. :hp2.nptr:ehp2.
  66. to an integer, interpreting the string as a decimal number.  The first
  67. unrecognized character ends the string.
  68.  
  69. .kp on
  70. :h4. calloc(nelem, elsize)
  71. :p.Declarations:
  72. :sl compact
  73. :li.int nelem, elsize;
  74. :esl
  75. :p.:hp2.calloc:ehp2.
  76. allocates space for an array of
  77. :hp2.nelem:ehp2.
  78. elements of size
  79. :hp2.elsize:ehp2..
  80. The space is initialized to binary zeros.
  81. A null pointer (0) is returned if the space cannot be allocated.
  82.  
  83. .kp on
  84. :h4. CCARGC()
  85. :p.Declarations:
  86. :sl compact
  87. :esl
  88. :p.:hp2.CCARGC:ehp2.
  89. returns the number of arguments passed to the calling program.
  90. :hp2.CCARGC:ehp2.
  91. works by returning the value in the DL register.
  92. :hp2.CCARGC:ehp2.
  93. must be called before the DL register is modified.  The DL register is
  94. modified by a multiply or divide operation or by a call to another function.
  95.  
  96. .kp on
  97. :h4. clearerr(stream)
  98. :p.Declarations:
  99. :sl compact
  100. :li.FILE *stream;
  101. :esl
  102. :p.:hp2.clearerr:ehp2.
  103. clears the error indicator associated with
  104. :hp2.stream:ehp2..
  105.  
  106. .kp on
  107. :h4. errno
  108. :p.Declarations:
  109. :sl compact
  110. :esl
  111. :p.:hp2.errno:ehp2.
  112. is an external integer which is set with one of the values defined in
  113. :hp2.errno.h:ehp2.
  114. when an I/O error or system error is detected.  This value is NOT cleared when
  115. non-erroneous calls are made.
  116.  
  117. .kp on
  118. :h4. exit(status)
  119. :p.Declarations:
  120. :sl compact
  121. :li.int status;
  122. :esl
  123. :p.:hp2.exit:ehp2.
  124. terminates execution of the program and returns to DOS.
  125. :hp2.exit:ehp2. differs from :hp2._exit:ehp2. in that it attempts to
  126. close open files before returning to DOS.  :hp2.exit:ehp2. does not
  127. set the DOS 2.0 return code.
  128.  
  129. .kp on
  130. :h4. fbinary(stream)
  131. :p.Declarations:
  132. :sl compact
  133. :li.FILE *stream;
  134. :esl
  135. :p.:hp2.fbinary:ehp2.
  136. causes the named
  137. :hp2.stream:ehp2.
  138. to be processed as a binary file, without performing the CR/LF processing which
  139. is done for text and source files.
  140.  
  141. .kp on
  142. :h4. fclose(stream)
  143. :p.Declarations:
  144. :sl compact
  145. :li.FILE *stream;
  146. :esl
  147. :p.:hp2.fclose:ehp2.
  148. causes any buffers for the named
  149. :hp2.stream:ehp2.
  150. to be emptied and the file to be closed.  Buffers allocated by
  151. the standard I/O system are freed.
  152. :hp2.fclose:ehp2.
  153. is performed automatically upon calling
  154. :hp2.exit:ehp2..
  155. :hp2.EOF:ehp2.
  156. is returned if
  157. :hp2.stream:ehp2.
  158. is not associated with an output file, or if the file is not buffered.
  159.  
  160. .kp on
  161. :h4. feof(stream)
  162. :p.Declarations:
  163. :sl compact
  164. :li.FILE *stream;
  165. :esl
  166. :p.:hp2.feof:ehp2.
  167. returns non-zero when end of file is read on
  168. :hp2. stream:ehp2.,
  169. otherwise zero.
  170.  
  171. .kp on
  172. :h4. ferror(stream)
  173. :p.Declarations:
  174. :sl compact
  175. :li.FILE *stream;
  176. :esl
  177. :p.:hp2.ferror:ehp2.
  178. returns non-zero when an error has occurred on
  179. :hp2.stream:ehp2.,
  180. otherwise zero.  Unless cleared by
  181. :hp2.clearerr:ehp2.,
  182. the error indication lasts until
  183. :hp2.stream:ehp2.
  184. is closed.
  185.  
  186. .kp on
  187. :h4. fflush(stream)
  188. :p.Declarations:
  189. :sl compact
  190. :li.FILE *stream;
  191. :esl
  192. :p.:hp2.fflush:ehp2.
  193. causes any buffered data for the named output
  194. :hp2. stream:ehp2.
  195. to be written to that file.  The stream remains open.
  196. :hp2.EOF:ehp2.
  197. is returned if
  198. :hp2.stream:ehp2.
  199. is not associated with an output file, or if the file is not buffered.
  200.  
  201. .kp on
  202. :h4. fgetc(stream)
  203. :p.Declarations:
  204. :sl compact
  205. :li.FILE *stream;
  206. :esl
  207. :p.:hp2.fgetc:ehp2.
  208. returns the next character read from
  209. :hp2.stream:ehp2..
  210. EOF is returned on error or end of file.
  211.  
  212. .kp on
  213. :h4. fgets(s, n, stream)
  214. :p.Declarations:
  215. :sl compact
  216. :li.char *s;
  217. :li.int n;
  218. :li.FILE *stream;
  219. :esl
  220. :p.:hp2.fgets:ehp2.
  221. reads a string from
  222. :hp2.stream:ehp2.
  223. into the character string addressed by
  224. :hp2.s:ehp2..
  225. Characters are read until a newline character is read or until
  226. :hp2.n-1:ehp2.
  227. characters are read, whichever is first.
  228. The last character placed in s is always followed by a null character.
  229. Unlike
  230. :hp2.gets:ehp2.,
  231. the newline character, if encountered, is placed in s.
  232.  
  233. .kp on
  234. :h4. fileno(stream)
  235. :p.Declarations:
  236. :sl compact
  237. :li.FILE *stream;
  238. :esl
  239. :p.:hp2.fileno:ehp2.
  240. returns the integer file descriptor (such as returned by
  241. :hp2._open):ehp2.
  242. associated with
  243. :hp2.stream:ehp2..
  244.  
  245. .kp on
  246. :h4. fopen(filename, type)
  247. :p.Declarations:
  248. :sl compact
  249. :li.char *filename, *type;
  250. :esl
  251. :p.:hp2.fopen:ehp2.
  252. opens the file named by
  253. :hp2.filename:ehp2.
  254. and associates a stream with it.
  255. :hp2.fopen:ehp2.
  256. returns a pointer used to identify the stream in subsequent
  257. operations.
  258. :hp2.type:ehp2.
  259. is a character string having one of the following values:
  260. :dl compact
  261. :dt.r
  262. :dd.Open for reading
  263. :dt.w
  264. :dd.Create for writing
  265. :dt.a
  266. :dd.Open for writing at the end of file (if it exists), or create for
  267. writing
  268. :dt.r+
  269. :dd.Open for read/write and position at the beginning of the file.
  270. :dt.w+
  271. :dd.Open for read/write, truncate the file, and position to the beginning
  272. of it
  273. :dt.a+
  274. :dd.Open for read/write and position at the end of the file.
  275. :edl
  276. :p.:hp2.fopen:ehp2.
  277. returns the pointer
  278. :hp2.NULL:ehp2.
  279. if
  280. :hp2.filename:ehp2.
  281. cannot be accessed.
  282.  
  283. .kp on
  284. :h4. fprintf(stream, format, [, arg] . . . )
  285. :p.Declarations:
  286. :sl compact
  287. :li.FILE *stream;
  288. :li.char *format;
  289. :esl
  290. :p.:hp2.fprintf:ehp2.
  291. formats the values represented by the
  292. :hp2.arg:ehp2.
  293. arguments and outputs them to
  294. :hp2.stream:ehp2.
  295. according to the format specified by
  296. :hp2.format:ehp2..
  297. format is a character string to be printed which optionally contains
  298. conversion specifications beginning with the character %.  Following the
  299. % character is a specification which describes how the corresponding
  300. argument is to be formatted.  There must be at least enough arguments
  301. to satisfy the requirements of the format specification.
  302. .kp off
  303.  
  304. Each conversion specification consists of:
  305. :ul compact
  306. :li.the % character.
  307. :li.an optional minus sign ("-") which specifies left
  308. adjustment of the converted
  309. value within the indicated field.
  310. :li.an optional digit string specifying field width.
  311. If the converted value has
  312. characters than the field width, the field is padded
  313. to the specified width.
  314. Padding is on the left unless a minus sign was used to
  315. specify left adjustment
  316. (and therefore right padding).  Padding is with blanks
  317. unless the field width
  318. began with a zero digit, in which case zero-padding is done instead.
  319. :li.an optional period (".") which serves to separate the
  320. field width from the
  321. next digit string.
  322. :li.an optional digit string specifying the maximum number
  323. of characters to be
  324. printed from a string (s-format only).
  325. :li.a character indicating the type of conversion to be performed.
  326. :eul
  327. :p.A field width or maximum string width
  328. value may be replaced with "*" (instead
  329. of the digit string).
  330. This indicates that the next argument is to be interpreted
  331. as the integer field width or maximum string width.
  332. :p.The characters which may be
  333. used for specifying the type of conversion are:
  334. :dl compact
  335. :dt.c
  336. :dd.The character value of the argument is printed.
  337. :dt.d
  338. :dd.The signed integer
  339. value of the argument is printed (-32768 to 32767).
  340. :dt.o
  341. :dd.The unsigned octal
  342. integer value of the argument is printed (0 to 177777).
  343. :dt.s
  344. :dd.The character string addressed by the argument is printed.
  345. :dt.u
  346. :dd.The unsigned integer value of the argument is printed (0 to 65535).
  347. :dt.x
  348. :dd.The unsigned hexadecimal integer value of the argument is printed
  349. (0 to FFFF).
  350. :dt.%
  351. :dd."%" is printed.
  352. :edl
  353. In no case does a small field width value cause truncation of a field; padding
  354. takes place only if the specified field width exceeds the actual width.
  355.  
  356. .kp on
  357. :h4. fputc(c, stream)
  358. :p.Declarations:
  359. :sl compact
  360. :li.char c;
  361. :li.FILE *stream;
  362. :esl
  363. :p.:hp2.fputc:ehp2.
  364. appends the character :hp2.c:ehp2. to the named output
  365. :hp2.stream:ehp2..  It returns the character written.
  366. If an error occurs, :hp2.EOF:ehp2. is returned.
  367.  
  368. .kp on
  369. :h4. fputs(s, stream)
  370. :p.Declarations:
  371. :sl compact
  372. :li.char *s;
  373. :li.FILE *stream;
  374. :esl
  375. :p.:hp2.fputs:ehp2.
  376. copies the null-terminated string addressed by
  377. :hp2.s:ehp2.
  378. to
  379. :hp2.stream:ehp2..
  380. Unlike
  381. :hp2.puts:ehp2.,
  382. fputs does not append a newline to the string.
  383.  
  384. .kp on
  385. :h4. fread(ptr, type, nitems, stream)
  386. :p.Declarations:
  387. :sl compact
  388. :li.char /* or int */ *ptr;
  389. :li.int type, nitems;
  390. :li.FILE *stream;
  391. :esl
  392. :p.:hp2.fread:ehp2.
  393. reads, into a block beginning at
  394. :hp2.ptr, nitems:ehp2.
  395. of data of the type indicated by
  396. :hp2.type:ehp2.,
  397. where type == 1 for char data and type == 2 for int data.
  398. It returns the number of items actually read.
  399. :hp2.fread:ehp2.
  400. returns 0 upon end-of-file or error.  If
  401. :hp2.stream:ehp2.
  402. is
  403. :hp2.stdin:ehp2.
  404. or
  405. :hp2.stdout:ehp2.,
  406. then
  407. :hp2.stdout:ehp2.
  408. and
  409. :hp2.stderr:ehp2.
  410. are flushed before any call to
  411. :hp2._read:ehp2.
  412. to satisfy the
  413. :hp2.fread:ehp2..
  414.  
  415. .kp on
  416. :h4. free(ptr)
  417. :p.Declarations:
  418. :sl compact
  419. :li.char *ptr;
  420. :esl
  421. :p.:hp2.free:ehp2.
  422. deallocates the section of heap storage addressed by :hp2.ptr:ehp2..
  423. :hp2.ptr:ehp2. must contain a value previously obtained from
  424. :hp2.malloc:ehp2. (or :hp2.calloc:ehp2.) or serious damage to the
  425. heap structure can result.
  426.  
  427. .kp on
  428. :h4. fseek2(stream, offset, ptrname)
  429. :p.Declarations:
  430. :sl compact
  431. :li.FILE *stream;
  432. :li.int offset, ptrname;
  433. :esl
  434. :p.:hp2.fseek2:ehp2.
  435. sets the position of the next input or output operation on
  436. :hp2.stream:ehp2..
  437. The new position is the signed distance
  438. :hp2.offset:ehp2.
  439. bytes from the beginning, the current position, or the end of the
  440. file, for
  441. :hp2.ptrname:ehp2.
  442. values of 0, 1, and 2, respectively.
  443. The new position is the signed distance
  444. (:hp2.offset:ehp2. * 512)
  445. bytes from the beginning, the current position, or the end of the
  446. file, for
  447. :hp2.ptrname:ehp2.
  448. values of 3, 4, and 5, respectively.
  449. :hp2.fseek2:ehp2. undoes any effects of
  450. :hp2.ungetc:ehp2..  :hp2.fseek2:ehp2.
  451. returns -1 for improper seeks.
  452.  
  453. .kp on
  454. :h4. ftell2(stream, ptrname)
  455. :p.Declarations:
  456. :sl compact
  457. :li.FILE *stream;
  458. :li.int ptrname;
  459. :esl
  460. :p.:hp2.ftell2:ehp2. returns the position within :hp2.stream:ehp2.
  461. which will be used for the next input or output operation.
  462. The value returned is the distance to the current position
  463. from the beginning of the file.  If :hp2.ptrname:ehp2. is zero,
  464. then the value is in units of bytes (modulo 65 536).  If
  465. :hp2.ptrname:ehp2. is non-zero, then the value is in units of 512
  466. bytes.  A value of -1 is returned if :hp2.stream:ehp2. is invalid
  467. for seeks.
  468.  
  469. .kp on
  470. :h4. fwrite(ptr, type, nitems, stream)
  471. :p.Declarations:
  472. :sl compact
  473. :li.char /* or int */ *ptr;
  474. :li.int type, nitems;
  475. :li.FILE *stream;
  476. :esl
  477. :p.:hp2.fwrite:ehp2.
  478. writes, from a block beginning at
  479. :hp2.ptr, nitems:ehp2.
  480. of data of the type indicated by
  481. :hp2.type:ehp2.,
  482. where type == 1 for char data and type == 2 for int data.
  483. It returns the number of items actually written.
  484. :hp2.fwrite:ehp2.
  485. returns 0 upon error.
  486.  
  487. .kp on
  488. :hp2.getc(stream)
  489. :p.Declarations:
  490. :sl compact
  491. :li.FILE *stream;
  492. :esl
  493. :p.:hp2.getc:ehp2.
  494. is a macro synonym for
  495. :hp2.fgetc:ehp2..
  496.  
  497. .kp on
  498. :h4. getchar()
  499. :p.Declarations:
  500. :sl compact
  501. :esl
  502. :p.:hp2.getchar:ehp2.
  503. returns the next character read from stdin.
  504. EOF is returned on error or end of file.
  505. Unlike the standard UNIX version,
  506. getchar is a true function and not a macro.
  507.  
  508. .kp on
  509. :h4. getparm(string)
  510. :p.Declarations:
  511. :sl compact
  512. :li.char *string;
  513. :esl
  514. :p.:hp2.getparm:ehp2.
  515. returns in the character array addressed by
  516. :hp2.string:ehp2.
  517. the DOS parameter string copied from the DOS program segment prefix.
  518. The array addressed by string should be at least 128 characters long to
  519. handle the worst case.
  520.  
  521. .kp on
  522. :h4. gets(s)
  523. :p.Declarations:
  524. :sl compact
  525. :li.char *s;
  526. :esl
  527. :p.:hp2.gets:ehp2.
  528. reads a string from stdin
  529. into the character string addressed by
  530. :hp2.s:ehp2..
  531. Characters are read until a newline character is encountered, and, unlike
  532. :hp2.fgets:ehp2.,
  533. the newline character is not placed in s.
  534. The last charactions:
  535. :sl compact
  536. :li.char c;
  537. :esl
  538. :p.:hp2.isalpha:ehp2.
  539. returns a non-zero value if character
  540. :hp2.c:ehp2.
  541. is a letter (A-Z, upper or lower case).  Otherwise, the
  542. value returned is zero.  The test assumes the standard ASCII character set.
  543.  
  544. .kp on
  545. :h4. isascii(c)
  546. :p.Declarations:
  547. :sl compact
  548. :li.char c;
  549. :esl
  550. :p.:hp2.isascii:ehp2.
  551. returns a non-zero value if character
  552. :hp2.c:ehp2.
  553. is a valid ASCII character (value less than 0200 octal).  Otherwise, the
  554. value returned is zero.
  555.  
  556. .kp on
  557. :h4. iscntrl(c)
  558. :p.Declarations:
  559. :sl compact
  560. :li.char c;
  561. :esl
  562. :p.:hp2.iscntrl:ehp2.
  563. returns a non-zero value if character
  564. :hp2.c:ehp2.
  565. is an ASCII control character (value less than 040 octal) or a delete character
  566. (0177 octal).  Otherwise, the value returned is zero.
  567.  
  568. .kp on
  569. :h4. isdigit(c)
  570. :p.Declarations:
  571. :sl compact
  572. :li.char c;
  573. :esl
  574. :p.:hp2.isdigit:ehp2.
  575. returns a non-zero value if character
  576. :hp2.c:ehp2.
  577. is a digit (0-9).  Otherwise, the value returned is zero.
  578. The test assumes the standard ASCII character set.
  579.  
  580. .kp on
  581. :h4. islower(c)
  582. :p.Declarations:
  583. :sl compact
  584. :li.char c;
  585. :esl
  586. :p.:hp2.islower:ehp2.
  587. returns a non-zero value if character
  588. :hp2.c:ehp2.
  589. is a lower case alphabetic character (a-z).  Otherwise, the value returned
  590. is zero.  The test assumes the standard ASCII character set.
  591.  
  592. .kp on
  593. :h4. isprint(c)
  594. :p.Declarations:
  595. :sl compact
  596. :li.char c;
  597. :esl
  598. :p.:hp2.isprint:ehp2.
  599. returns a non-zero value if character
  600. :hp2.c:ehp2.
  601. is a printing character:  Space (040 octal) through tilde (0176 octal).
  602. Otherwise, the value returned
  603. is zero.  The test assumes the standard ASCII character set.
  604.  
  605. .kp on
  606. :h4. ispunct(c)
  607. :p.Declarations:
  608. :sl compact
  609. :li.char c;
  610. :esl
  611. :p.:hp2.ispunct:ehp2.
  612. returns a non-zero value if character
  613. :hp2.c:ehp2.
  614. is neither a control character nor an alphanumeric character.
  615. Otherwise, the value returned
  616. is zero.  The test assumes the standard ASCII character set.
  617.  
  618. .kp on
  619. :h4. isspace(c)
  620. :p.Declarations:
  621. :sl compact
  622. :li.char c;
  623. :esl
  624. :p.:hp2.isspace:ehp2.
  625. returns a non-zero value if character
  626. :hp2.c:ehp2.
  627. is a space, tab, carriage return, newline, or form feed.
  628. Otherwise, the value returned
  629. is zero.  The test assumes the standard ASCII character set.
  630.  
  631. .kp on
  632. :h4. isupper(c)
  633. :p.Declarations:
  634. :sl compact
  635. :li.char c;
  636. :esl
  637. :p.:hp2.isupper:ehp2.
  638. returns a non-zero value if character
  639. :hp2.c:ehp2.
  640. is a upper case alphabetic character (A-Z).  Otherwise, the value returned
  641. is zero.  The test assumes the standard ASCII character set.
  642.  
  643. .kp on
  644. :h4. malloc(size)
  645. :p.Declarations:
  646. :sl compact
  647. :li.int size;
  648. :esl
  649. :p.:hp2.malloc:ehp2. allocates a block of (at least) :hp2.size:ehp2.
  650. bytes from the heap and returns a pointer to the first usable byte.
  651. The space is not initialized to any particular value.
  652. A null pointer (0) is returned if no storage is available.
  653.  
  654. .kp on
  655. :h4. peekc(seg, offset)
  656. :p.Declarations:
  657. :sl compact
  658. :li.int seg, offset;
  659. :esl
  660. :p.:hp2.peekc:ehp2.
  661. returns the value (sign extended) of the byte at
  662. :hp2.offset:ehp2.
  663. in
  664. :hp2.seg:ehp2.
  665. in the 8088 address space.
  666.  
  667. .kp on
  668. :h4. perror(s)
  669. :p.Declarations:
  670. :sl compact
  671. :li.char *s;
  672. :esl
  673. :p.:hp2.perror:ehp2.
  674. produces a short error message on stderr describing the error present in
  675. :hp2.errno:ehp2..
  676. First the argument string addressed by
  677. :hp2.s:ehp2.
  678. is printed, then a colon, then the message, and then a newline.
  679. The argument string may be any valid character string, such as the name of
  680. the program encountering the error.
  681.  
  682. .kp on
  683. :h4. printf(format, [, arg] . . .)
  684. :p.Declarations:
  685. :sl compact
  686. :li.char *format;
  687. :esl
  688. :p.:hp2.printf:ehp2.
  689. formats the values represented by the
  690. :hp2.arg:ehp2.
  691. arguments and prints them according to the format specified by
  692. :hp2.format.  format:ehp2.
  693. is a character string to be printed which optionally contains
  694. conversion specifications beginning with the character %.  Following the
  695. % character is a specification which describes how the corresponding
  696. argument is to be formatted.  There must be at least enough arguments
  697. to satisfy the requirements of the format specification.
  698. .kp off
  699.  
  700. :p.Each conversion specification consists of:
  701. :ul compact
  702. :li.the % character.
  703. :li. an optional minus sign ("-") which
  704. specifies left adjustment of the converted
  705. value within the indicated field.
  706. :li.an optional digit string specifying
  707. field width.  If the converted value has
  708. characters than the field width, the
  709. field is padded to the specified width.
  710. Padding is on the left unless a minus
  711. sign was used to specify left adjustment
  712. (and therefore right padding).  Padding
  713. is with blanks unless the field width
  714. began with a zero digit, in which case
  715. zero-padding is done instead.
  716. :li.an optional period (".") which serves
  717. to separate the field width from the
  718. next digit string.
  719. :li.an optional digit string specifying the
  720. maximum number of characters to be
  721. printed from a string (s-format only).
  722. :li.a character indicating the type of conversion to be performed.
  723. :eul
  724. :p.A field width or maximum string
  725. width value may be replaced with "*" (instead
  726. of the digit string).  This indicates
  727. that the next argument is to be interpreted
  728. as the integer field width or maximum string width.
  729. :p.The characters which may be
  730. used for specifying the type of conversion are:
  731. :dl compact
  732. :dt.c
  733. :dd.The character value of the argument is printed.
  734. :dt.d
  735. :dd.The signed integer value of the
  736. argument is printed (-32768 to 32767).
  737. :dt.o
  738. :dd.The unsigned octal integer value
  739. of the argument is printed (0 to 177777).
  740. :dt.s
  741. :dd.The character string addressed by the argument is printed.
  742. :dt.u
  743. :dd.The unsigned integer value of the argument is printed (0 to 65535).
  744. :dt.x
  745. :dd.The unsigned hexadecimal integer value of the argument is printed
  746. (0 to FFFF).
  747. :dt.%
  748. :dd."%" is printed.
  749. :edl
  750. :p.In no case does a small field width value
  751. cause truncation of a field; padding
  752. takes place only if the specified field
  753. width exceeds the actual width.
  754.  
  755. .kp on
  756. :h4. putc(c, stream)
  757. :p.Declarations:
  758. :sl compact
  759. :li.char c;
  760. :li.FILE *stream;
  761. :esl
  762. :p.:hp2.putc:ehp2.
  763. is a macro defining a synonym for the function
  764. :hp2.fputc:ehp2..
  765.  
  766. .kp on
  767. :h4. putchar(c)
  768. :p.Declarations:
  769. :sl compact
  770. :li.char c;
  771. :esl
  772. :p.:hp2.putchar:ehp2.
  773. appends the character
  774. :hp2.c:ehp2.
  775. to stdout.  The value of c is returned unless there is an error, in which case
  776. EOF is returned.
  777.  
  778. .kp on
  779. :h4. puts(s)
  780. :p.Declarations:
  781. :sl compact
  782. :li.char *s;
  783. :esl
  784. :p.:hp2.puts:ehp2.
  785. copies the null-terminated string
  786. addressed by
  787. :hp2.s:ehp2.
  788. to stdout and (unlike
  789. :hp2.fputs:ehp2.)
  790. appends a newline character.
  791.  
  792. .kp on
  793. :h4. putw(w, stream)
  794. :p.Declarations:
  795. :sl compact
  796. :li.int w;
  797. :li.FILE *stream;
  798. :esl
  799. :p.:hp2.putw:ehp2.
  800. appends the integer word
  801. :hp2.w:ehp2.
  802. to
  803. :hp2.stream:ehp2..
  804. The value of w is returned unless there is an error, in which case
  805. EOF is returned.  However, since EOF is a valid integer,
  806. :hp2.ferror:ehp2.
  807. should be used to test for errors.
  808.  
  809. .kp on
  810. :h4. rewind(stream)
  811. :p.Declarations:
  812. :sl compact
  813. :li.FILE *stream;
  814. :esl
  815. :p.:hp2.rewind:ehp2.
  816. positions
  817. :hp2.stream:ehp2.
  818. at the beginning of the file.
  819.  
  820. .kp on
  821. :h4. rindex(s, c)
  822. :p.Declarations:
  823. :sl compact
  824. :li.char *s, c;
  825. :esl
  826. :p.:hp2.rindex:ehp2.
  827. returns a pointer to the last occurrence of character
  828. :hp2.c:ehp2.
  829. in the null-terminated string addressed by
  830. :hp2.s:ehp2.,
  831. or zero if c does not occur in the string.
  832.  
  833. .kp on
  834. :h4. sprintf(s, format, [, arg] . . . )
  835. :p.Declarations:
  836. :sl compact
  837. :li.char *s, *format;
  838. :esl
  839. :p.:hp2.sprintf:ehp2.
  840. formats the values represented by the
  841. :hp2.arg:ehp2.
  842. arguments and places them in the string addressed by
  843. :hp2.s:ehp2.
  844. according to the format specified by
  845. :hp2.format:ehp2..
  846. format is a character string to be printed which optionally contains
  847. conversion specifications beginning with the character %.  Following the
  848. % character is a specification which describes how the corresponding
  849. argument is to be formatted.  There must be at least enough arguments
  850. to satisfy the requirements of the format specification.
  851. .kp off
  852.  
  853. Each conversion specification consists of:
  854. :ul compact
  855. :li.the % character.
  856. :li.an optional minus sign ("-") which specifies left
  857. adjustment of the converted value within the indicated
  858. field.
  859. :li.an optional digit string specifying field width.  If the
  860. converted value has characters than the field width, the
  861. field is padded to the specified width.  Padding is on the
  862. left unless a minus sign was used to specify left adjustment
  863. (and therefore right padding).  Padding is with blanks
  864. unless the field width began with a zero digit, in which
  865. case zero-padding is done instead.
  866. :li.an optional period (".") which serves to separate the
  867. field width from the next digit string.
  868. :li.an optional digit string specifying the maximum number of
  869. characters to be printed from a string (s-format only).
  870. :li.a character indicating the type of conversion to be performed.
  871. :eul
  872. :p.A field width or maximum string width value may be replaced
  873. with "*" (instead of the digit string).  This indicates that
  874. the next argument is to be interpreted as the integer field
  875. width or maximum string width.
  876.  
  877. :p.The characters which may be used for specifying the type of
  878. conversion are:
  879. :dl compact
  880. :dt.c
  881. :dd.The character value of the argument is printed.
  882. :dt.d
  883. :dd.The signed integer value of the argument
  884. is printed (-32768 to 32767).
  885. :dt.o
  886. :dd.The unsigned octal integer value of the
  887. argument is printed (0 to 177777).
  888. :dt.s
  889. :dd.The character string addressed by the argument is printed.
  890. :dt.u
  891. :dd.The unsigned integer value of the argument is printed (0 to 65535).
  892. :dt.x
  893. :dd.The unsigned hexadecimal integer value of the argument is printed
  894. (0 to FFFF).
  895. :dt.%
  896. :dd."%" is printed.
  897. :edl
  898. :p.In no case does a small field width value cause truncation of
  899. a field; padding takes place only if the specified field
  900. width exceeds the actual width.
  901.  
  902. .kp on
  903. :h4. strcat(s1, s2)
  904. :p.Declarations:
  905. :sl compact
  906. :li.char *s1, *s1;
  907. :esl
  908. :p.:hp2.strcat:ehp2.
  909. appends a copy of the null-terminated string addressed by
  910. :hp2.s2:ehp2.
  911. to the end of the null-terminated string addressed by
  912. :hp2.s1:ehp2..
  913. The function returns s1.
  914.  
  915. .kp on
  916. :h4. strcmp(s1, s2)
  917. :p.Declarations:
  918. :sl compact
  919. :li.char *s1, *s2;
  920. :esl
  921. :p.:hp2.strcmp:ehp2.
  922. compares the null-terminated strings addressed
  923. by the two arguments, and returns a result which
  924. is greater than, equal to, or less than zero, if string
  925. :hp2.s1:ehp2.
  926. is greater than, equal to, or less than string
  927. :hp2.s2:ehp2.,
  928. respectively.
  929.  
  930. .kp on
  931. :h4. strcpy(s1, s2)
  932. :p.Declarations:
  933. :sl compact
  934. :li.char *s1, *s2;
  935. :esl
  936. :p.:hp2.strcpy:ehp2.
  937. copies the null-terminated string addressed by
  938. :hp2.s2:ehp2.
  939. to the location addressed by
  940. :hp2.s1:ehp2..
  941. The function returns the pointer s1.
  942.  
  943. .kp on
  944. :h4. strlen(s)
  945. :p.Declarations:
  946. :sl compact
  947. :li.char *s;
  948. :esl
  949. :p.:hp2.strlen:ehp2.
  950. returns the length of the null-terminated string addressed by
  951. :hp2.s:ehp2..
  952.  
  953. .kp on
  954. :h4. strncat(s1, s2, n)
  955. :p.Declarations:
  956. :sl compact
  957. :li.char *s1, *s1;
  958. :esl
  959. :p.:hp2.strncat:ehp2.
  960. appends a copy of the null-terminated string addressed by
  961. :hp2.s2:ehp2.
  962. to the end of the null-terminated string addressed by
  963. :hp2.s1.  At most:ehp2.,
  964. :hp2.n:ehp2.
  965. characters are appended.
  966. The function returns s1.
  967.  
  968. .kp on
  969. :h4. strncmp(s1, s2, n)
  970. :p.Declarations:
  971. :sl compact
  972. :li.char *s1, *s2;
  973. :esl
  974. :p.:hp2.strncmp:ehp2.
  975. compares the null-terminated strings addressed
  976. by the two arguments, and returns a result which
  977. is greater than, equal to, or less than zero, if string
  978. :hp2.s1:ehp2.
  979. is greater than, equal to, or less than string
  980. :hp2.s2:ehp2.,
  981. respectively.  At most,
  982. :hp2.n:ehp2.
  983. characters are compared.
  984.  
  985. .kp on
  986. :h4. strncpy(s1, s2, n)
  987. :p.Declarations:
  988. :sl compact
  989. :li.char *s1, *s2;
  990. :esl
  991. :p.:hp2.strncpy:ehp2.
  992. copies the null-terminated string addressed by
  993. :hp2.s2:ehp2.
  994. to the location addressed by
  995. :hp2.s1:ehp2..
  996. Exactly
  997. :hp2.n:ehp2.
  998. characters are copied, with the string being truncated or null padded as
  999. necessary.  Note that if the length of the string is greater than or equal
  1000. to n, the resulting string will not be null terminated.
  1001. The function returns the pointer s1.
  1002.  
  1003. .kp on
  1004. :h4. swab(from, to, nbytes)
  1005. :p.Declarations:
  1006. :sl compact
  1007. :li.char *from, *to;
  1008. :li.int nbytes;
  1009. :esl
  1010. :p.:hp2.swab:ehp2.
  1011. copies
  1012. :hp2.nbytes:ehp2.
  1013. bytes from the location addressed by
  1014. :hp2.from:ehp2.
  1015. to the location addressed by
  1016. :hp2.to:ehp2.,
  1017. exchanging adjacent odd and even bytes.  nbytes should be even.
  1018.  
  1019. .kp on
  1020. :h4. sys_errlist
  1021. :p.Declarations:
  1022. :sl compact
  1023. :esl
  1024. :p.:hp2.sys_errlist:ehp2.
  1025. is the external name of a table of error messages corresponding to the values
  1026. in errno.h.  sys_errlist is a vector of integers, each of which can be cast
  1027. into a character pointer and used to address a null-terminated string containing
  1028. the corresponding error message.
  1029. :hp2.sys_nerr:ehp2.
  1030. is the external name of an integer value specifying the number of entries in
  1031. sys_errlist.
  1032.  
  1033. .kp on
  1034. :h4. sys_nerr
  1035. :p.Declarations:
  1036. :sl compact
  1037. :esl
  1038. :p.:hp2.sys_nerr:ehp2.
  1039. is the external name of the integer value specifying the number of entries in
  1040. sys_errlist.
  1041.  
  1042. .kp on
  1043. :h4. tolower(c)
  1044. :p.Declarations:
  1045. :sl compact
  1046. :li.char c;
  1047. :esl
  1048. :p.:hp2.tolower:ehp2.
  1049. returns the value the character
  1050. :hp2.c:ehp2.,
  1051. converted to lower-case if the original character was an upper-case alphabetic.
  1052. The standard ASCII character set is assumed.
  1053.  
  1054. .kp on
  1055. :h4. toupper(c)
  1056. :p.Declarations:
  1057. :sl compact
  1058. :li.char c;
  1059. :esl
  1060. :p.:hp2.toupper:ehp2.
  1061. returns the value the character
  1062. :hp2.c:ehp2.,
  1063. converted to upper-case if the original character was a lower-case alphabetic.
  1064. The standard ASCII character set is assumed.
  1065.  
  1066. .kp on
  1067. :h4. traceback(stream)
  1068. :p.Declarations:
  1069. :sl compact
  1070. :li.FILE *stream;
  1071. :esl
  1072. :p.:hp2.traceback:ehp2.
  1073. produces a debug display of stack frame addresses and return addresses for the
  1074. currently executing program.  This can be used (in conjunction with a LINK MAP
  1075. and other dumps) to determine the current state of the program as well as its
  1076. call history.
  1077.  
  1078. .kp on
  1079. :h4. ungetc(c, stream)
  1080. :p.Declarations:
  1081. :sl compact
  1082. :li.char c;
  1083. :li.FILE *stream;
  1084. :esl
  1085. :p.:hp2.ungetc:ehp2.
  1086. pushes character
  1087. :hp2.c:ehp2.,
  1088. back on
  1089. :hp2.stream:ehp2..
  1090. The pushed character will be returned by the next call to
  1091. :hp2.fgetc:ehp2.
  1092. for
  1093. :hp2.stream.  Only one character may be pushed back:ehp2..
  1094. The function returns the character c, unless an error condition is detected,
  1095. in which case EOF is returned.
  1096. fseek2 erases the pushed character.
  1097.  
  1098. .kp on
  1099. :h4. _close(fildes)
  1100. :p.Declarations:
  1101. :sl compact
  1102. :li.int fildes;
  1103. :esl
  1104. :p.:hp2._close:ehp2.
  1105. closes the file identified by
  1106. :hp2.fildes:ehp2..
  1107. All files are closed automatically upon
  1108. :hp2.exit:ehp2.
  1109. (except in certain error cases) but the explicit use of
  1110. :hp2._close:ehp2.
  1111. may be necessary if many files are used by a program, since there is a limit to
  1112. the number of simultaneously open files.
  1113.  
  1114. .kp on
  1115. :h4. _create(name, mode)
  1116. :p.Declarations:
  1117. :sl compact
  1118. :li.char *name;
  1119. :li.int mode;
  1120. :esl
  1121. :p.:hp2._create:ehp2.
  1122. creates a new file or prepares to rewrite an existing file with the name
  1123. specified by the string addressed by
  1124. :hp2.name.  mode:ehp2.
  1125. specifies the attributes given to the file if a new one is created.  mode is
  1126. bit significant, with 0x02 specifying "system", and 0x04 specifying "hidden".
  1127.  
  1128. .kp on
  1129. :h4. _doschar(ch)
  1130. :p.Declarations:
  1131. :sl compact
  1132. :li.char ch;
  1133. :esl
  1134. :p.:hp2._doschar:ehp2.
  1135. determines if character
  1136. :hp2.ch:ehp2.
  1137. is a legal DOS filename character (DOS 2.0 rules).  Legal characters are
  1138. "a"-"z", "A"-"Z", "0"-"9", and "$&#@!%'()-{}_^~`".
  1139.  
  1140. .kp on
  1141. :h4. _dosdate(year, month, day)
  1142. :p.Declarations:
  1143. :sl compact
  1144. :li.int *year, *month, *day;
  1145. :esl
  1146. :p.:hp2._dosdate:ehp2.
  1147. returns the current date (as supplied by DOS).  The year is returned in the
  1148. location addressed by
  1149. :hp2.year:ehp2.,
  1150. the month is returned in the location addressed by
  1151. :hp2.month:ehp2.,
  1152. and the day is returned in the location addressed by
  1153. :hp2.day:ehp2..
  1154.  
  1155. .kp on
  1156. :h4. _dosfcall(function, dreg)
  1157. :p.Declarations:
  1158. :sl compact
  1159. :li.#include <doscall.h>
  1160. :li.int function, dreg;
  1161. :esl
  1162. :p.:hp2._dosfcall:ehp2.
  1163. performs an INT 21H function call with
  1164. :hp2.function:ehp2.
  1165. as the function code, and
  1166. :hp2.dreg:ehp2.
  1167. as the DX register value.  The contents of AL are returned (signed extended).
  1168.  
  1169. .kp on
  1170. :h4. _dosfxcall(function, dreg, cin, cout)
  1171. :p.Declarations:
  1172. :sl compact
  1173. :li.#include <doscall.h>
  1174. :li.int function, dreg, cin, *cout;
  1175. :esl
  1176. :p.:hp2._dosfxcall:ehp2.
  1177. performs an INT 21H function call with
  1178. :hp2.function:ehp2.
  1179. as the function code,
  1180. :hp2.dreg:ehp2.
  1181. as the DX register value, and
  1182. :hp2.cin:ehp2.
  1183. as the CX register value.
  1184. The contents of AL are returned (signed extended) as the value of the function,
  1185. and the contents of CX are returned in the location addressed by pointer
  1186. :hp2.cout:ehp2..
  1187.  
  1188. .kp on
  1189. :h4. _dostime(hours, minutes, seconds, hundredths)
  1190. :p.Declarations:
  1191. :sl compact
  1192. :li.int *hours, *minutes, *seconds, *hundredths;
  1193. :esl
  1194. :p.:hp2._dostime:ehp2.
  1195. returns the current time (as supplied by DOS).  The hour is returned in the
  1196. location addressed by
  1197. :hp2.hours:ehp2.,
  1198. the minute is returned in the location addressed by
  1199. :hp2.minutes:ehp2.,
  1200. and the second is returned in the location addressed by
  1201. :hp2.seconds:ehp2..
  1202. The location addressed by
  1203. :hp2.hundredths:ehp2.
  1204. contains the fraction of a second in units of 1/100th of a second.
  1205.  
  1206. .kp on
  1207. :h4. _exit(status)
  1208. :p.Declarations:
  1209. :sl compact
  1210. :li.int status;
  1211. :esl
  1212. :p.:hp2._exit:ehp2.
  1213. terminates execution of the program and returns to DOS.
  1214. :hp2._exit:ehp2. differs from :hp2.exit:ehp2. in that it does not
  1215. close open files before returning to DOS.  Neither function sets the
  1216. DOS 2.0 return code.
  1217.  
  1218. .kp on
  1219. :h4. _ioctl(fildes, request, argp)
  1220. :p.Declarations:
  1221. :sl compact
  1222. :li.#include <sgtty.h>
  1223. :li.int fildes, request;
  1224. :li.char *argp;
  1225. :esl
  1226. :p.:hp2._ioctl:ehp2.
  1227. changes the mode of operation of the device or file specified by
  1228. :hp2.fildes:ehp2..
  1229. The implemented values for
  1230. :hp2.request:ehp2.
  1231. are:
  1232. :dl compact
  1233. :dt.TIOCSETP:dd.set parameters
  1234. :dt.TIOCGETP:dd.get parameters
  1235. :edl
  1236. :p.:hp2.argp:ehp2.
  1237. addresses the 6-character structure defined by sgtty.h.  The 5th byte, SG_FLGS,
  1238. contains the only significant attributes.  It is defined as follows (octal):
  1239. :dl compact
  1240. :dt.EVENP  :dd.200  Even parity allowed on input.
  1241. :dt.ODDP   :dd.100  Odd parity allowed on input.
  1242. :dt.RAW    :dd.040  Raw mode:
  1243. Wake up on all characters & return control characters.
  1244. :dt.CRMOD  :dd.020  Map CR/LF to NL and back; echo LF or CR as CR-LF.
  1245. :dt.ECHO   :dd.010  Echo typed characters.
  1246. :dt.LCASE  :dd.004  Map upper case to lower case.
  1247. :dt.CBREAK :dd.002  Return each character as soon as typed.
  1248. :edl
  1249. :p.The modes which can be affected control such things as
  1250. buffering, echoing, etc.  One important attribute which can be
  1251. controlled with _ioctl is the mapping of CR/LF to NL and back
  1252. for C-DOS compatibility.
  1253.  
  1254. .kp on
  1255. :h4. _isatty(fildes)
  1256. :p.Declarations:
  1257. :sl compact
  1258. :li.int fildes;
  1259. :esl
  1260. :p.:hp2._isatty:ehp2.
  1261. returns a non-zero value if the file described by
  1262. :hp2.fildes:ehp2.
  1263. is a terminal device (or printer), zero otherwise.
  1264.  
  1265. .kp on
  1266. :h4. _open(name, mode)
  1267. :p.Declarations:
  1268. :sl compact
  1269. :li.char *name;
  1270. :li.int mode;
  1271. :esl
  1272. :p.:hp2._open:ehp2.
  1273. opens the file with the name addressed by
  1274. :hp2.name.  mode:ehp2.
  1275. determines whether the file is opened for reading (mode == 0), writing (mode ==
  1276. 1), or reading and writing (mode == 2).  The file is positioned at the beginning
  1277. of the file.
  1278.  
  1279. .kp on
  1280. :h4. _read(fildes, buffer, nbytes)
  1281. :p.Declarations:
  1282. :sl compact
  1283. :li.int fildes, nbytes;
  1284. :li.char *buffer;
  1285. :esl
  1286. :p.:hp2._read:ehp2.
  1287. reads up to the next
  1288. :hp2.nbytes:ehp2.
  1289. of data from the file selected by
  1290. :hp2.fildes:ehp2.
  1291. and places them in the location defined by
  1292. :hp2.buffer:ehp2..
  1293. Fewer than nbytes may be read, if end-of-file is encountered or if the file
  1294. is a device such as a terminal.  The number of bytes read is returned.  If
  1295. nbytes is zero, then end-of-file has been reached and there are no bytes to
  1296. read.
  1297.  
  1298. .kp on
  1299. :h4. _seek(fildes, offset, whence)
  1300. :p.Declarations:
  1301. :sl compact
  1302. :li.int fildes, offset, whence;
  1303. :esl
  1304. :p.:hp2._seek:ehp2.
  1305. causes the file identified by
  1306. :hp2.fildes:ehp2.
  1307. to be positioned at the location specified by
  1308. :hp2.offset:ehp2.
  1309. and
  1310. :hp2.whence:ehp2..
  1311. The returned value is the resulting location.  The result of seeking beyond the
  1312. end of the file is undefined.  The values of whence work as follows:
  1313.  
  1314. :dl compact
  1315. :dt.0  :dd.The pointer is set to offset
  1316. :dt.1  :dd.The pointer is set to the current location plus offset
  1317. :dt.2  :dd.The pointer is set to the size of the file plus offset
  1318. :dt.3  :dd.The pointer is set to offset * 512
  1319. :dt.4  :dd.The pointer is set to the current location plus offset * 512
  1320. :dt.5  :dd.The pointer is set to the size of the file plus offset * 512
  1321. :edl
  1322. :p.The whence values of 3, 4, and 5 are necessary since offset can
  1323. only take values of +/- 32k, and DOS files can be larger than
  1324. this.  Using two invocations of _seek, files of up to 16 MB can
  1325. be positioned to any arbitrary byte.  First use a whence of 3,
  1326. 4, or 5, to position within 512 bytes of the desired location,
  1327. then use a whence of 1 to position to the exact byte.
  1328.  
  1329. .kp on
  1330. :h4. _write(fildes, buffer, nbytes)
  1331. :p.Declarations:
  1332. :sl compact
  1333. :li.int fildes, nbytes;
  1334. :li.char *buffer;
  1335. :esl
  1336. :p.:hp2._write:ehp2.
  1337. takes the next
  1338. :hp2.nbytes:ehp2.
  1339. of data from the location defined by
  1340. :hp2.buffer:ehp2.,
  1341. and writes them in the file defined by
  1342. :hp2.fildes:ehp2..
  1343. The number of characters actually written is returned, and an error was
  1344. encountered if this value is not equal to nbytes.
  1345. .kp off
  1346. :egdoc
  1347.