The sm_io portion of the libsm library is similar to the stdio library. It is derived from the Chris Torek version of the stdio library (BSD). There are some key differences described below between sm_io and stdio but many similarities will be noticed.
A key difference between stdio and sm_io is that the functional code that does the open, close, read, write, etc. on a file can be different for different files. For example, with stdio the functional code (read, write) is either the default supplied in the library or a "programmer specified" set of functions set via sm_io_open(). Whichever set of functions are specified all open's, read's, write's, etc use the same set of functions. In contrast, with sm_io a different set of functions can be specified with each active file for read's, write's, etc. These different function sets are identified as file types (see sm_io_open()). Each function set can handle the actions directly, pass the action request to another function set or do some work before passing it on to another function set. The setting of a function set for a file type can be done for a file type at any time (even after the type is open).
A second difference is the use of rpools. An rpool is specified with the opening of a file (sm_io_open()). This allows of a file to be associated with an rpool so that when the rpool is released the open file will be closed; the sm_io_open() registers that sm_io_close() should be called when the rpool is released.
A third difference is that the I/O functions take a timeout argument. This allows the setting of a maximum amount of time allowable for the I/O to be completed. This means the calling program does not need to setup it's own timeout mechanism. NOTE: SIGALRM's should not be active in the calling program when an I/O function with a timeout is used.
When converting source code from stdio to sm_io be very careful to NOTE: the arguments to functions have been rationalized. That is, unlike stdio, all sm_io functions that take a file pointer (SM_FILE_T *) argument have the file pointer as the first argument. Also not all functions with stdio have an identical matching sm_io API: the API list has been thinned since a number of stdio API's overlapped in functionality. Remember many functions also have a timeout argument added.
When a file is going to be opened, the file type is included with sm_io_open(). A file type is either one automatically included with the sm_io library or one created by the program at runtime. File types can be either buffered or unbuffered. When buffered the buffering is either the builtin sm_io buffering or as done by the file type. File types can be disk files, strings, TCP/IP connections or whatever your imagination can come up with that can be read and/or written to.
Information about a particular file type or pointer can be obtained or set with the sm_io "info" functions. The sm_io_setinfo() and sm_io_getinfo() functions work on an active file pointer.
There is one main include file for use with sm_io: io.h. Since the use of rpools is specified with sm_io_open() an rpool may be created and thus rpool.h may need to be included as well (before io.h).
#include <rpool.h> #include <io.h>
Below is a list of the functions for sm_io listed in alphabetical order. Currently these functions return error codes and set errno when appropriate. These (may?/will?) change to raising exceptions later.
SM_FILE_T *sm_io_autoflush(SM_FILE_T *fp, SM_FILE_T *) void sm_io_automode(SM_FILE_T *fp, SM_FILE_T *) void sm_io_clearerr(SM_FILE_T *fp) int sm_io_close(SM_FILE_T *fp, int timeout) int sm_io_dup(SM_FILE_T *fp) int sm_io_eof(SM_FILE_T *fp) int sm_io_error(SM_FILE_T *fp) char * sm_io_fgets(SM_FILE_T *fp, int timeout, char *buf, int n) int sm_io_flush(SM_FILE_T *fp, int timeout) int sm_io_fopen(char *pathname, int flags [, MODE_T mode]) int sm_io_fprintf(SM_FILE_T *fp, int timeout, const char *fmt, ...) int sm_io_fputs(s, int, SM_FILE_T *fp) int sm_io_fscanf(SM_FILE_T *fp, int timeout, char const *fmt, ...) int sm_io_getc(SM_FILE_T *fp, int timeout) void sm_io_getinfo(SM_FILE_T *sfp, int what, void *valp) SM_FILE_T * sm_io_open(SM_FILE_T type, int timeout, void *info, int flags, void *rpool) int sm_io_purge(SM_FILE_T *fp) int sm_io_putc(SM_FILE_T *fp, int timeout, int c) size_t sm_io_read(SM_FILE_T *fp, int timeout, char *buf, size_t size) SM_FILE_T * sm_io_open(SM_FILE_T type, int timeout, void *info, int flags, void *rpool) void sm_io_rewind(SM_FILE_T *fp, int timeout) int sm_io_seek(SM_FILE_T *fp, off_t offset, int timeout, int whence) void sm_io_setinfo(SM_FILE_T *sfp, int what, void *valp) int sm_io_setvbuf(SM_FILE_T *fp, int timeout, char *buf, int mode, size_t size) int sm_io_sscanf(const char *str, char const *fmt, ...) long sm_io_tell(SM_FILE_T *fp, int timeout) int sm_io_ungetc(SM_FILE_T *fp, int timeout, int c) size_t sm_io_write(SM_FILE_T *fp, int timeout, char *buf, size_t size) int sm_snprintf(char *str, size_t n, char const *fmt, ...)
For many of the functions a timeout argument is given. This limits the amount of time allowed for the function to complete. There are three pre-defined values:
A function caller can also specify a positive integer value in milliseconds. A function will return with errno set to EINVAL if a bad value is given for timeout. When a function times out the function returns in error with errno set to EAGAIN. In the future this may change to an exception being thrown.
There are several builtin file types as mentioned in sm_io_open(). More file types may be added later.
When writing functions to create a file type a function needs to be created for each function vector in the SM_FILE_T structure that will be passed to sm_io_open() or sm_io_setinfo(). Otherwise the setting will be rejected and errno set to EINVAL. Each function should accept and handle the number and types of arguments as described in the portion of the SM_FILE_T structure shown below:
int (*open) __P((SM_FILE_T *fp, const void *, int flags, const void *rpool)); int (*close) __P((SM_FILE_T *fp)); int (*read) __P((SM_FILE_T *fp, char *buf, size_t size)); int (*write) __P((SM_FILE_T *fp, const char *buf, size_t size)); off_t (*seek) __P((SM_FILE_T *fp, off_t offset, int whence)); int (*getinfo) __P((SM_FILE_T *fp, int what, void *valp)); int (*setinfo) __P((SM_FILE_T *fp, int what, void *valp));
The macro SM_IO_SET_TYPE should be used to initialized an SM_FILE_T as a file type for an sm_io_open():You should avoid trying to change or use the other structure members of the SM_FILE_T. The file pointer content (internal structure members) of an active file should only be set and observed with the "info" functions. The two exceptions to the above statement are the structure members cookie and ival. Cookie is of type void * while ival is of type int. These two structure members exist specificly for your created file type to use. The sm_io functions will not change or set these two structure members; only specific file type will change or set these variables.
For maintaining information privately about status for a file type the information should be encapsulated in a cookie. A cookie is an opaque type that contains information that is only known to the file type layer itself. The sm_io package will know nothing about the contents of the cookie; sm_io only maintains the location of the cookie so that it may be passed to the functions of a file type. It is up to the file type to determine what to do with the cookie. It is the responsibility of the file type's open to create the cookie and point the SM_FILE_T's cookie at the address of the cookie. It is the responsibility of close to clean up any resources that the cookie and instance of the file type have used.
For the cookie to be passed to all members of a function type cleanly the location of the cookie must assigned during the call to open. The file type functions should not attempt to maintain the cookie internally since the file type may have serveral instances (file pointers).
The SM_FILE_T's member ival may be used in a manner similar to cookie. It is not to be used for maintaining the file's offset or access status (other members do that). It is intended as a "light" reference.
The file type vector functions are called by the sm_io_*() functions after sm_io processing has occurred. The sm_io processing validates SM_FILE_T's and may then handle the call entirely itself or pass the request to the file type vector functions.
All of the "int" functions should return -1 (minus one) on failure and 0 (zero) or greater on success. Errno should be set to provide diagnostic information to the caller if it has not already been set by another function the file type function used.
Examples are a wonderful manner of clarifying details. Below is an example of an open function.
This shows the setup.
A number of sm_io API's perform similar to their stdio counterparts (same name as when the "sm_io_" is removed). One difference between sm_io and stdio functions is that if a "file pointer" (FILE/SM_FILE_T) is one of the arguments for the function, then it is now the first argument. Sm_io is standardized so that when a file pointer is one of the arguments to function then it will always be the first arguement. Many of the sm_io function take a timeout argument (see Timeouts).
The API you have selected is one of these. Please consult the appropriate stdio man page for now.