home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_C / RECIO110.ZIP / SPEC.TXT < prev    next >
Text File  |  1994-03-28  |  51KB  |  1,542 lines
  1.     Title: SPECIFICATION OF C LANGUAGE RECIO LIBRARY
  2. Copyright: (C) 1994 William Pierpoint
  3.   Version: 1.10
  4.      Date: March 28, 1994
  5.  
  6.  
  7.  
  8. 1.0 RECORD INPUT/OUTPUT <recio.h>
  9.  
  10.  
  11. 1.1 Introduction
  12.  
  13. The header <recio.h> declares one type, several macros, and many functions
  14. for performing line oriented input.  
  15.  
  16. Note: This specification only covers input; output might be developed at a 
  17. later date if there is a perceived need.  Generally the functions available 
  18. in <stdio.h> are adequate for output.
  19.  
  20.  
  21. 1.1.1 Record Streams
  22.  
  23. Input is mapped into logical data record streams.  A record stream is an
  24. ordered sequence of characters composed into records, each record consisting
  25. of zero or more characters plus a terminating record delimiter character.
  26. The terminating record delimiter for a file is the newline character.
  27.  
  28. Each record consists of zero or more fields.  The record may be broken 
  29. into fields in two different ways: (1) character delimited and (2) column 
  30. delimited.  For character delimited fields, each field consists of zero or 
  31. more characters plus a terminating field delimiter character or, for the 
  32. last field in the record, the record delimiter character.  For column 
  33. delimited fields, each field consists of one or more characters delimited 
  34. by a single column position for fields consisting of one character, or by 
  35. beginning and ending column positions for fields consisting of one or more 
  36. characters.
  37.  
  38. Three types of fields are defined: (1) character, (2) text, and (3) 
  39. numeric.  A character field consists of a single character.  A text 
  40. field consists of a sequence of zero or more characters delimited at 
  41. each end by an optional text delimiter character.  A numeric field 
  42. consists of a sequence of one or more characters from the set of valid 
  43. characters for the number type (integral or floating point) and radix.
  44.  
  45.  
  46. 1.1.2 Type
  47.  
  48. The type is
  49.  
  50.     REC
  51.  
  52. which is an object type capable of recording all information needed to 
  53. control a record stream used for line oriented input, including its 
  54. file pointer, pointers to its associated record and field buffers, field 
  55. and text delimiting characters, an error indicator that records whether 
  56. an error has occurred, and an end-of-file indicator that records whether 
  57. the end of the file has been reached.
  58.  
  59.  
  60. 1.1.3 Macros
  61.  
  62. The macros are
  63.  
  64.     RECBUFSIZ
  65.     FLDBUFSIZ
  66.     
  67. which expand to integral constant expressions, which are the initial 
  68. sizes of the record buffer and the field buffer;
  69.     
  70.     RECFLDCH
  71.     RECTXTCH
  72.     
  73. which expand to integral constant expressions, which are the default 
  74. values of the characters used to separate the fields and delimit text 
  75. in a record and whose default value shall correspond to the value of
  76. the space character;
  77.  
  78.     ROPEN_MAX
  79.     
  80. which expands to an integral constant expression that is the maximum 
  81. number of files that can be open simultaneously;
  82.  
  83.     RECIN
  84.     
  85. which expands to an integral constant expression that is the context
  86. number for the recin record stream that gets it's input from the <stdio.h> 
  87. standard input stream stdin.
  88.  
  89.  
  90. 1.1.4 Expressions
  91.  
  92. The one expression is
  93.  
  94.     recin
  95.  
  96. which is of type "pointer to REC" that points to the REC object associated 
  97. with the <stdio.h> FILE object stdin (standard input stream).  The recin 
  98. record stream is always open and is included in the count of ROPEN_MAX.
  99.  
  100.  
  101. 1.2 Record Access Functions
  102.  
  103. 1.2.1 The rclose Function
  104.  
  105. Synopsis
  106.  
  107.      #include <recio.h>
  108.      int rclose(REC *rp);
  109.  
  110. Description
  111.  
  112. The rclose function causes the record stream pointed to by rp and the 
  113. associated file to be closed.  Any unread data is discarded.  The record 
  114. stream is disassociated from the file.  If associated buffers were 
  115. automatically allocated, they are deallocated.
  116.  
  117. If an error occurs, the error indicator for the record stream is set, 
  118. the callback error function is called (if registered), and the rclose 
  119. function returns EOF.
  120.  
  121. Returns
  122.  
  123. The rclose function returns zero if the record stream is successfully 
  124. closed, or EOF if any errors were detected.
  125.  
  126.  
  127. 1.2.2 The rcloseall Function
  128.  
  129. Synopsis
  130.  
  131.      #include <recio.h>
  132.      int rcloseall(void);
  133.  
  134. Description
  135.  
  136. The rcloseall function causes all the open record streams, and all the
  137. files associated with the open record streams, to be closed.  Any unread
  138. data is discarded.  Each record stream is disassociated from its file.
  139. If associated buffers were automatically allocated, they are deallocated.
  140.  
  141. If an error occurs, the rcloseall function returns EOF.
  142.  
  143. Returns
  144.  
  145. The rcloseall function returns the number of record streams successfully 
  146. closed, or EOF if any errors were detected.
  147.  
  148.  
  149. 1.2.3 The ropen Function
  150.  
  151. Synopsis
  152.  
  153.      #include <recio.h>
  154.      REC *ropen(const char *filename, const char *mode);
  155.  
  156. Description
  157.  
  158. The ropen function opens the file whose name is the string pointed to by
  159. filename, and associates a record stream with it.  The argument mode 
  160. points to a string containing:
  161.  
  162.        "r" - open text file for input
  163.  
  164. Note: This specification does not cover output modes at this time.
  165.  
  166. When successfully opened, the error and end-of-file indicators for the 
  167. record stream are clear.  If an error occurs, errno is set to one of the 
  168. error reporting macros as defined in <errno.h>, the callback error function 
  169. is called (except when the file associated with filename is not able to be 
  170. opened), and a null pointer is returned.
  171.  
  172. Returns
  173.  
  174. The ropen function returns a pointer to the object controlling the record 
  175. stream.  If the open operation fails, ropen returns a null pointer.
  176.  
  177.  
  178. 1.2.4 The rsetfldsiz Function
  179.  
  180. Synopsis
  181.  
  182.      #include <recio.h>
  183.      int rsetfldsiz(REC *rp, size_t fldsize);
  184.  
  185. Description
  186.  
  187. The rsetfldsiz function reallocates the field buffer associated with the 
  188. record stream pointed to by rp to the new size of fldsize.
  189.  
  190. The rsetfldsiz function may be used only after the record stream pointed 
  191. to by rp has been opened and before any data is read into the record 
  192. buffer.  Data is read into the record buffer by the function rgetrec,
  193. or by calling a function that either skips a field or gets data from a
  194. field.  If rsetfldsiz is not used, the initial size of the field buffer 
  195. is set by the value of the macro FLDBUFSIZ.
  196.  
  197. If an error occurs, the error indicator for the record stream is set, 
  198. the callback error function is called (if registered), and the rsetfldsiz 
  199. function returns EOF.
  200.  
  201. Returns
  202.  
  203. The rsetfldsiz function returns zero if the field buffer is successfully 
  204. reallocated, or EOF if any errors were detected.
  205.  
  206.  
  207. 1.2.5 The rsetrecsiz Function
  208.  
  209. Synopsis
  210.  
  211.      #include <recio.h>
  212.      int rsetrecsiz(REC *rp, size_t recsize);
  213.  
  214. Description
  215.  
  216. The rsetrecsiz function reallocates the record buffer associated with the 
  217. record stream pointed to by rp to the new size of recsize.
  218.  
  219. The rsetrecsiz function may be used only after the record stream pointed 
  220. to by rp has been opened and before any data is read into the record 
  221. buffer.  Data is read into the record buffer by the function rgetrec,
  222. or by calling a function that either skips a field or gets data from a
  223. field.  If rsetrecsiz is not used, the initial size of the field buffer 
  224. is set by the value of the macro RECBUFSIZ.
  225.  
  226. If an error occurs, the error indicator for the record stream is set, 
  227. the callback error function is called (if registered), and the rsetrecsiz 
  228. function returns EOF.
  229.  
  230. Returns
  231.  
  232. The rsetrecsiz function returns zero if the record buffer is successfully 
  233. reallocated, or EOF if any errors were detected.
  234.  
  235.  
  236. 1.3 Character Delimited Field Input Functions
  237.  
  238. 1.3.1 The rbgeti Function
  239.  
  240. Synopsis
  241.  
  242.      #include <recio.h>
  243.      int rbgeti(REC *rp, int base);
  244.  
  245. Description
  246.  
  247. The rbgeti function reads a field consisting of one integral number 
  248. represented by the radix determined by the value of base from the input 
  249. record stream pointed to by rp.  Any leading or trailing white space 
  250. in the field is ignored.
  251.  
  252. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  253. base is zero, the expected form of the integral number is described by
  254. section 3.1.3.2 of ANSI X3.159-1989.
  255.  
  256. If an error occurs, the error indicator for the record stream is set, 
  257. errno is set to one of the error reporting macros as defined in <errno.h>, 
  258. the callback error function is called (if registered), and the rbgeti 
  259. function returns zero.
  260.  
  261. Returns
  262.  
  263. The rbgeti function returns a signed integer from the input record 
  264. stream pointed to by rp.  If an attempt is made to read beyond the 
  265. end-of-record, if the field is empty, or if there is an illegal character 
  266. in the field, the error indicator for the record stream is set, and rbgeti 
  267. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  268. set), rbgeti returns zero.  If a previous error has occurred on the record 
  269. stream that has not been cleared (error indicator set), rbgeti returns zero.  
  270.  
  271.  
  272. 1.3.2 The rbgetl Function
  273.  
  274. Synopsis
  275.  
  276.      #include <recio.h>
  277.      long rbgetl(REC *rp, int base);
  278.  
  279. Description
  280.  
  281. The rbgetl function reads a field consisting of one integral number 
  282. represented by the radix determined by the value of base from the input 
  283. record stream pointed to by rp.  Any leading or trailing white space 
  284. in the field is ignored.
  285.  
  286. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  287. base is zero, the expected form of the integral number is described by
  288. section 3.1.3.2 of ANSI X3.159-1989.
  289.  
  290. If an error occurs, the error indicator for the record stream is set, 
  291. errno is set to one of the error reporting macros as defined in <errno.h>, 
  292. the callback error function is called (if registered), and the rbgetl 
  293. function returns zero (0L).
  294.  
  295. Returns
  296.  
  297. The rbgetl function returns a signed long from the input record stream 
  298. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  299. if the field is empty, or if there is an illegal character in the field, 
  300. the error indicator for the record stream is set, and rbgetl returns zero 
  301. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  302. rbgetl returns zero (0L).  If a previous error has occurred on the record 
  303. stream that has not been cleared (error indicator set), rbgetl returns 
  304. zero (0L).  
  305.  
  306.  
  307. 1.3.3 The rbgetui Function
  308.  
  309. Synopsis
  310.  
  311.      #include <recio.h>
  312.      unsigned int rbgetui(REC *rp, int base);
  313.  
  314. Description
  315.  
  316. The rbgetui function reads a field consisting of one non-negative integral 
  317. number represented by the radix determined by the value of base from the 
  318. input record stream pointed to by rp.  Any leading or trailing white space 
  319. in the field is ignored.
  320.  
  321. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  322. base is zero, the expected form of the integral number is described by
  323. section 3.1.3.2 of ANSI X3.159-1989.
  324.  
  325. If an error occurs, the error indicator for the record stream is set, 
  326. errno is set to one of the error reporting macros as defined in <errno.h>, 
  327. the callback error function is called (if registered), and the rbgetui 
  328. function returns zero.
  329.  
  330. Returns
  331.  
  332. The rbgetui function returns an unsigned integer from the input record 
  333. stream pointed to by rp.  If an attempt is made to read beyond the 
  334. end-of-record, if the field is empty, or if there is an illegal character 
  335. in the field, the error indicator for the record stream is set, and rbgetui 
  336. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  337. set), rbgetui returns zero.  If a previous error has occurred on the record 
  338. stream that has not been cleared (error indicator set), rbgetui returns zero.  
  339.  
  340.  
  341. 1.3.4 The rbgetul Function
  342.  
  343. Synopsis
  344.  
  345.      #include <recio.h>
  346.      unsigned long rbgetul(REC *rp, int base);
  347.  
  348. Description
  349.  
  350. The rbgetul function reads a field consisting of one non-negative integral 
  351. number represented by the radix determined by the value of base from the 
  352. input record stream pointed to by rp.  Any leading or trailing white space 
  353. in the field is ignored.
  354.  
  355. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  356. base is zero, the expected form of the integral number is described by
  357. section 3.1.3.2 of ANSI X3.159-1989.
  358.  
  359. If an error occurs, the error indicator for the record stream is set, 
  360. errno is set to one of the error reporting macros as defined in <errno.h>, 
  361. the callback error function is called (if registered), and the rbgetul 
  362. function returns zero (0L).
  363.  
  364. Returns
  365.  
  366. The rbgetul function returns an unsigned long from the input record stream 
  367. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  368. if the field is empty, or if there is an illegal character in the field, 
  369. the error indicator for the record stream is set, and rbgetul returns zero 
  370. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  371. rbgetul returns zero (0L).  If a previous error has occurred on the record 
  372. stream that has not been cleared (error indicator set), rbgetul returns 
  373. zero (0L).  
  374.  
  375.  
  376. 1.3.5 The rgetc Function
  377.  
  378. Synopsis
  379.  
  380.      #include <recio.h>
  381.      int rgetc(REC *rp);
  382.  
  383. Description
  384.  
  385. The rgetc function reads a field consisting of one non-white space 
  386. character from the input record stream pointed to by rp.  Any leading 
  387. or trailing white space in the field is ignored.
  388.  
  389. If an error occurs, the error indicator for the record stream is set, 
  390. errno is set to one of the error reporting macros as defined in <errno.h>, 
  391. the callback error function is called (if registered), and the rgetc 
  392. function returns EOF.
  393.  
  394. Returns
  395.  
  396. The rgetc function returns a character from a single non-white
  397. space character field in the input record stream pointed to by rp.  
  398. If an attempt is made to read beyond the end-of-record, or if there
  399. is more than or less than one non-white character in the field, the 
  400. error indicator for the record stream is set, and rgetc returns EOF.  If the 
  401. record stream is at end-of-file (end-of-file indicator set), rgetc returns 
  402. EOF.  If a previous error has occurred on the record stream that has not been 
  403. cleared (error indicator set), rgetc returns EOF.  
  404.  
  405.  
  406. 1.3.6 The rgetd Function
  407.  
  408. Synopsis
  409.  
  410.      #include <recio.h>
  411.      double rgetd(REC *rp);
  412.  
  413. Description
  414.  
  415. The rgetd function reads a field consisting of one floating point
  416. number from the input record stream pointed to by rp.  Any leading 
  417. or trailing white space in the field is ignored.
  418.  
  419. If an error occurs, the error indicator for the record stream is set, 
  420. errno is set to one of the error reporting macros as defined in <errno.h>, 
  421. the callback error function is called (if registered), and the rgetd 
  422. function returns zero (0.0).
  423.  
  424. Returns
  425.  
  426. The rgetd function returns a double precision floating point number 
  427. from the input record stream pointed to by rp.  If an attempt is made 
  428. to read beyond the end-of-record, if the field is empty, or if there
  429. is an illegal character in the field, the error indicator for the 
  430. record stream is set, and rgetd returns zero (0.0).  If the record stream is 
  431. at end-of-file (end-of-file indicator set), rgetd returns zero (0.0).  If a 
  432. previous error has occurred on the record stream that has not been cleared 
  433. (error indicator set), rgetd returns zero (0.0).
  434.  
  435.  
  436. 1.3.7 The rgetf Function
  437.  
  438. Synopsis
  439.  
  440.      #include <recio.h>
  441.      float rgetf(REC *rp);
  442.  
  443. Description
  444.  
  445. The rgetf function reads a field consisting of one floating point
  446. number from the input record stream pointed to by rp.  Any leading 
  447. or trailing white space in the field is ignored.
  448.  
  449. If an error occurs, the error indicator for the record stream is set, 
  450. errno is set to one of the error reporting macros as defined in <errno.h>, 
  451. the callback error function is called (if registered), and the rgetf 
  452. function returns zero (0.0).
  453.  
  454. Returns
  455.  
  456. The rgetf function returns a single precision floating point number 
  457. from the input record stream pointed to by rp.  If an attempt is made 
  458. to read beyond the end-of-record, if the field is empty, or if there
  459. is an illegal character in the field, the error indicator for the 
  460. record stream is set, and rgetf returns zero (0.0).  If the record stream is 
  461. at end-of-file (end-of-file indicator set), rgetf returns zero (0.0).  If a 
  462. previous error has occurred on the record stream that has not been cleared 
  463. (error indicator set), rgetf returns zero (0.0).
  464.  
  465.  
  466. 1.3.8 The rgeti Function
  467.  
  468. Synopsis
  469.  
  470.      #include <recio.h>
  471.      int rgeti(REC *rp);
  472.  
  473. Description
  474.  
  475. The rgeti function reads a field consisting of one integral
  476. number from the input record stream pointed to by rp.  Any leading 
  477. or trailing white space in the field is ignored.
  478.  
  479. If an error occurs, the error indicator for the record stream is set, 
  480. errno is set to one of the error reporting macros as defined in <errno.h>, 
  481. the callback error function is called (if registered), and the rgeti 
  482. function returns zero.
  483.  
  484. Returns
  485.  
  486. The rgeti function returns a signed integer from the input record 
  487. stream pointed to by rp.  If an attempt is made to read beyond the 
  488. end-of-record, if the field is empty, or if there is an illegal character 
  489. in the field, the error indicator for the record stream is set, and rgeti 
  490. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  491. set), rgeti returns zero.  If a previous error has occurred on the record 
  492. stream that has not been cleared (error indicator set), rgeti returns zero.  
  493.  
  494.  
  495. 1.3.9 The rgetl Function
  496.  
  497. Synopsis
  498.  
  499.      #include <recio.h>
  500.      long rgetl(REC *rp);
  501.  
  502. Description
  503.  
  504. The rgetl function reads a field consisting of one integral number 
  505. from the input record stream pointed to by rp.  Any leading or trailing 
  506. white space in the field is ignored.
  507.  
  508. If an error occurs, the error indicator for the record stream is set, 
  509. errno is set to one of the error reporting macros as defined in <errno.h>, 
  510. the callback error function is called (if registered), and the rgetl 
  511. function returns zero (0L).
  512.  
  513. Returns
  514.  
  515. The rgetl function returns a signed long from the input record stream 
  516. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  517. if the field is empty, or if there is an illegal character in the field, 
  518. the error indicator for the record stream is set, and rgetl returns zero 
  519. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  520. rgetl returns zero (0L).  If a previous error has occurred on the record 
  521. stream that has not been cleared (error indicator set), rgetl returns zero 
  522. (0L).  
  523.  
  524.  
  525. 1.3.10 The rgets Function
  526.  
  527. Synopsis
  528.  
  529.      #include <recio.h>
  530.      char *rgets(REC *rp);
  531.  
  532. Description
  533.  
  534. The rgets function reads a field consisting of one text string from the 
  535. input record stream pointed to by rp.  Any leading white space before the 
  536. text delimiter and any trailing white space after the text delimiter in 
  537. the field is ignored.  The text delimiters are not returned as part of 
  538. the string.
  539.  
  540. If an error occurs, the error indicator for the record stream is set, 
  541. errno is set to one of the error reporting macros as defined in <errno.h>, 
  542. the callback error function is called (if registered), and the rgets 
  543. function returns a null pointer.
  544.  
  545. Returns
  546.  
  547. The rgets function returns a pointer to a character array from the 
  548. input record stream pointed to by rp.  If an attempt is made to read 
  549. beyond the end-of-record, the error indicator for the record stream is 
  550. set, and rgets returns a null pointer.  If the record stream is at end-of-file 
  551. (end-of-file indicator set), rgets returns a null pointer.  If a previous 
  552. error has occurred on the record stream that has not been cleared (error 
  553. indicator set), rgets returns a null pointer.
  554.  
  555.  
  556. 1.3.11 The rgetui Function
  557.  
  558. Synopsis
  559.  
  560.      #include <recio.h>
  561.      unsigned int rgetui(REC *rp);
  562.  
  563. Description
  564.  
  565. The rgetui function reads a field consisting of one non-negative 
  566. integral number from the input record stream pointed to by rp.  Any 
  567. leading or trailing white space in the field is ignored.
  568.  
  569. If an error occurs, the error indicator for the record stream is set, 
  570. errno is set to one of the error reporting macros as defined in <errno.h>, 
  571. the callback error function is called (if registered), and the rgetui 
  572. function returns zero.
  573.  
  574. Returns
  575.  
  576. The rgetui function returns an unsigned integer from the input record 
  577. stream pointed to by rp.  If an attempt is made to read beyond the 
  578. end-of-record, if the field is empty, or if there is an illegal character 
  579. in the field, the error indicator for the record stream is set, and rgetui 
  580. returns zero.  If the record stream is at end-of-file (end-of-file indicator 
  581. set), rgetui returns zero.  If a previous error has occurred on the record 
  582. stream that has not been cleared (error indicator set), rgetui returns zero.  
  583.  
  584.  
  585. 1.3.12 The rgetul Function
  586.  
  587. Synopsis
  588.  
  589.      #include <recio.h>
  590.      unsigned long rgetul(REC *rp);
  591.  
  592. Description
  593.  
  594. The rgetul function reads a field consisting of one non-negative 
  595. integral number from the input record stream pointed to by rp.  Any 
  596. leading or trailing white space in the field is ignored.
  597.  
  598. If an error occurs, the error indicator for the record stream is set, 
  599. errno is set to one of the error reporting macros as defined in <errno.h>, 
  600. the callback error function is called (if registered), and the rgetul 
  601. function returns zero (0L).
  602.  
  603. Returns
  604.  
  605. The rgetul function returns an unsigned long from the input record stream 
  606. pointed to by rp.  If an attempt is made to read beyond the end-of-record, 
  607. if the field is empty, or if there is an illegal character in the field, 
  608. the error indicator for the record stream is set, and rgetul returns zero 
  609. (0L).  If the record stream is at end-of-file (end-of-file indicator set), 
  610. rgetul returns zero (0L).  If a previous error has occurred on the record 
  611. stream that has not been cleared (error indicator set), rgetul returns zero 
  612. (0L).  
  613.  
  614.  
  615. 1.3.13 The rsetfldch Function
  616.  
  617. Synopsis
  618.  
  619.      #include <recio.h>
  620.      int rsetfldch(REC *rp, int ch);
  621.  
  622. Description
  623.  
  624. The rsetfldch function sets the field delimiter to the character ch
  625. for the record stream pointed to by rp.  If the character ch is the 
  626. space character ' ', then the field is delimited by any white-space, 
  627. and multiple contiguous white space characters are treated as a single 
  628. delimiter.  If the character ch is other than the space character, then 
  629. multiple contiguous field delimiters are treated as a series of empty
  630. fields.
  631.  
  632. If rsetfldch is not called, the field delimiter is set by the value of 
  633. the macro RECFLDCH.
  634.  
  635. If an error occurs, the error indicator for the record stream is set, 
  636. the callback error function is called (if registered), and the rsetfldch 
  637. function returns EOF.
  638.  
  639. Returns
  640.  
  641. The rsetfldch function returns zero if the field delimiter character was
  642. successfully set for the record stream, or EOF if any errors were detected.
  643.  
  644.  
  645. 1.3.14 The rsettxtch Function
  646.  
  647. Synopsis
  648.  
  649.      #include <recio.h>
  650.      int rsettxtch(REC *rp, int ch);
  651.  
  652. Description
  653.  
  654. The rsettxtch function sets the text delimiter to the character ch for 
  655. the record stream pointed to by rp.
  656.  
  657. If rsettxtch is not called, the text delimiter is set by the value of 
  658. the macro RECTXTCH.
  659.  
  660. If an error occurs, the error indicator for the record stream is set, 
  661. the callback error function is called (if registered), and the rsettxtch 
  662. function returns EOF.
  663.  
  664. Returns
  665.  
  666. The rsettxtch function returns zero if the text delimiter character was
  667. successfully set for the record stream, or EOF if any errors were detected.
  668.  
  669.  
  670. 1.3.15 The rskipfld Function
  671.  
  672. Synopsis
  673.  
  674.      #include <recio.h>
  675.      int rskipfld(REC *rp);
  676.  
  677. Description
  678.  
  679. The rskipfld function skips to the next field for the record stream
  680. pointed to by rp.
  681.  
  682. If an error occurs, the error indicator for the record stream is set, 
  683. the callback error function is called (if registered), and the rskipfld 
  684. function returns EOF.
  685.  
  686. Returns
  687.  
  688. The rskipfld function returns one if the field was successfully skipped, 
  689. zero if the field could not be skipped (end of record), or EOF if any 
  690. errors were detected.
  691.  
  692.  
  693. 1.3.16 The rskipnfld Function
  694.  
  695. Synopsis
  696.  
  697.      #include <recio.h>
  698.      int rskipnfld(REC *rp, size_t num);
  699.  
  700. Description
  701.  
  702. The rskipnfld function skips over num number of fields for the record
  703. stream pointed to by rp.
  704.  
  705. If an error occurs, the error indicator for the record stream is set, 
  706. the callback error function is called (if registered), and the rskipnfld 
  707. function returns EOF.
  708.  
  709. Returns
  710.  
  711. The rskipfld function returns the actual number of fields skipped, or EOF 
  712. if any errors were detected.
  713.  
  714.  
  715. 1.4 Column Delimited Field Input Functions
  716.  
  717. 1.4.1 The rcbgeti Function
  718.  
  719. Synopsis
  720.  
  721.      #include <recio.h>
  722.      int rcbgeti(REC *rp, size_t begcol, size_t endcol, int base);
  723.  
  724. Description
  725.  
  726. The rcbgeti function gets one integral number represented by the radix 
  727. determined by the value of base and contained inclusively from column 
  728. begcol to column endcol for the input record stream pointed to by rp.  
  729. Any leading or trailing white space in the field is ignored.
  730.  
  731. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  732. base is zero, the expected form of the integral number is described by
  733. section 3.1.3.2 of ANSI X3.159-1989.
  734.  
  735. If an error occurs, the error indicator for the record stream is set, 
  736. errno is set to one of the error reporting macros as defined in <errno.h>, 
  737. the callback error function is called (if registered), and the rgeti 
  738. function returns zero.
  739.  
  740. Returns
  741.  
  742. The rcbgeti function returns a signed integer from the input record stream 
  743. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  744. empty, or if there is an illegal character in the field, the error indicator 
  745. for the record stream is set, and rcbgeti returns zero.  If the record stream 
  746. is at end-of-file (end-of-file indicator set), rcbgeti returns zero.  If a 
  747. previous error has occurred on the record stream that has not been cleared 
  748. (error indicator set), rcbgeti returns zero.  
  749.  
  750.  
  751. 1.4.2 The rcbgetl Function
  752.  
  753. Synopsis
  754.  
  755.      #include <recio.h>
  756.      long rcbgetl(REC *rp, size_t begcol, size_t endcol, int base);
  757.  
  758. Description
  759.  
  760. The rcbgetl function gets one integral number represented by the radix 
  761. determined by the value of base and contained inclusively from column 
  762. begcol to column endcol for the input record stream pointed to by rp.  
  763. Any leading or trailing white space in the field is ignored.
  764.  
  765. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  766. base is zero, the expected form of the integral number is described by
  767. section 3.1.3.2 of ANSI X3.159-1989.
  768.  
  769. If an error occurs, the error indicator for the record stream is set, 
  770. errno is set to one of the error reporting macros as defined in <errno.h>, 
  771. the callback error function is called (if registered), and the rgetl 
  772. function returns zero (0L).
  773.  
  774. Returns
  775.  
  776. The rcbgetl function returns a signed long from the input record stream 
  777. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  778. empty, or if there is an illegal character in the field, the error indicator 
  779. for the record stream is set, and rcbgetl returns zero (0L).  If the record 
  780. stream is at end-of-file (end-of-file indicator set), rcbgetl returns zero 
  781. (0L).  If a previous error has occurred on the record stream that has not been 
  782. cleared (error indicator set), rcbgetl returns zero (0L).  
  783.  
  784.  
  785. 1.4.3 The rcbgetui Function
  786.  
  787. Synopsis
  788.  
  789.      #include <recio.h>
  790.      unsigned int rcbgetui(REC *rp, size_t begcol, size_t endcol, 
  791.           int base);
  792.  
  793. Description
  794.  
  795. The rcbgetui function gets one non-negative integral number represented 
  796. by the radix determined by the value of base and contained inclusively 
  797. from column begcol to column endcol for the input record stream pointed 
  798. to by rp.  Any leading or trailing white space in the field is ignored.
  799.  
  800. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  801. base is zero, the expected form of the integral number is described by
  802. section 3.1.3.2 of ANSI X3.159-1989.
  803.  
  804. If an error occurs, the error indicator for the record stream is set, 
  805. errno is set to one of the error reporting macros as defined in <errno.h>, 
  806. the callback error function is called (if registered), and the rgetui 
  807. function returns zero.
  808.  
  809. Returns
  810.  
  811. The rcbgetui function returns an unsigned integer from the input record 
  812. stream pointed to by rp.  If begcol is beyond the end-of-record, if the 
  813. field is empty, or if there is an illegal character in the field, the 
  814. error indicator for the record stream is set, and rcbgetui returns zero.  If 
  815. the record stream is at end-of-file (end-of-file indicator set), rcbgetui 
  816. returns zero.  If a previous error has occurred on the record stream that has 
  817. not been cleared (error indicator set), rcbgetui returns zero.  
  818.  
  819.  
  820. 1.4.4 The rcbgetul Function
  821.  
  822. Synopsis
  823.  
  824.      #include <recio.h>
  825.      unsigned long rcbgetul(REC *rp, size_t begcol, size_t endcol, 
  826.           int base);
  827.  
  828. Description
  829.  
  830. The rcbgetul function gets one non-negative integral number represented 
  831. by the radix determined by the value of base and contained inclusively 
  832. from column begcol to column endcol for the input record stream pointed 
  833. to by rp.  Any leading or trailing white space in the field is ignored.
  834.  
  835. Base may be zero or in the range of 2 to 36 inclusive.  If the value of
  836. base is zero, the expected form of the integral number is described by
  837. section 3.1.3.2 of ANSI X3.159-1989.
  838.  
  839. If an error occurs, the error indicator for the record stream is set, 
  840. errno is set to one of the error reporting macros as defined in <errno.h>, 
  841. the callback error function is called (if registered), and the rgetul 
  842. function returns zero (0L).
  843.  
  844. Returns
  845.  
  846. The rcbgetul function returns an unsigned long from the input record stream 
  847. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  848. empty, or if there is an illegal character in the field, the error indicator 
  849. for the record stream is set, and rcbgetul returns zero (0L).  If the record 
  850. stream is at end-of-file (end-of-file indicator set), rcbgetul returns zero 
  851. (0L).  If a previous error has occurred on the record stream that has not been 
  852. cleared (error indicator set), rcbgetul returns zero (0L).  
  853.  
  854.  
  855. 1.4.5 The rcgetc Function
  856.  
  857. Synopsis
  858.  
  859.      #include <recio.h>
  860.      int rcgetc(REC *rp, size_t col);
  861.  
  862. Description
  863.  
  864. The rcgetc function obtains from column position col the unsigned char
  865. converted to an int from the input record stream pointed to by rp.
  866.  
  867. If an error occurs, the error indicator for the record stream is set, 
  868. errno is set to one of the error reporting macros as defined in <errno.h>, 
  869. the callback error function is called (if registered), and the rcgetc 
  870. function returns EOF.
  871.  
  872. Returns
  873.  
  874. The rcgetc function returns a character from column position col from 
  875. the input record stream pointed to by rp.  If an attempt is made to read 
  876. beyond the end-of-record, the error indicator for the record stream is set, 
  877. and rcgetc returns EOF.  If the record stream is at end-of-file (end-of-file 
  878. indicator set), rcgetc returns EOF.  If a previous error has occurred on the 
  879. record stream that has not been cleared (error indicator set), rcgetc returns 
  880. EOF.  
  881.  
  882.  
  883. 1.4.6 The rcgetd Function
  884.  
  885. Synopsis
  886.  
  887.      #include <recio.h>
  888.      double rcgetd(REC *rp, size_t begcol, size_t endcol);
  889.  
  890. Description
  891.  
  892. The rcgetd function gets one floating point number contained inclusively
  893. from column begcol to column endcol for the input record stream pointed to 
  894. by rp.  Any leading or trailing white space in the field is ignored.
  895.  
  896. If an error occurs, the error indicator for the record stream is set, 
  897. errno is set to one of the error reporting macros as defined in <errno.h>, 
  898. the callback error function is called (if registered), and the rcgetd 
  899. function returns zero (0.0).
  900.  
  901. Returns
  902.  
  903. The rcgetd function returns a double precision floating point number from the 
  904. input record stream pointed to by rp.  If begcol is beyond the end-of-record, 
  905. if the field is empty, or if there is an illegal character in the field, the 
  906. error indicator for the record stream is set, and rcgetd returns zero (0.0).  
  907. If the record stream is at end-of-file (end-of-file indicator set), rcgetd 
  908. returns zero (0.0).  If a previous error has occurred on the record stream 
  909. that has not been cleared (error indicator set), rcgetd returns zero (0.0).
  910.  
  911.  
  912. 1.4.7 The rcgetf Function
  913.  
  914. Synopsis
  915.  
  916.      #include <recio.h>
  917.      float rcgetf(REC *rp, size_t begcol, size_t endcol);
  918.  
  919. Description
  920.  
  921. The rcgetd function gets one floating point number contained inclusively
  922. from column begcol to column endcol for the input record stream pointed to 
  923. by rp.  Any leading or trailing white space in the field is ignored.
  924.  
  925. If an error occurs, the error indicator for the record stream is set, 
  926. errno is set to one of the error reporting macros as defined in <errno.h>, 
  927. the callback error function is called (if registered), and the rcgetf 
  928. function returns zero (0.0).
  929.  
  930. Returns
  931.  
  932. The rcgetf function returns a single precision floating point number from the 
  933. input record stream pointed to by rp.  If begcol is beyond the end-of-record, 
  934. if the field is empty, or if there is an illegal character in the field, the 
  935. error indicator for the record stream is set, and rcgetf returns zero (0.0).  
  936. If the record stream is at end-of-file (end-of-file indicator set), rcgetf 
  937. returns zero (0.0).  If a previous error has occurred on the record stream 
  938. that has not been cleared (error indicator set), rcgetf returns zero (0.0).
  939.  
  940.  
  941. 1.4.8 The rcgeti Function
  942.  
  943. Synopsis
  944.  
  945.      #include <recio.h>
  946.      int rcgeti(REC *rp, size_t begcol, size_t endcol);
  947.  
  948. Description
  949.  
  950. The rcgeti function gets one integral number contained inclusively from 
  951. column begcol to column endcol for the input record stream pointed to by 
  952. rp.  Any leading or trailing white space in the field is ignored.
  953.  
  954. If an error occurs, the error indicator for the record stream is set, 
  955. errno is set to one of the error reporting macros as defined in <errno.h>, 
  956. the callback error function is called (if registered), and the rgeti 
  957. function returns zero.
  958.  
  959. Returns
  960.  
  961. The rcgeti function returns a signed integer from the input record stream 
  962. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  963. empty, or if there is an illegal character in the field, the error indicator 
  964. for the record stream is set, and rcgeti returns zero.  If the record stream 
  965. is at end-of-file (end-of-file indicator set), rcgeti returns zero.  If a 
  966. previous error has occurred on the record stream that has not been cleared 
  967. (error indicator set), rcgeti returns zero.  
  968.  
  969.  
  970. 1.4.9 The rcgetl Function
  971.  
  972. Synopsis
  973.  
  974.      #include <recio.h>
  975.      long rcgetl(REC *rp, size_t begcol, size_t endcol);
  976.  
  977. Description
  978.  
  979. The rcgetl function gets one integral number contained inclusively from 
  980. column begcol to column endcol for the input record stream pointed to by 
  981. rp.  Any leading or trailing white space in the field is ignored.
  982.  
  983. If an error occurs, the error indicator for the record stream is set, 
  984. errno is set to one of the error reporting macros as defined in <errno.h>, 
  985. the callback error function is called (if registered), and the rgetl 
  986. function returns zero (0L).
  987.  
  988. Returns
  989.  
  990. The rcgetl function returns a signed long from the input record stream 
  991. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  992. empty, or if there is an illegal character in the field, the error indicator 
  993. for the record stream is set, and rcgetl returns zero (0L).  If the record 
  994. stream is at end-of-file (end-of-file indicator set), rcgetl returns zero 
  995. (0L).  If a previous error has occurred on the record stream that has not 
  996. been cleared (error indicator set), rcgetl returns zero (0L).  
  997.  
  998.  
  999. 1.4.10 The rcgets Function
  1000.  
  1001. Synopsis
  1002.  
  1003.      #include <recio.h>
  1004.      char *rcgets(REC *rp, size_t begcol, size_t endcol);
  1005.  
  1006. Description
  1007.  
  1008. The rcgets function gets a string contained inclusively from column 
  1009. begcol to column endcol for the input record stream pointed to by 
  1010. rp.  The rcgets function does not remove any leading or trailing
  1011. white space, nor does it remove any text delimiter characters.
  1012.  
  1013. If an error occurs, the error indicator for the record stream is set, 
  1014. errno is set to one of the error reporting macros as defined in <errno.h>, 
  1015. the callback error function is called (if registered), and the rgets 
  1016. function returns a null pointer.
  1017.  
  1018. Returns
  1019.  
  1020. The rcgets function returns a pointer to a character array from the input 
  1021. record stream pointed to by rp.  If begcol is beyond the end-of-record, 
  1022. the error indicator for the record stream is set, and rcgets returns a null 
  1023. pointer.  If the record stream is at end-of-file (end-of-file indicator set), 
  1024. rcgets returns a null pointer.  If a previous error has occurred on the record 
  1025. stream that has not been cleared (error indicator set), rcgets returns a null 
  1026. pointer.
  1027.  
  1028.  
  1029. 1.4.11 The rcgetui Function
  1030.  
  1031. Synopsis
  1032.  
  1033.      #include <recio.h>
  1034.      unsigned int rcgetui(REC *rp, size_t begcol, size_t endcol);
  1035.  
  1036. Description
  1037.  
  1038. The rcgetui function gets one non-negative integral number contained 
  1039. inclusively from column begcol to column endcol for the input record 
  1040. stream pointed to by rp.  Any leading or trailing white space in the 
  1041. field is ignored.
  1042.  
  1043. If an error occurs, the error indicator for the record stream is set, 
  1044. errno is set to one of the error reporting macros as defined in <errno.h>, 
  1045. the callback error function is called (if registered), and the rgetui 
  1046. function returns zero.
  1047.  
  1048. Returns
  1049.  
  1050. The rcgetui function returns an unsigned integer from the input record 
  1051. stream pointed to by rp.  If begcol is beyond the end-of-record, if the 
  1052. field is empty, or if there is an illegal character in the field, the 
  1053. error indicator for the record stream is set, and rcgetui returns zero.  If 
  1054. the record stream is at end-of-file (end-of-file indicator set), rcgetui 
  1055. returns zero.  If a previous error has occurred on the record stream that has 
  1056. not been cleared (error indicator set), rcgetui returns zero.  
  1057.  
  1058.  
  1059. 1.4.12 The rcgetul Function
  1060.  
  1061. Synopsis
  1062.  
  1063.      #include <recio.h>
  1064.      unsigned long rcgetul(REC *rp, size_t begcol, size_t endcol);
  1065.  
  1066. Description
  1067.  
  1068. The rcgetul function gets one non-negative integral number contained 
  1069. inclusively from column begcol to column endcol for the input record 
  1070. stream pointed to by rp.  Any leading or trailing white space in the 
  1071. field is ignored.
  1072.  
  1073. If an error occurs, the error indicator for the record stream is set, 
  1074. errno is set to one of the error reporting macros as defined in <errno.h>, 
  1075. the callback error function is called (if registered), and the rgetul 
  1076. function returns zero (0L).
  1077.  
  1078. Returns
  1079.  
  1080. The rcgetul function returns an unsigned long from the input record stream 
  1081. pointed to by rp.  If begcol is beyond the end-of-record, if the field is 
  1082. empty, or if there is an illegal character in the field, the error indicator 
  1083. for the record stream is set, and rcgetul returns zero (0L).  If the record 
  1084. stream is at end-of-file (end-of-file indicator set), rcgetul returns zero 
  1085. (0L).  If a previous error has occurred on the record stream that has not 
  1086. been cleared (error indicator set), rcgetul returns zero (0L).  
  1087.  
  1088.  
  1089. 1.5 Current Position Functions
  1090.  
  1091. 1.5.1 The rbegcolno Function
  1092.  
  1093. Synopsis
  1094.  
  1095.      #include <recio.h>
  1096.      int rbegcolno(REC *rp);
  1097.  
  1098. Description
  1099.  
  1100. The rbegcolno function gets the current setting of the first column number 
  1101. in the record for the record stream pointed to by rp.
  1102.  
  1103. Returns
  1104.  
  1105. The rbegcolno function returns 0 if column numbering starts with zero or 
  1106. 1 if column numbering starts with one.
  1107.  
  1108.  
  1109. 1.5.2 The rcolno Function
  1110.  
  1111. Synopsis
  1112.  
  1113.      #include <recio.h>
  1114.      size_t rcolno(REC *rp);
  1115.  
  1116. Description
  1117.  
  1118. The rcolno function gets the current column number of the current record 
  1119. for the record stream pointed to by rp.
  1120.  
  1121. Returns
  1122.  
  1123. The rcolno function returns the current column number of the current record 
  1124. for the record stream pointed to by rp.  The rcolno function returns zero 
  1125. prior to the reading of the first record.
  1126.  
  1127.  
  1128. 1.5.3 The rflds Function
  1129.  
  1130. Synopsis
  1131.  
  1132.      #include <recio.h>
  1133.      char *rflds(REC *rp);
  1134.  
  1135. Description
  1136.  
  1137. The rflds function gets a pointer to the field buffer associated with 
  1138. the record stream pointed to by rp.  The last field read from the current 
  1139. record is stored in the field buffer.  The field is terminated by a
  1140. null character.
  1141.  
  1142. Returns
  1143.  
  1144. The rflds function returns a pointer to the field buffer associated with 
  1145. the record stream pointed to by rp.
  1146.  
  1147.  
  1148. 1.5.4 The rfldno Function
  1149.  
  1150. Synopsis
  1151.  
  1152.      #include <recio.h>
  1153.      size_t rfldno(REC *rp);
  1154.  
  1155. Description
  1156.  
  1157. The rfldno function gets the number of fields that have been read from 
  1158. the current record for the record stream pointed to by rp.
  1159.  
  1160. Returns
  1161.  
  1162. The rfldno function returns the number of fields that have been read from 
  1163. the current record for the record stream pointed to by rp.
  1164.  
  1165.  
  1166. 1.5.5 The rnames Function
  1167.  
  1168. Synopsis
  1169.  
  1170.      #include <recio.h>
  1171.      char *rnames(REC *rp);
  1172.  
  1173. Description
  1174.  
  1175. The rnames function gets a pointer to the name of the file associated
  1176. with the record stream pointed to by rp.
  1177.  
  1178. Returns
  1179.  
  1180. The rnames function returns a pointer to the name of the file associated
  1181. with the record stream pointed to by rp.
  1182.  
  1183.  
  1184. 1.5.6 The rgetrec Function
  1185.  
  1186. Synopsis
  1187.  
  1188.      #include <recio.h>
  1189.      char *rgetrec(REC *rp);
  1190.  
  1191. Description
  1192.  
  1193. The rgetrec function gets the next record from the record stream pointed
  1194. to by rp.  If the next record was successfully read, the rgetrec function 
  1195. increments the record number, clears the field and columns numbers to zero,
  1196. and returns a pointer to the record buffer.  If there are no more records, 
  1197. the record number is not incremented and the field and column numbers are 
  1198. cleared to zero.  The first record is at one (1L), the first field at zero, 
  1199. and the first column is at zero.
  1200.  
  1201. If an error occurs, the error indicator for the record stream is set, 
  1202. the callback error function is called (if registered), and the rgetrec 
  1203. function returns a null pointer.
  1204.  
  1205. If the end-of-file is reached, the end-of-file indicator for the record
  1206. stream is set and the rgetrec function returns a null pointer.
  1207.  
  1208. Returns
  1209.  
  1210. The rgetrec function returns a pointer to the record buffer if the next 
  1211. record was successfully read.  If there are no more records, the end-of-file 
  1212. indicator is set and rgetrec returns a null pointer.  If an error occurred, 
  1213. the error indicator is set and rgetrec returns a null pointer.
  1214.  
  1215.  
  1216. 1.5.7 The rrecs Function
  1217.  
  1218. Synopsis
  1219.  
  1220.      #include <recio.h>
  1221.      char *rrecs(REC *rp);
  1222.  
  1223. Description
  1224.  
  1225. The rrecs function gets a pointer to the record buffer associated with 
  1226. the record stream pointed to by rp.  The current record is stored in the 
  1227. record buffer.  The record is terminated by a null character.
  1228.  
  1229. Returns
  1230.  
  1231. The rrecs function returns a pointer to the record buffer associated with 
  1232. the record stream pointed to by rp.
  1233.  
  1234.  
  1235. 1.5.8 The rrecno Function
  1236.  
  1237. Synopsis
  1238.  
  1239.      #include <recio.h>
  1240.      long rrecno(REC *rp);
  1241.  
  1242. Description
  1243.  
  1244. The rrecno function gets the number of records that have been read from 
  1245. the record stream pointed to by rp.
  1246.  
  1247. Returns
  1248.  
  1249. The rrecno function returns the number of records that have been read from 
  1250. the record stream pointed to by rp.
  1251.  
  1252.  
  1253. 1.5.9 The rsetbegcolno Function
  1254.  
  1255. Synopsis
  1256.  
  1257.      #include <recio.h>
  1258.      int rsetbegcolno(REC *rp, int colno);
  1259.  
  1260. Description
  1261.  
  1262. The rsetbegcolno function sets the first column number colno for the record 
  1263. stream pointed to by rp.  Column numbering can start at either 0 or 1.
  1264.  
  1265. If an error occurs, the error indicator for the record stream is set, the 
  1266. callback error function is called (if registered), and the rsetbegcolno 
  1267. function returns EOF.
  1268.  
  1269. Returns
  1270.  
  1271. The rsetbegcolno function returns zero if the first column number was 
  1272. successfully set, or EOF if any errors were detected.
  1273.  
  1274.  
  1275. 1.5.10 The rsetfldstr Function
  1276.  
  1277. Synopsis
  1278.  
  1279.      #include <recio.h>
  1280.      int rsetfldstr(REC *rp, char *s);
  1281.  
  1282. Description
  1283.  
  1284. The rsetfldstr function copies the string s into the field buffer of the 
  1285. record stream pointed to by rp.  Any existing string in the field buffer
  1286. is overwritten.  The field buffer size is increased, if necessary, to 
  1287. accommodate the string.  
  1288.  
  1289. A side effect of using the rsetfldstr function is that the error and 
  1290. end-of-file indicators for the record stream are cleared (provided 
  1291. rsetfldstr does not create an error).
  1292.  
  1293. If an error occurs, the error indicator for the record stream is set, 
  1294. the callback error function is called (if registered), and the rsetfldstr 
  1295. function returns EOF.
  1296.  
  1297. Returns
  1298.  
  1299. The rsetfldstr function returns zero if the string is successfully copied 
  1300. into the field buffer, or EOF if any errors were detected.
  1301.  
  1302.  
  1303. 1.6 Error-Handling Functions
  1304.  
  1305. 1.6.1 The errno Macro
  1306.  
  1307. Synopsis
  1308.  
  1309.      #include <errno.h>
  1310.  
  1311. Description
  1312.  
  1313. The errno macro "expands to a modifiable lvalue that has type int, the
  1314. value of which is set to a positive error number by several library
  1315. functions." -Section 4.1.3 of ANSI X3.159-1989.
  1316.  
  1317.      
  1318. 1.6.2 The rclearerr Function
  1319.  
  1320. Synopsis
  1321.  
  1322.      #include <recio.h>
  1323.      void rclearerr(REC *rp);
  1324.  
  1325. Description
  1326.  
  1327. The rclearerr function clears the end-of-file and error indicators for
  1328. the record stream pointed to by rp.
  1329.  
  1330. Returns
  1331.  
  1332. The rclearerr function returns no value.
  1333.  
  1334.  
  1335. 1.6.3 The rcxtno Function
  1336.  
  1337. Synopsis
  1338.  
  1339.      #include <recio.h>
  1340.      int rcxtno(REC *rp);
  1341.  
  1342. Description
  1343.  
  1344. The rcxtno function gets the context number from the record stream pointed 
  1345. to by rp.  Context numbers can be assigned to a record stream using the 
  1346. rsetcxtno function.  A zero context number indicates that the context 
  1347. number has not been assigned.  The recin stream returns the macro value 
  1348. of RECIN.
  1349.  
  1350. Returns
  1351.  
  1352. The rcxtno function returns the context number from the record stream pointed 
  1353. to by rp.
  1354.  
  1355.  
  1356. 1.6.4 The rerror Function
  1357.  
  1358. Synopsis
  1359.  
  1360.      #include <recio.h>
  1361.      unsigned int rerror(REC *rp);
  1362.  
  1363. Description
  1364.  
  1365. The rerror function tests the error indicator for the record stream
  1366. pointed to by rp.
  1367.  
  1368. Returns
  1369.  
  1370. The rerror function returns nonzero if and only if the error indicator
  1371. is set for the record stream pointed to by rp.
  1372.  
  1373.  
  1374. 1.6.5 The reof Function
  1375.  
  1376. Synopsis
  1377.  
  1378.      #include <recio.h>
  1379.      unsigned int reof(REC *rp);
  1380.  
  1381. Description
  1382.  
  1383. The reof function tests the end-of-file indicator for the record stream
  1384. pointed to by rp.
  1385.  
  1386. Returns
  1387.  
  1388. The reof function returns nonzero if and only if the end-of-file indicator
  1389. is set for the record stream pointed to by rp.
  1390.  
  1391.  
  1392. 1.6.6 The risvalid Function
  1393.  
  1394. Synopsis
  1395.  
  1396.      #include <recio.h>
  1397.      int risvalid(REC *rp);
  1398.  
  1399. Description
  1400.  
  1401. The risvalid function tests if rp is a valid pointer to a record stream.
  1402.  
  1403. Returns
  1404.  
  1405. The risvalid function returns a nonzero value if and only if rp is a 
  1406. valid pointer to an open record stream.
  1407.  
  1408.  
  1409. 1.6.7 The rsetcxtno Function
  1410.  
  1411. Synopsis
  1412.  
  1413.      #include <recio.h>
  1414.      int rsetcxtno(REC *rp, int cxtno);
  1415.  
  1416. Description
  1417.  
  1418. The rsetcxtno function sets the context number cxtno on the record stream 
  1419. pointed to by rp.  Assigning a context number allows a file format to be more 
  1420. easily identified in the callback error function.  Negative context numbers 
  1421. are reserved; a zero context number indicates an that the context has not 
  1422. been assigned.  A macro value RECIN is preassigned to the recin stream.
  1423.  
  1424. If an error occurs, the rsetcxtno function returns EOF.
  1425.  
  1426. Returns
  1427.  
  1428. The rsetcxtno returns zero if the context number was successfully assigned
  1429. to the record stream, or EOF if any errors were detected.
  1430.  
  1431.  
  1432. 1.6.8 The rseterr Function
  1433.  
  1434. Synopsis
  1435.  
  1436.      #include <recio.h>
  1437.      int rseterr(REC *rp, int errnum);
  1438.  
  1439. Description
  1440.  
  1441. The rseterr function sets the global error number errno to the value of 
  1442. errnum and, if errnum is positive, sets the error indicator on the record 
  1443. stream pointed to by rp.  The callback error function is called (if 
  1444. registered).  If the record stream error indicator is already set on 
  1445. entry to the rseterr function, the rseterr function only sets errno.
  1446.  
  1447. Returns
  1448.  
  1449. The rseterr function returns the error number.  If the callback error 
  1450. function corrects the error and clears the error number, the function 
  1451. returns zero.
  1452.  
  1453.  
  1454. 1.6.9 The rseterrfn Function
  1455.  
  1456. Synopsis
  1457.  
  1458.      #include <recio.h>
  1459.      void rseterrfn(void(*rerrfn)(REC *rp));
  1460.  
  1461. Description
  1462.  
  1463. The rseterrfn function registers the callback error function rerrfn for the 
  1464. record stream pointed to by rp.
  1465.  
  1466. Returns
  1467.  
  1468. The rseterrfn function returns no value.  The callback error function rerrfn 
  1469. returns no value.
  1470.  
  1471.  
  1472.  
  1473. 2.0 PORTABILITY ISSUES
  1474.  
  1475. The first six characters of this function are common to another function. 
  1476. Ref 3.1.2 of ANSI X3.159-1989.  (1.2.1, 1.2.2, 1.2.4, 1.3.3, 1.3.4, 1.3.13, 
  1477. 1.4.1-1.4.4, 1.4.11, 1.4.12, 1.5.10, 1.6.8, 1.6.9)
  1478.  
  1479.  
  1480.  
  1481. 3.0 INDEX
  1482.  
  1483. errno macro ............ 1.6.1
  1484. FLDBUFSIZ macro ........ 1.1.3, 1.2.4
  1485. rbegcolno function ..... 1.5.1
  1486. rbgeti function ........ 1.3.1
  1487. rbgetl function ........ 1.3.2
  1488. rbgetui function ....... 1.3.3
  1489. rbgetul function ....... 1.3.4
  1490. rcbgeti function ....... 1.4.1
  1491. rcbgetl function ....... 1.4.2
  1492. rcbgetui function ...... 1.4.3
  1493. rcbgetul function ...... 1.4.4
  1494. rcgetc function ........ 1.4.5
  1495. rcgetd function ........ 1.4.6
  1496. rcgetf function ........ 1.4.7
  1497. rcgeti function ........ 1.4.8
  1498. rcgetl function ........ 1.4.9
  1499. rcgets function ........ 1.4.10
  1500. rcgetui function ....... 1.4.11
  1501. rcgetul function ....... 1.4.12
  1502. rclearerr function ..... 1.6.2
  1503. rclose function ........ 1.2.1
  1504. rcloseall function ..... 1.2.2
  1505. rcolno function ........ 1.5.2
  1506. rcxtno function ........ 1.6.3
  1507. REC object ............. 1.1.2
  1508. recin expression ....... 1.1.4
  1509. RECBUFSIZ macro ........ 1.1.3, 1.2.5
  1510. RECFLDCH macro ......... 1.1.3, 1.3.13
  1511. RECTXTCH macro ......... 1.1.3, 1.3.14
  1512. reof function .......... 1.6.5
  1513. rerror function ........ 1.6.4
  1514. rflds function ......... 1.5.3
  1515. rfldno function ........ 1.5.4
  1516. rgetc function ......... 1.3.5
  1517. rgetd function ......... 1.3.6
  1518. rgetf function ......... 1.3.7
  1519. rgeti function ......... 1.3.8
  1520. rgetl function ......... 1.3.9
  1521. rgetrec function ....... 1.5.6
  1522. rgets function ......... 1.3.10
  1523. rgetui function ........ 1.3.11
  1524. rgetul function ........ 1.3.12
  1525. risvalid function ...... 1.6.6
  1526. rnames function ........ 1.5.5
  1527. ropen function  ........ 1.2.3
  1528. ROPEN_MAX macro ........ 1.1.3
  1529. rrecs function ......... 1.5.7
  1530. rrecno function ........ 1.5.8
  1531. rsetbegcolno function .. 1.5.9
  1532. rsetcxtno function ..... 1.6.7
  1533. rseterr function ....... 1.6.8
  1534. rseterrfn function ..... 1.6.9
  1535. rsetfldch function ..... 1.3.13
  1536. rsetfldsiz function .... 1.2.4
  1537. rsetfldstr function .... 1.5.10
  1538. rsetrecsiz function .... 1.2.5
  1539. rsettxtch function ..... 1.3.14
  1540. rskipfld function  ..... 1.3.15
  1541. rskipnfld function ..... 1.3.16
  1542.