Title: A TUTORIAL INTRODUCTION TO THE C LANGUAGE RECIO LIBRARY Copyright: (C) 1994 William Pierpoint Version: 1.10 Date: March 28, 1994 1.0 STDIO AND RECIO The program many people learned when first introduced to the C programming language was the "hello, world" program published in Kernighan and Richie's "The C Programming Language." And the first line of that first program, #include tells the compiler that the functions and macros provided by the standard input/output library are needed for the program. The "hello, world" program uses the powerful printf statement for output. Unfortunately printf's counterpart for input, scanf, looks deceptively like printf, but has many ways to trap to unwary programmer. These include failure to provide the address of an variable, size of argument mismatched with the specification in the format statement, and number of arguments mismatched with the specification in the format statement. Suppose you use a library that defines a boolean type as an unsigned character. You develop an output module that writes variables of type boolean to a file, /* output */ boolean state=0; ... fprintf(fp, "%6d", state); where fp is a pointer to FILE. Once you get the output module working, you decide to develop the input module to read back into the program the data you wrote to disk. /* input */ boolean state; ... fscanf(fp, "%d", &state); So, is this ok? On one compiler this worked consistently without problems, but on another compiler, it overwrote the value in another variable. Why? Because fscanf expects the address of an integer, not an unsigned char. One compiler overwrote the adjoining memory address and the other compiler apparently did not. And since compilers don't do type checking on functions with variable number of arguments, you don't get any errors or warnings. That is what is so infuriating about this type of error. You see that another variable has the wrong value, you check all the code that uses the other variable, and you can't find anything wrong with it. In the midst of development, it is hard to imagine that the problem is caused by code that has nothing to do with the variable containing the bad value. The recio (record input/output) library takes a different approach to input. To input the boolean variable using the recio library, just write /* input */ boolean state; ... state = rgeti(rp); where rp is a pointer to REC (more about this later). The rgeti function gets an integer from the input and the compiler converts it to a boolean when it makes the assignment. No need to worry about crazy pointers here! Since virtually every program has to do input or output, the stdio library is familiar to every C programmer. Many functions in the recio library are analogous to the stdio library. This makes the learning curve easier. Analogous stdio/recio components stdio recio --------- --------- FILE REC FOPEN_MAX ROPEN_MAX stdin recin fopen ropen fclose rclose fgets rgetrec fscanf rgeti, rgetd, rgets, ... clearerr rclearerr feof reof ferror rerror At this time recio only includes functions for input. So why then does it stand for record input/output? Why isn't it called just reci? Output might be added in a later version, and if so, we don't want to have to go through our code and change every reci to recio. 2.0 EXAMPLES 2.1 Line Input One of the first things you can do with the recio library to is to substitute rgetrec() for fgets() to get a line of text (record) from a file (or standard input). The advantage of rgetrec() is that you don't have to go to the trouble to allocate space for a string buffer, or worry about the size of the string buffer. The recio library handles that for you automatically. The rgetrec function is like fgets() in that it gets a string from a stream, but it is like gets() in that it trims off the trailing newline character. The echo program demonstrates the use of the rgetrec function. /* echo.c - echo input to output */ #include #include #include "recio.h" main() { /* while input continues to be available */ while (rgetrec(recin)) { /* echo record buffer to output */ puts(rrecs(recin)); } /* if exited loop before end-of-file */ if (!reof(recin)) { exit (EXIT_FAILURE); } return (EXIT_SUCCESS); } The echo program reads standard input using recin, the recio equivalent to stdin. The rgetrec function returns a pointer to the record buffer, but the echo program did not use a variable to hold a pointer to the string (although it could have). Instead, the record buffer was accessed through the rrecs macro, which provides a pointer to the record buffer. Since rgetrec returns NULL on either error or end-of-file, your program needs to find out which condition occurred. The echo program just exits with a failure status if an error occurred before the end of the file was reached. 2.2 Line, Word, and Character Counting The power of the recio library comes from its facilities to break records into fields and from the many functions that operate on fields. Because the default field delimiter is the space character (which breaks on any whitespace), the default behavior is equivalent to subdividing a line of text into words. The wc program counts lines, words, and characters for files specified on the command line. /* wc.c - count lines, words, characters */ #include #include #include #include "recio.h" #define SIZE_T_MAX (~(size_t)0) main(int argc, char *argv[]) { int nf; /* number of files */ REC *rp; /* pointer to open record stream */ long nc, /* number of characters */ nw, /* number of words */ nl; /* number of lines */ /* loop through all files */ for (nf=1; nf < argc; nf++) { /* open record stream */ rp = ropen(argv[nf], "r"); if (!rp) { if (errno == ENOENT) { printf("ERROR: Could not open %s\n", argv[nf]); continue; } else { printf("FATAL ERROR: %s\n", strerror(errno)); exit (EXIT_FAILURE); } } /* initialize */ nc = nw = 0; rsetfldch(rp, ' '); rsettxtch(rp, ' '); /* loop through all lines (records) */ while (rgetrec(rp)) { /* count number of characters in line w/o '\n' */ nc += strlen(rrecs(rp)); /* count actual number of words (fields) */ nw += rskipnfld(rp, SIZE_T_MAX); } /* if exited loop on error rather than end-of-file */ if (rerror(rp)) { printf("FATAL ERROR: %s\n", strerror(rerror(recin))); exit (EXIT_FAILURE); } /* get number of lines (records) */ nl = rrecno(rp); /* adjust nc for operating system line termination character(s) */ #ifdef __MSDOS__ nc += nl + nl; /* carriage return and linefeed for each line */ #else nc += nl; /* newline for each line */ #endif /* output results */ printf("%s: %ld %ld %ld\n", rnames(rp), nl, nw, nc); /* close record stream */ rclose(rp); } return (EXIT_SUCCESS); } If ropen() fails, the wc program goes to the trouble to check errno for ENOENT rather than just assuming that the failure was caused by a missing file. The wc program also sets the field and text delimiters even though it is unneccessary here since they are the same as the default values. If you wanted to read a comma-delimited file, you could set the the delimiters to, rsetfldch(rp, ','); rsettxtch(rp, '"'); which allows you to also read text fields containing commas by delimiting the text with quotes, such as "Hello, World." Fields are counted using the rskipnfld function. The program asks the function to skip more fields than could possibly exist in the record and the function returns with the number of fields actually skipped. The rskipnfld function can be handy to have around. You might have a data file with dozens of fields in a record but your program only needs a couple of them. You can use rskipnfld() to skip over the fields you don't need to read. The recio library gives you more control over your input data than stdio. If the last field is missing from a data file, fscanf() starts reading the next line. In a file with a complex structure, it can be difficult to tell where you are. Sometimes every record in a file has a different format. The recio library has functions you can use to always find out where you are. You only move from record to record when you use the rgetrec function. Note that the wc program assumes that each line ends with a line terminator. That assumption may not be correct as the last line could end with the file terminator, in which case the character count is off by one or two. 2.3 Field Functions For most programs you will want to use those recio functions that read data from the fields of a record. Functions are available to read integer, unsigned integer, long, unsigned long, double, float, character, and string fields. Functions are divided into two groups: those that read character delimited fields (such as comma-delimited) and those that read column delimited fields (such as an integer between columns 0 and 9). Each group is further divided into two subgroups: one for numeric data in base 10 and the other for numeric data in any base from 2 to 36. See the text files USAGE.TXT and SPEC.TXT for more information. If you explore the source code for the recio library, you will find that the field functions can easily be extended for other data types. For example you could define, in one line of code, a function that would get a boolean variable and that function would generate an ERANGE error if the value was anything other than 0 or 1. See the file DESIGN.TXT for more information. Of course if you are not concerned with validation, you can always use rgeti(). 2.4 Error Handling Rather than checking errno and rerror() for errors after each call to a recio function, or checking the return value from those functions that return an error value, you can register a callback error function using the rseterrfn function. The error function gives you one convenient place to handle all recio errors. As you write your error function, you will find that the recio library provides many useful functions for determining and reporting the location and type of error. One important kind of error is the data error. Data errors occur when data values are too large or too small, when fields contain illegal characters, or when data is missing. Your error function can correct data errors either through algorithms you supply or by asking the user for a replacement value. For an example of a callback error function, see the TEST.C source code. A skeleton code structure for a callback error function is given in the file DESIGN.TXT. 3.0 WHAT NOW? That's it for this brief introduction. Next, if you haven't already done so, spend a few minutes running TEST.EXE, inputting various data values (both valid and invalid) to see what happens, and perusing the TEST.C source code. Then to study the recio functions in more detail, move on to the remaining documentation.