About these functions

Each function description begins with an ANSI C function prototype, which specifies the types of any arguments as well as the type of the quantity returned by the function (see K&R, pp. 217–218). Note that many of these functions take pointer arguments. These can be traps for newcomers to C. Study the examples carefully! Often a function will return information to the caller in a variable or structure to which the pointer argument points. It is necessary in such cases for the caller to allocate storage for the variables or structures and to initialize the pointers so that they point to the allocated storage. If you fail to do so, the compiler probably will not warn you of your error; instead your program will fail mysteriously, probably with a core dump and an “illegal memory reference” error message.

With few exceptions, WFDB library functions return integers that indicate success or failure. The tables that follow the function prototypes list the possible returns and their meanings. By convention, a return code of -1 indicates end-of-file on input files, and no error message is printed. Other negative return codes signify other types of errors, and are usually accompanied by descriptive messages on the standard error output (but see section wfdbquiet and wfdbverbose). Zero may indicate success or failure, depending on context (see the descriptions of the individual functions below). Positive codes (returned by only a few functions) always indicate success.

A comprehensive discussion of database files appears later in this guide (see section Database Files). Most readers should not need to learn about the gruesome details of how the data are actually stored. You should know, however, that there are files that contain digitized signals, other files that contain annotations, and still others (called header files) that describe attributes of the signals such as sampling frequency. The database path lists directories in which database files are found; the WFDB library functions can find them given only the record (and annotator) names, provided that WFDB has been properly set (see section The Database Path and Other Environment Variables). WFDB library functions responsible for opening signal files find them by reading the header file (which contains their names) first.

The first two sections of this chapter describes functions that extract information from header files in order to gain access to signal and annotation files, and functions that control how these files are read and written. The following two sections describe functions that read and write signal and annotation files. Many readers will not need to go any further; the remaining sections deal with special-purpose functions that exist to serve unusual applications.