This month, I present the low-level "primitive" functions in <stdio.h> that must be tailored to each operating system. A primitive is a function that performs some essential operation. No other combination of library functions can substitute. You can keep most of the library portable if you isolate system dependencies in a minimum set of primitives.

As I mentioned last month, this implementation has nine such functions Each primitive function must perform a standardized operation for the Standard C library. Each must also be reasonably easy to tailor for the divergent needs of different operating systems.

• remove — Remove a named file.
• rename — Change the name of a file.
• tmpnam — Construct a reasonable name for a temporary file.

Three of the primitives are macros defined in the internal header "yfuns.h". It defines macros and declares functions needed only within the Standard C library to interface to the outside world. Only certain functions written for this implementation need include "yfuns.h". (The internal header <yvals.h>, by contrast, must be included in several standard headers.)

The three macros look like internal functions with the declarations

int _Fclose(FILE *str);
int _Fread(FILeE *str, char *buf, int size);
int _Fwrite(FILE *str, const char *buf, int size);

• _Fclose — Close the file associated with str. Return zero if successful.
• _Fread — Read up to size characters into the buffer starting at buf from the file associated with str. Return the number successfully read, or zero if at end-of-file, or a negative error code if a read error occurs.
• _Fwrite — Write size characters from the buffer starting at buf to the file associated with str. Return the number of characters actually written or a negative error code if a write error occurs.

The last three primitives are internal functions. One function is declared in "xstdio.h". Two are used in masking macros, and hence are declared in <stdio.h>. (See last month's presentation for a listing of this standard header file.) Their declarations are:

short _Fopen(const char *name, unsigned short mode, const char *mods);
long _Fgpos(FILE *str, fpos_t *fpos);
int _Fspos(FILE *str, const fpos_t *fpos, long offset, int way);

• _Fopen — Open the file with name name and mode mode (possibly using the string mods as well). Return a non-negative handle if successful.
• _Fgpos — If fpos is not a null pointer, store the file-position indicator at fpos and return zero. Otherwise, encode the file-position indicator as a long and return its value. Return the value EOF if not successful.
• _Fspos — If way has the value SEEK_SET, set the file-position indicator from either fpos or offset. (If fpos is not a null pointer, use the value stored in fpos. Otherwise, decode offset to determine the file-position indicator.) If way has the value SEEK_CUR, add offset to the file-position indicator. Otherwise, way must have the value SEEK_END. Set the file-position indicator to just beyond the last character in the file, plus offset. If successful, return zero and clear _MEOF, _MREAD, and _MWRITE. Otherwise, return the value EOF.

The primitives you are likely to find strangest are _Fgpos and _Fspos. They bear only a loose resemblance to their ancestor, called lseek. Most of the difference is designed to accommodate two new file-positioning functions, fgetpos and fsetpos. These have no exact analog in UNIX.

To show you why these new primitives take the form they do, I simply show how the library uses them. The function fseek, for example, is simply

int fseek(FILE *str, fpos_t *p)
   {
   return (_Fspos(str, NULL, off, smode));
   }

long ftell(FILE *str)
   {
   return (_Fgpos(str, NULL));
   }

void rewind(FILE *str)
   {
   _Fspos(str, NULL, OL, SEEK_SET);
   str->_Mode &= ~_MERR;
   }

int fgetpos(FILE *str, fpos_t *p)
   {
   return (_Fgpos(str, p));
   }

int fsetpos(FILE *str, const fpos_t *p)
   {
   return (_Fspos(str, p, OL, SEEK_SET));
   }

For simplicity, I sketch here primitives that interface to many versions of the UNIX operating system. That is often the easiest system to use as a host for the Standard C library. The C language has moved to many other environments. Still, as I indicated above, much of the library design was shaped by the needs and capabilities of UNIX. The files I show are only sketches because they often can be augmented to advantage.

In all cases, I assume the existence of C-callable functions that perform UNIX system calls without violating the name-space restrictions of Standard C. I take the conventional UNIX name, make the first letter uppercase and prepend an underscore. Thus, unlink becomes _Unlink. You may have to write these functions in assembly language if your UNIX system supplies no adequate substitutes.

This article is excerpted in part from P.J. Plauger, The Standard C Library, (Englewood Cliffs, N.J.: Prentice-Hall, 1992).