140266059SGregory Neil Shapiro<html> 240266059SGregory Neil Shapiro<head> 340266059SGregory Neil Shapiro<title>libsm sm_io general overview</title> 440266059SGregory Neil Shapiro</head> 540266059SGregory Neil Shapiro<body> 640266059SGregory Neil Shapiro<a href="index.html">Back to libsm overview</a> 740266059SGregory Neil Shapiro<center> 840266059SGregory Neil Shapiro<h1>libsm sm_io general overview</h1> 94313cc83SGregory Neil Shapiro<br> $Id: io.html,v 1.3 2001-03-17 03:22:50 gshapiro Exp $ 1040266059SGregory Neil Shapiro</center> 1140266059SGregory Neil Shapiro<h2> Introduction </h2> 1240266059SGregory Neil Shapiro<p> 1340266059SGregory Neil ShapiroThe <i>sm_io</i> portion of the <i>libsm</i> library is similar to 1440266059SGregory Neil Shapirothe <i>stdio</i> library. It is derived from the Chris Torek version 1540266059SGregory Neil Shapiroof the <i>stdio</i> library (BSD). There are some key differences 1640266059SGregory Neil Shapirodescribed below between <i>sm_io</i> and <i>stdio</i> but many 1740266059SGregory Neil Shapirosimilarities will be noticed. 1840266059SGregory Neil Shapiro</p> 1940266059SGregory Neil Shapiro<p> 2040266059SGregory Neil ShapiroA key difference between <i>stdio</i> and <i>sm_io</i> is that the 2140266059SGregory Neil Shapirofunctional code that does the open, close, read, write, etc. on a file 2240266059SGregory Neil Shapirocan be different for different files. For example, with <i>stdio</i> 2340266059SGregory Neil Shapirothe functional code (read, write) is either the default supplied in the 2440266059SGregory Neil Shapirolibrary or a "programmer specified" set of functions set via 2540266059SGregory Neil Shapiro<i>sm_io_open()</i>. Whichever set of functions are specified <b>all</b> 2640266059SGregory Neil Shapiroopen's, read's, write's, etc use the same set of functions. In contrast, with 2740266059SGregory Neil Shapiro<i>sm_io</i> a different set of functions can be specified with each 2840266059SGregory Neil Shapiroactive file for read's, write's, etc. These different function sets 2940266059SGregory Neil Shapiroare identified as <b>file types</b> (see <tt>sm_io_open()</tt>). Each function 3040266059SGregory Neil Shapiroset can handle the actions directly, pass the action request to 3140266059SGregory Neil Shapiroanother function set or do some work before passing it on to another function 3240266059SGregory Neil Shapiroset. The setting of a function set for a file type can be done for 3340266059SGregory Neil Shapiroa file type at any time (even after the type is open). 3440266059SGregory Neil Shapiro</p> 3540266059SGregory Neil Shapiro<p> 3640266059SGregory Neil ShapiroA second difference is the use of <a href="rpool.html"><b>rpools</b></a>. 3740266059SGregory Neil ShapiroAn <b>rpool</b> is specified with the opening of a file 3840266059SGregory Neil Shapiro(<tt>sm_io_open()</tt>). 3940266059SGregory Neil ShapiroThis allows of a file to be associated with an rpool so that when the 4040266059SGregory Neil Shapirorpool is released the open file will be closed; the <tt>sm_io_open()</tt> 4140266059SGregory Neil Shapiroregisters that <tt>sm_io_close()</tt> should be called when the rpool is 4240266059SGregory Neil Shapiroreleased. 4340266059SGregory Neil Shapiro</p> 4440266059SGregory Neil Shapiro<p> 4540266059SGregory Neil ShapiroA third difference is that the I/O functions take a <i>timeout</i> 4640266059SGregory Neil Shapiroargument. This allows the setting of a maximum amount of time allowable 4740266059SGregory Neil Shapirofor the I/O to be completed. This means the calling program does not need 4840266059SGregory Neil Shapiroto setup it's own timeout mechanism. NOTE: SIGALRM's should not be 4940266059SGregory Neil Shapiroactive in the calling program when an I/O function with a <i>timeout</i> 5040266059SGregory Neil Shapirois used. 5140266059SGregory Neil Shapiro</p> 5240266059SGregory Neil Shapiro<p> 5340266059SGregory Neil ShapiroWhen converting source code from <i>stdio</i> to <i>sm_io</i> be 5440266059SGregory Neil Shapirovery careful to NOTE: the arguments to functions have been rationalized. 5540266059SGregory Neil ShapiroThat is, unlike <i>stdio</i>, all <i>sm_io</i> functions that 5640266059SGregory Neil Shapirotake a file pointer (SM_FILE_T *) argument have the file pointer 5740266059SGregory Neil Shapiroas the first argument. Also not all functions with <i>stdio</i> have 5840266059SGregory Neil Shapiroan identical matching <i>sm_io</i> API: the API list has been thinned 5940266059SGregory Neil Shapirosince a number of <i>stdio</i> API's overlapped in functionality. 6040266059SGregory Neil ShapiroRemember many functions also have a <i>timeout</i> argument added. 6140266059SGregory Neil Shapiro</p> 6240266059SGregory Neil Shapiro<p> 6340266059SGregory Neil ShapiroWhen a file is going to be opened, the file type is included with 6440266059SGregory Neil Shapiro<tt>sm_io_open()</tt>. 6540266059SGregory Neil ShapiroA file type is either one automatically included with the <i>sm_io</i> 6640266059SGregory Neil Shapirolibrary or one created by the program at runtime. 6740266059SGregory Neil ShapiroFile types can be either buffered or unbuffered. When buffered the buffering 6840266059SGregory Neil Shapirois either the builtin <i>sm_io</i> buffering or as done by the file type. 6940266059SGregory Neil ShapiroFile types can be disk files, strings, TCP/IP connections or whatever 7040266059SGregory Neil Shapiroyour imagination can come up with that can be read and/or written to. 7140266059SGregory Neil Shapiro</p> 7240266059SGregory Neil Shapiro<p> 7340266059SGregory Neil ShapiroInformation about a particular file type or pointer can be obtained or set with 7440266059SGregory Neil Shapirothe <i>sm_io</i> "info" functions. 7540266059SGregory Neil ShapiroThe <tt>sm_io_setinfo()</tt> and <tt>sm_io_getinfo()</tt> functions work on 7640266059SGregory Neil Shapiroan active file pointer. 7740266059SGregory Neil Shapiro</p> 7840266059SGregory Neil Shapiro<h2>Include files</h2> 7940266059SGregory Neil Shapiro<p> 8040266059SGregory Neil ShapiroThere is one main include file for use with sm_io: <i>io.h</i>. Since the 8140266059SGregory Neil Shapirouse of <b>rpools</b> is specified with <tt>sm_io_open()</tt> an 8240266059SGregory Neil Shapiro<b>rpool</b> may 8340266059SGregory Neil Shapirobe created and thus <i>rpool.h</i> may need to be included as well 8440266059SGregory Neil Shapiro(before io.h). 8540266059SGregory Neil Shapiro</p> 8640266059SGregory Neil Shapiro<pre> 8740266059SGregory Neil Shapiro#include <rpool.h> 8840266059SGregory Neil Shapiro#include <io.h> 8940266059SGregory Neil Shapiro</pre> 9040266059SGregory Neil Shapiro 9140266059SGregory Neil Shapiro<h2>Functions/API's</h2> 9240266059SGregory Neil Shapiro<p> 9340266059SGregory Neil ShapiroBelow is a list of the functions for <i>sm_io</i> listed in 9440266059SGregory Neil Shapiroalphabetical order. Currently these functions return error codes 9540266059SGregory Neil Shapiroand set errno when appropriate. These (may?/will?) change to 9640266059SGregory Neil Shapiroraising exceptions later. 9740266059SGregory Neil Shapiro</p> 9840266059SGregory Neil Shapiro<pre> 9940266059SGregory Neil Shapiro<a href="#sm_io_autoflush">SM_FILE_T *sm_io_autoflush(SM_FILE_T *fp, SM_FILE_T *)</a> 10040266059SGregory Neil Shapiro 10140266059SGregory Neil Shapiro<a href="#sm_io_automode">void sm_io_automode(SM_FILE_T *fp, SM_FILE_T *)</a> 10240266059SGregory Neil Shapiro 10340266059SGregory Neil Shapiro<a href="#defaultapi">void sm_io_clearerr(SM_FILE_T *fp)</a> 10440266059SGregory Neil Shapiro 10540266059SGregory Neil Shapiro<a href="#sm_io_close">int sm_io_close(SM_FILE_T *fp, int timeout)</a> 10640266059SGregory Neil Shapiro 10740266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_dup(SM_FILE_T *fp)</a> 10840266059SGregory Neil Shapiro 10940266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_eof(SM_FILE_T *fp)</a> 11040266059SGregory Neil Shapiro 11140266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_error(SM_FILE_T *fp)</a> 11240266059SGregory Neil Shapiro 11340266059SGregory Neil Shapiro<a href="#defaultapi">char * sm_io_fgets(SM_FILE_T *fp, int timeout, char *buf, int n)</a> 11440266059SGregory Neil Shapiro 11540266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_flush(SM_FILE_T *fp, int timeout)</a> 11640266059SGregory Neil Shapiro 11740266059SGregory Neil Shapiro<a href="#sm_io_fopen">int sm_io_fopen(char *pathname, int flags [, MODE_T mode])</a> 11840266059SGregory Neil Shapiro 11940266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_fprintf(SM_FILE_T *fp, int timeout, const char *fmt, ...)</a> 12040266059SGregory Neil Shapiro 12140266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_fputs(s, int, SM_FILE_T *fp)</a> 12240266059SGregory Neil Shapiro 12340266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_fscanf(SM_FILE_T *fp, int timeout, char const *fmt, ...) </a> 12440266059SGregory Neil Shapiro 12540266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_getc(SM_FILE_T *fp, int timeout)</a> 12640266059SGregory Neil Shapiro 12740266059SGregory Neil Shapiro<a href="#sm_io_getinfo">void sm_io_getinfo(SM_FILE_T *sfp, int what, void *valp)</a> 12840266059SGregory Neil Shapiro 12940266059SGregory Neil Shapiro<a href="#sm_io_open">SM_FILE_T * sm_io_open(SM_FILE_T type, int timeout, void *info, int flags, void *rpool)</a> 13040266059SGregory Neil Shapiro 13140266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_purge(SM_FILE_T *fp)</a> 13240266059SGregory Neil Shapiro 13340266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_putc(SM_FILE_T *fp, int timeout, int c)</a> 13440266059SGregory Neil Shapiro 13540266059SGregory Neil Shapiro<a href="#defaultapi">size_t sm_io_read(SM_FILE_T *fp, int timeout, char *buf, size_t size)</a> 13640266059SGregory Neil Shapiro 13740266059SGregory Neil Shapiro<a href="#sm_io_reopen">SM_FILE_T * sm_io_open(SM_FILE_T type, int timeout, void *info, int flags, void *rpool)</a> 13840266059SGregory Neil Shapiro 13940266059SGregory Neil Shapiro<a href="#defaultapi">void sm_io_rewind(SM_FILE_T *fp, int timeout)</a> 14040266059SGregory Neil Shapiro 14140266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_seek(SM_FILE_T *fp, off_t offset, int timeout, int whence)</a> 14240266059SGregory Neil Shapiro 14340266059SGregory Neil Shapiro<a href="#sm_io_setinfo">void sm_io_setinfo(SM_FILE_T *sfp, int what, void *valp)</a> 14440266059SGregory Neil Shapiro 14540266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_setvbuf(SM_FILE_T *fp, int timeout, char *buf, int mode, size_t size)</a> 14640266059SGregory Neil Shapiro 14740266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_sscanf(const char *str, char const *fmt, ...)</a> 14840266059SGregory Neil Shapiro 14940266059SGregory Neil Shapiro<a href="#defaultapi">long sm_io_tell(SM_FILE_T *fp, int timeout)</a> 15040266059SGregory Neil Shapiro 15140266059SGregory Neil Shapiro<a href="#defaultapi">int sm_io_ungetc(SM_FILE_T *fp, int timeout, int c)</a> 15240266059SGregory Neil Shapiro 15340266059SGregory Neil Shapiro<a href="#defaultapi">size_t sm_io_write(SM_FILE_T *fp, int timeout, char *buf, size_t size)</a> 15440266059SGregory Neil Shapiro 15540266059SGregory Neil Shapiro<a href="#defaultapi">int sm_snprintf(char *str, size_t n, char const *fmt, ...)</a> 15640266059SGregory Neil Shapiro 15740266059SGregory Neil Shapiro</pre> 1585b0945b5SGregory Neil Shapiro<h2><a name="timeouts">Timeouts</a></h2> 15940266059SGregory Neil Shapiro<p> 16040266059SGregory Neil ShapiroFor many of the functions a <i>timeout</i> argument is given. This limits 16140266059SGregory Neil Shapirothe amount of time allowed for the function to complete. There are three 16240266059SGregory Neil Shapiropre-defined values: 16340266059SGregory Neil Shapiro<menu> 16440266059SGregory Neil Shapiro<li> 16540266059SGregory Neil ShapiroSM_TIME_DEFAULT - timeout using the default setting for this file type 16640266059SGregory Neil Shapiro</li> 16740266059SGregory Neil Shapiro<li> 16840266059SGregory Neil ShapiroSM_TIME_FOREVER - timeout will take forever; blocks until task completed 16940266059SGregory Neil Shapiro</li> 17040266059SGregory Neil Shapiro<li> 17140266059SGregory Neil ShapiroSM_TIME_IMMEDIATE - timeout (virtually) now 17240266059SGregory Neil Shapiro</li> 17340266059SGregory Neil Shapiro</menu> 17440266059SGregory Neil Shapiro</p> 17540266059SGregory Neil Shapiro<p> 17640266059SGregory Neil ShapiroA function caller can also specify a positive integer value in milliseconds. 17740266059SGregory Neil ShapiroA function will return with <i>errno</i> set to EINVAL if a bad value 17840266059SGregory Neil Shapirois given for <i>timeout</i>. 17940266059SGregory Neil ShapiroWhen a function times out the function returns in error with <i>errno</i> 18040266059SGregory Neil Shapiroset to <b>EAGAIN</b>. In the future this may change to an exception being 18140266059SGregory Neil Shapirothrown. 18240266059SGregory Neil Shapiro</p> 18340266059SGregory Neil Shapiro<h2>Function Descriptions</h2> 18440266059SGregory Neil Shapiro<dl> 18540266059SGregory Neil Shapiro<!-- SM_IO_FOPEN --> 18640266059SGregory Neil Shapiro<p></p> 18740266059SGregory Neil Shapiro<dt><tt><a name="sm_io_fopen"> 18840266059SGregory Neil ShapiroSM_FILE_T * 18940266059SGregory Neil Shapiro<br> 19040266059SGregory Neil Shapirosm_io_fopen(char *pathname, int flags) 19140266059SGregory Neil Shapiro<br> 19240266059SGregory Neil ShapiroSM_FILE_T * 19340266059SGregory Neil Shapiro<br> 19440266059SGregory Neil Shapirosm_io_fopen(char *pathname, int flags, MODE_T mode) 19540266059SGregory Neil Shapiro</a></tt></dt> 19640266059SGregory Neil Shapiro<dd> 19740266059SGregory Neil ShapiroOpen the file named by <tt>pathname</tt>, and associate a stream with it. 19840266059SGregory Neil ShapiroThe arguments are the same as for the <tt>open(2)</tt> system call. 19940266059SGregory Neil Shapiro<br> 20040266059SGregory Neil ShapiroIf memory could not be allocated, an exception is raised. 20140266059SGregory Neil ShapiroIf successful, an <tt>SM_FILE_T</tt> pointer is returned. 20240266059SGregory Neil ShapiroOtherwise, <tt>NULL</tt> is returned and <tt>errno</tt> is set. 20340266059SGregory Neil Shapiro<!-- SM_IO_OPEN --> 20440266059SGregory Neil Shapiro<p></p> 20540266059SGregory Neil Shapiro<dt><tt><a name="sm_io_open"> 20640266059SGregory Neil ShapiroSM_FILE_T * 20740266059SGregory Neil Shapiro<br> 20840266059SGregory Neil Shapirosm_io_open(const SM_FILE_T *type, int timeout, const void *info, int flags, void *rpool) 20940266059SGregory Neil Shapiro</a></tt></dt> 21040266059SGregory Neil Shapiro<dd> 21140266059SGregory Neil ShapiroOpens a file by <i>type</i> directed by <i>info</i>. <i>Type</i> is a filled-in 21240266059SGregory Neil ShapiroSM_FILE_T structure from the following builtin list 21340266059SGregory Neil Shapiro(<a href="#builtins"><b>descriptions below</b></a>) 21440266059SGregory Neil Shapiroor one specified by the program. 21540266059SGregory Neil Shapiro<menu> 21640266059SGregory Neil Shapiro<li> 21740266059SGregory Neil ShapiroSmFtString 21840266059SGregory Neil Shapiro</li> 21940266059SGregory Neil Shapiro<li> 22040266059SGregory Neil ShapiroSmFtStdio 22140266059SGregory Neil Shapiro</li> 22240266059SGregory Neil Shapiro<li> 22340266059SGregory Neil ShapiroSmFtStdiofd 22440266059SGregory Neil Shapiro</li> 22540266059SGregory Neil Shapiro<li> 22640266059SGregory Neil Shapirosmioin <b>*</b> 22740266059SGregory Neil Shapiro</li> 22840266059SGregory Neil Shapiro<li> 22940266059SGregory Neil Shapirosmioout <b>*</b> 23040266059SGregory Neil Shapiro</li> 23140266059SGregory Neil Shapiro<li> 23240266059SGregory Neil Shapirosmioerr <b>*</b> 23340266059SGregory Neil Shapiro</li> 23440266059SGregory Neil Shapiro<li> 23540266059SGregory Neil Shapirosmiostdin <b>*</b> 23640266059SGregory Neil Shapiro</li> 23740266059SGregory Neil Shapiro<li> 23840266059SGregory Neil Shapirosmiostdout <b>*</b> 23940266059SGregory Neil Shapiro</li> 24040266059SGregory Neil Shapiro<li> 24140266059SGregory Neil Shapirosmiostderr <b>*</b> 24240266059SGregory Neil Shapiro</li> 24340266059SGregory Neil Shapiro<li> 24440266059SGregory Neil ShapiroSmFtSyslog 24540266059SGregory Neil Shapiro</li> 24640266059SGregory Neil Shapiro</menu> 24740266059SGregory Neil Shapiro<br> 24840266059SGregory Neil ShapiroThe above list of file types are already appropriately filled in. Those marked 24940266059SGregory Neil Shapirowith a "<b>*</b>" are already open and may be used directly and immediately. 25040266059SGregory Neil ShapiroFor program specified types, to set the <i>type</i> argument easily and with minimal error the macro 25140266059SGregory Neil Shapiro<b>SM_IO_SET_TYPE</b> should be used. The SM_FILE_T structure is fairly 25240266059SGregory Neil Shapirolarge, but only a small portion of it need to be initialized for a new 25340266059SGregory Neil Shapirotype. 25440266059SGregory Neil ShapiroSee also <a href="#writefunctions">"Writing Functions for a File Type"</a>. 25540266059SGregory Neil Shapiro<menu> 25640266059SGregory Neil Shapiro<pre> 25740266059SGregory Neil ShapiroSM_IO_SET_TYPE(type, name, open, close, read, write, seek, get, set, timeout) 25840266059SGregory Neil Shapiro</pre> 25940266059SGregory Neil Shapiro</menu> 26040266059SGregory Neil Shapiro<br> 26140266059SGregory Neil Shapiro<i>Timeout</i> is set as described in the <a href="#timeouts"><b>Timeouts</b></a> 26240266059SGregory Neil Shapirosection. 26340266059SGregory Neil Shapiro<br> 26440266059SGregory Neil Shapiro<i>Info</i> is information that describes for the file type what is 26540266059SGregory Neil Shapiroto be opened and any associated information. 26640266059SGregory Neil ShapiroFor a disk file this would be a file path; with a TCP 26740266059SGregory Neil Shapiroconnection this could be an a structure containing an IP address and port. 26840266059SGregory Neil Shapiro<br><i>Flags</i> is a 26940266059SGregory Neil Shapiroset of sm_io flags that describes how the file is to be interacted with: 27040266059SGregory Neil Shapiro<menu> 27140266059SGregory Neil Shapiro<li> 27240266059SGregory Neil ShapiroSM_IO_RDWR - read and write 27340266059SGregory Neil Shapiro</li> 27440266059SGregory Neil Shapiro<li> 27540266059SGregory Neil ShapiroSM_IO_RDONLY - read only 27640266059SGregory Neil Shapiro</li> 27740266059SGregory Neil Shapiro<li> 27840266059SGregory Neil ShapiroSM_IO_WRONLY - write only 27940266059SGregory Neil Shapiro</li> 28040266059SGregory Neil Shapiro<li> 28140266059SGregory Neil ShapiroSM_IO_APPEND - allow write to EOF only 28240266059SGregory Neil Shapiro</li> 28340266059SGregory Neil Shapiro<li> 28440266059SGregory Neil ShapiroSM_IO_APPENDRW - allow read-write from EOF only 28540266059SGregory Neil Shapiro</li> 28640266059SGregory Neil Shapiro<li> 28740266059SGregory Neil ShapiroSM_IO_RDWRTR - read and write with truncation of file first 28840266059SGregory Neil Shapiro</li> 28940266059SGregory Neil Shapiro</menu> 29040266059SGregory Neil Shapiro<i>Rpool</i> is the address of the rpool that this open is to be associated 29140266059SGregory Neil Shapirowith. When the rpool is released then the close function for this 29240266059SGregory Neil Shapirofile type will be automatically called to close the file for cleanup. 29340266059SGregory Neil ShapiroIf NULL is specified for <i>rpool</i> then the close function is not 29440266059SGregory Neil Shapiroassociated (attached) to an rpool. 29540266059SGregory Neil Shapiro<br> 29640266059SGregory Neil ShapiroOn cannot allocate memory, an exception is raised. 29740266059SGregory Neil ShapiroIf the <i>type</i> is invalid, <tt>sm_io_open</tt> will abort the process. 29840266059SGregory Neil ShapiroOn success an SM_FILE_T * pointer is returned. 29940266059SGregory Neil ShapiroOn failure the NULL pointer is returned and errno is set. 30040266059SGregory Neil Shapiro</dd> 30140266059SGregory Neil Shapiro<!-- SM_IO_SETINFO --> 30240266059SGregory Neil Shapiro<p></p> 30340266059SGregory Neil Shapiro<dt><tt><a name="sm_io_setinfo"> 30440266059SGregory Neil Shapiroint 30540266059SGregory Neil Shapiro<br> 30640266059SGregory Neil Shapirosm_io_setinfo(SM_FILE_T *sfp, int what, void *valp) 30740266059SGregory Neil Shapiro</a></tt></dt> 30840266059SGregory Neil Shapiro<dd> 30940266059SGregory Neil ShapiroFor the open file <i>sfp</i> set the indicated information (<i>what</i>) 31040266059SGregory Neil Shapiroto the new value <i>(valp</i>). 31140266059SGregory Neil ShapiroThis will make the change for this SM_FILE_T only. The file 31240266059SGregory Neil Shapirotype that <i>sfp</i> originally belonged to will still be 31340266059SGregory Neil Shapiroconfigured the same way (this is to prevent side-effect 31440266059SGregory Neil Shapiroto other open's of the same file type, particularly with threads). 3155b0945b5SGregory Neil ShapiroThe value of <i>what</i> will be file-type dependent since this function 31640266059SGregory Neil Shapirois one of the per file type setable functions. 31740266059SGregory Neil ShapiroOne value for <i>what</i> that is valid for all file types is 31840266059SGregory Neil ShapiroSM_WHAT_VECTORS. This sets the currently open file with a new function 31940266059SGregory Neil Shapirovector set for open, close, etc. The new values are taken from <i>valp</i> 32040266059SGregory Neil Shapiroa SM_FILE_T filled in by the used via the macro SM_IO_SET_TYPE 32140266059SGregory Neil Shapiro(see and <a href="#writefunctions"> 32240266059SGregory Neil Shapiro"Writing Functions for a File Type"</a> for more information). 32340266059SGregory Neil Shapiro<br> 32440266059SGregory Neil ShapiroOn success 0 (zero) is returned. On failure -1 is returned and errno is set. 32540266059SGregory Neil Shapiro</dd> 32640266059SGregory Neil Shapiro<!-- SM_IO_GETINFO --> 32740266059SGregory Neil Shapiro<p></p> 32840266059SGregory Neil Shapiro<dt><tt><a name="sm_io_getinfo"> 32940266059SGregory Neil Shapiroint 33040266059SGregory Neil Shapiro<br> 33140266059SGregory Neil Shapirosm_io_getinfo(SM_FILE_T *sfp, int what, void *valp) 33240266059SGregory Neil Shapiro</a></tt></dt> 33340266059SGregory Neil Shapiro<dd> 33440266059SGregory Neil ShapiroFor the open file <i>sfp</i> get the indicated information (<i>what</i>) 33540266059SGregory Neil Shapiroand place the result in <i>(valp</i>). 33640266059SGregory Neil ShapiroThis will obtain information for SM_FILE_T only and may be different than 33740266059SGregory Neil Shapirothe information for the file type it was originally opened as. 3385b0945b5SGregory Neil ShapiroThe value of <i>what</i> will be file type dependent since this function 33940266059SGregory Neil Shapirois one of the per file type setable functions. 34040266059SGregory Neil ShapiroOne value for <i>what</i> that is valid for all file types is 34140266059SGregory Neil ShapiroSM_WHAT_VECTORS. This gets from the currently open file a copy of 34240266059SGregory Neil Shapirothe function vectors and stores them in <i>valp</i> a SM_FILE_T 34340266059SGregory Neil Shapiro(see <a href="#writefunctions"> 34440266059SGregory Neil Shapiro"Writing Functions for a File Type"</a> for more information). 34540266059SGregory Neil Shapiro<br> 34640266059SGregory Neil ShapiroOn success 0 (zero) is returned. On failure -1 is returned and errno is set. 34740266059SGregory Neil Shapiro</dd> 34840266059SGregory Neil Shapiro<!-- SM_IO_AUTOFLUSH --> 34940266059SGregory Neil Shapiro<p></p> 35040266059SGregory Neil Shapiro<dt><tt><a name="sm_io_autoflush"> 35140266059SGregory Neil Shapirovoid 35240266059SGregory Neil Shapiro<br> 35340266059SGregory Neil Shapirosm_io_autoflush(SM_FILE_T *fp1, *SM_FILE_T fp2) 35440266059SGregory Neil Shapiro</a></tt></dt> 35540266059SGregory Neil Shapiro<dd> 35640266059SGregory Neil ShapiroAssociate a read of <i>fp1</i> with a data flush for <i>fp2</i>. If a read 35740266059SGregory Neil Shapiroof <i>fp1</i> discovers that there is no data available to be read, then 35840266059SGregory Neil Shapiro<i>fp2</i> will have it's data buffer flushed for writable data. It is 35940266059SGregory Neil Shapiroassumed that <i>fp1</i> is open for reading and <i>fp2</i> is open 36040266059SGregory Neil Shapirofor writing. 36140266059SGregory Neil Shapiro<br> 36240266059SGregory Neil ShapiroOn return the old file pointer associated with <i>fp1</i> for flushing 36340266059SGregory Neil Shapirois returned. A return of NULL is no an error; this merely indicates no 36440266059SGregory Neil Shapiroprevious association. 36540266059SGregory Neil Shapiro</dd> 36640266059SGregory Neil Shapiro<!-- SM_IO_AUTOMODE --> 36740266059SGregory Neil Shapiro<p></p> 36840266059SGregory Neil Shapiro<dt><tt><a name="sm_io_automode"> 36940266059SGregory Neil Shapirovoid 37040266059SGregory Neil Shapiro<br> 37140266059SGregory Neil Shapirosm_io_automode(SM_FILE_T *fp1, *SM_FILE_T fp2) 3725b0945b5SGregory Neil Shapiro<dt> 37340266059SGregory Neil Shapiro</a></tt></dt> 37440266059SGregory Neil Shapiro<dd> 37540266059SGregory Neil ShapiroAssociate the two file pointers for blocking/non-blocking mode changes. 37640266059SGregory Neil ShapiroIn the handling of timeouts <i>sm_io</i> may need to switch the mode of 37740266059SGregory Neil Shapiroa file between blocking and non-blocking. If the underlying file descriptor 37840266059SGregory Neil Shapirohas been duplicated with <tt>dup(2)</tt> and these descriptors are used 37940266059SGregory Neil Shapiroby <i>sm_io</i> (for example with an SmFtStdiofd file type), then this API 38040266059SGregory Neil Shapiroshould be called to associate them. Otherwise odd behavior (i.e. errors) 3815b0945b5SGregory Neil Shapiromay result that is not consistently reproducible nor easily identifiable. 38240266059SGregory Neil Shapiro</dd> 38340266059SGregory Neil Shapiro<!-- SM_IO_CLOSE --> 38440266059SGregory Neil Shapiro<p></p> 38540266059SGregory Neil Shapiro<dt><tt><a name="sm_io_close"> 38640266059SGregory Neil Shapiroint 38740266059SGregory Neil Shapiro<br> 38840266059SGregory Neil Shapirosm_io_close(SM_FILE_T *sfp, int timeout) 38940266059SGregory Neil Shapiro</a></tt></dt> 39040266059SGregory Neil Shapiro<dd> 39140266059SGregory Neil ShapiroRelease all resources (file handles, memory, etc.) associated with 39240266059SGregory Neil Shapirothe open SM_FILE_T <i>sfp</i>. If buffering is active then the 39340266059SGregory Neil Shapirobuffer is flushed before any resources are released. 39440266059SGregory Neil Shapiro<i>Timeout</i> is set as described in the <a href="#timeouts"><b>Timeouts</b></a> 39540266059SGregory Neil Shapirosection. 39640266059SGregory Neil ShapiroThe first resources released after buffer flushing will be the 39740266059SGregory Neil Shapirobuffer itself. Then the <b>close</b> function specified in the 39840266059SGregory Neil Shapirofile type at open will be called. It is the responsibility 39940266059SGregory Neil Shapiroof the <b>close</b> function to release any file type 40040266059SGregory Neil Shapirospecific resources allocated and to call <tt>sm_io_close()</tt> 40140266059SGregory Neil Shapirofor the next file type layer(s) that the current file type uses (if any). 40240266059SGregory Neil Shapiro<br> 40340266059SGregory Neil ShapiroOn success 0 (zero) is returned. On failure SM_IO_EOF is returned and 40440266059SGregory Neil Shapiroerrno is set. 40540266059SGregory Neil Shapiro</dd> 40640266059SGregory Neil Shapiro</dl> 40740266059SGregory Neil Shapiro<h2> 40840266059SGregory Neil Shapiro<a name="builtins">Description of Builtin File Types</a> 40940266059SGregory Neil Shapiro</h2> 41040266059SGregory Neil Shapiro<p> 41140266059SGregory Neil ShapiroThere are several builtin file types as mentioned in <tt>sm_io_open()</tt>. 41240266059SGregory Neil ShapiroMore file types may be added later. 41340266059SGregory Neil Shapiro</p> 41440266059SGregory Neil Shapiro<dl> 41540266059SGregory Neil Shapiro<p></p> 41640266059SGregory Neil Shapiro<dt><tt>SmFtString</tt></dt> 41740266059SGregory Neil Shapiro<dd> 41840266059SGregory Neil ShapiroOperates on a character string. <i>SmFtString</i> is a file type only. 41940266059SGregory Neil ShapiroThe string starts at the location 0 (zero) 42040266059SGregory Neil Shapiroand ends at the last character. A read will obtain the requested 42140266059SGregory Neil Shapironumber of characters if available; else as many as possible. A read 42240266059SGregory Neil Shapirowill not terminate the read characters with a NULL ('\0'). A write 42340266059SGregory Neil Shapirowill place the number of requested characters at the current location. 42440266059SGregory Neil ShapiroTo append to a string either the pointer must currently be at the end 42540266059SGregory Neil Shapiroof the string or a seek done to position the pointer. The file type 42640266059SGregory Neil Shapirohandles the space needed for the string. Thus space needed for the 42740266059SGregory Neil Shapirostring will be grown automagically without the user worrying about 42840266059SGregory Neil Shapirospace management. 42940266059SGregory Neil Shapiro</dd> 43040266059SGregory Neil Shapiro<dt><tt>SmFtStdio</tt></dt> 43140266059SGregory Neil Shapiro<dd> 43240266059SGregory Neil ShapiroA predefined SM_FILE_T structure with function vectors pointing to 43340266059SGregory Neil Shapirofunctions that result in the file-type behaving as the system stdio 43440266059SGregory Neil Shapironormally does. The <i>info</i> portion of the <tt>sm_io_open</tt> 43540266059SGregory Neil Shapirois the path of the file to be opened. Note that this file type 43640266059SGregory Neil Shapirodoes not interact with the system's stdio. Thus a program mixing system 43740266059SGregory Neil Shapirostdio and sm_io stdio (SmFtStdio) will result in uncoordinated input 43840266059SGregory Neil Shapiroand output. 43940266059SGregory Neil Shapiro</dd> 44040266059SGregory Neil Shapiro<dt><tt>SmFtStdiofd</tt></dt> 44140266059SGregory Neil Shapiro<dd> 44240266059SGregory Neil ShapiroA predefined SM_FILE_T structure with function vectors pointing to 44340266059SGregory Neil Shapirofunctions that result in the file-type behaving as the system stdio 44440266059SGregory Neil Shapironormally does. The <i>info</i> portion of the <tt>sm_io_open</tt> 44540266059SGregory Neil Shapirois a file descriptor (the value returned by open(2)). Note that this file type 44640266059SGregory Neil Shapirodoes not interact with the system's stdio. Thus a program mixing system 44740266059SGregory Neil Shapirostdio and sm_io stdio (SmFtStdio) will result in uncoordinated input 44840266059SGregory Neil Shapiroand output. 44940266059SGregory Neil Shapiro</dd> 45040266059SGregory Neil Shapiro<dt><tt>smioin</tt></dt> 45140266059SGregory Neil Shapiro<dt><tt>smioout</tt></dt> 45240266059SGregory Neil Shapiro<dt><tt>smioerr</tt></dt> 45340266059SGregory Neil Shapiro<dd> 45440266059SGregory Neil ShapiroThe three types <i>smioin</i>, <i>smioout</i> and <i>smioerr</i> are grouped 45540266059SGregory Neil Shapirotogether. These three types 45640266059SGregory Neil Shapiroperform in the same manner as <b>stdio</b>'s <i>stdin</i>, <i>stdout</i> 45740266059SGregory Neil Shapiroand <i>stderr</i>. These types are both the names and the file pointers. 4585b0945b5SGregory Neil ShapiroThey are already open when a program starts (unless the parent explicitly 45940266059SGregory Neil Shapiroclosed file descriptors 0, 1 and 2). 46040266059SGregory Neil ShapiroThus <tt>sm_io_open()</tt> should never be called for these types: 46140266059SGregory Neil Shapirothe named file pointers should be used directly. 46240266059SGregory Neil Shapiro<i>Smioin</i> and <i>smioout</i> are buffered 46340266059SGregory Neil Shapiroby default. <i>Smioerr</i> is not buffered by default. Calls to <b>stdio</b> 46440266059SGregory Neil Shapiroare safe to make when using these three<b>sm_io</b> file pointers. 46540266059SGregory Neil ShapiroThere is no interaction between <b>sm_io</b> and <b>stdio</b>. Hence, 46640266059SGregory Neil Shapirodue to buffering, the sequence of input and output data from both <b>sm_io</b> 46740266059SGregory Neil Shapiroand <b>stdio</b> at the same time may appear unordered. For 46840266059SGregory Neil Shapirocoordination between <b>sm_io</b> and <b>stdio</b> use the three 46940266059SGregory Neil Shapirofile pointers below (<i>smiostdin, smiostdout, smiostderr</i>). 47040266059SGregory Neil Shapiro</dd> 47140266059SGregory Neil Shapiro<dt><tt>smiostdin</tt></dt> 47240266059SGregory Neil Shapiro<dt><tt>smiostdout</tt></dt> 47340266059SGregory Neil Shapiro<dt><tt>smiostderr</tt></dt> 47440266059SGregory Neil Shapiro<dd> 47540266059SGregory Neil ShapiroThe three types <i>smiostdin</i>, <i>smioostdut</i> and <i>smiostderr</i> 47640266059SGregory Neil Shapiroare grouped together. These three types 47740266059SGregory Neil Shapiroperform in the same manner as <b>stdio</b>'s <i>stdin</i>, <i>stdout</i> 47840266059SGregory Neil Shapiroand <i>stderr</i>. These types are both the names and file pointers. 4795b0945b5SGregory Neil ShapiroThey are already open when a program starts (unless the parent explicitly 48040266059SGregory Neil Shapiroclose file descriptors 0, 1 and 2). 48140266059SGregory Neil ShapiroThus <tt>sm_io_open()</tt> should 48240266059SGregory Neil Shapironever be called: the named file pointers should be used directly. 48340266059SGregory Neil ShapiroCalls to <b>stdio</b> are safe to make when using these three<b>sm_io</b> 484*d39bd2c1SGregory Neil Shapirofile pointers though no code is shared between the two libraries. 48540266059SGregory Neil ShapiroHowever, the input and output between <i>sm_io</i> and <i>stdio</i> is 48640266059SGregory Neil Shapirocoordinated for these three file pointers: <i>smiostdin</i>, 48740266059SGregory Neil Shapiro<i>smiostdout</i> and <i>smiostderr</i> are layered on-top-of 48840266059SGregory Neil Shapirothe system's <i>stdio</i>. 48940266059SGregory Neil Shapiro<i>Smiostdin</i>, <i>smiostdout</i> 49040266059SGregory Neil Shapiroand <i>Smiostderr</i> are not buffered by default. 49140266059SGregory Neil ShapiroHence, due to buffering in <i>stdio</i> only, the sequence of input and 49240266059SGregory Neil Shapirooutput data from both <b>sm_io</b> and <b>stdio</b> at the same time will 49340266059SGregory Neil Shapiroappear ordered. If <i>sm_io</i> buffering is turned on then the 49440266059SGregory Neil Shapiroinput and output can appear unordered or lost. 49540266059SGregory Neil Shapiro</dd> 49640266059SGregory Neil Shapiro<dt><tt>SmFtSyslog</tt></dt> 49740266059SGregory Neil Shapiro<dd> 49840266059SGregory Neil ShapiroThis opens the channel to the system log. Reads are not allowed. Writes 49940266059SGregory Neil Shapirocannot be undone once they have left the <i>sm_io</i> buffer. 50040266059SGregory Neil ShapiroThe man pages for <tt>syslog(3)</tt> should be read for information 50140266059SGregory Neil Shapiroon syslog. 50240266059SGregory Neil Shapiro</dd> 50340266059SGregory Neil Shapiro</dl> 50440266059SGregory Neil Shapiro<p></p> 50540266059SGregory Neil Shapiro<hr> 50640266059SGregory Neil Shapiro<p></p> 50740266059SGregory Neil Shapiro<h2> 50840266059SGregory Neil Shapiro<a name="writefunctions"> 50940266059SGregory Neil ShapiroWriting Functions for a File Type 51040266059SGregory Neil Shapiro</a> 51140266059SGregory Neil Shapiro</h2> 51240266059SGregory Neil Shapiro<p> 51340266059SGregory Neil ShapiroWhen writing functions to create a file type a function needs to 51440266059SGregory Neil Shapirobe created for each function vector in the SM_FILE_T structure 51540266059SGregory Neil Shapirothat will be passed to <tt>sm_io_open()</tt> or <tt>sm_io_setinfo()</tt>. 51640266059SGregory Neil ShapiroOtherwise the setting will be rejected and <i>errno</i> set to EINVAL. 51740266059SGregory Neil ShapiroEach function should accept and handle the number and types of arguments as 51840266059SGregory Neil Shapirodescribed in the portion of the SM_FILE_T structure shown below: 51940266059SGregory Neil Shapiro</p> 52040266059SGregory Neil Shapiro<pre> 52140266059SGregory Neil Shapiro int (*open) __P((SM_FILE_T *fp, const void *, int flags, 52240266059SGregory Neil Shapiro const void *rpool)); 52340266059SGregory Neil Shapiro int (*close) __P((SM_FILE_T *fp)); 52440266059SGregory Neil Shapiro int (*read) __P((SM_FILE_T *fp, char *buf, size_t size)); 52540266059SGregory Neil Shapiro int (*write) __P((SM_FILE_T *fp, const char *buf, size_t size)); 52640266059SGregory Neil Shapiro off_t (*seek) __P((SM_FILE_T *fp, off_t offset, int whence)); 52740266059SGregory Neil Shapiro int (*getinfo) __P((SM_FILE_T *fp, int what, void *valp)); 52840266059SGregory Neil Shapiro int (*setinfo) __P((SM_FILE_T *fp, int what, void *valp)); 52940266059SGregory Neil Shapiro</pre> 53040266059SGregory Neil Shapiro<p> 53140266059SGregory Neil ShapiroThe macro SM_IO_SET_TYPE should be used to initialized an SM_FILE_T as a file 53240266059SGregory Neil Shapirotype for an <tt>sm_io_open()</tt>: 53340266059SGregory Neil Shapiro<menu> 53440266059SGregory Neil Shapiro<pre> 53540266059SGregory Neil ShapiroSM_IO_SET_TYPE(type, name, open, close, read, write, seek, get, set, timeout) 53640266059SGregory Neil Shapiro</pre> 53740266059SGregory Neil Shapiro<br> 53840266059SGregory Neil Shapirowhere: 53940266059SGregory Neil Shapiro<menu> 54040266059SGregory Neil Shapiro<li> 54140266059SGregory Neil Shapirotype - is the SM_FILE_T being filled-in 54240266059SGregory Neil Shapiro</li> 54340266059SGregory Neil Shapiro<li> 54440266059SGregory Neil Shapironame - a human readable character string for human identification purposes 54540266059SGregory Neil Shapiro</li> 54640266059SGregory Neil Shapiro<li> 54740266059SGregory Neil Shapiroopen - the vector to the open function 54840266059SGregory Neil Shapiro</li> 54940266059SGregory Neil Shapiro<li> 55040266059SGregory Neil Shapiroclose - the vector to the close function 55140266059SGregory Neil Shapiro</li> 55240266059SGregory Neil Shapiro<li> 55340266059SGregory Neil Shapiroread - the vector to the read function 55440266059SGregory Neil Shapiro</li> 55540266059SGregory Neil Shapiro<li> 55640266059SGregory Neil Shapirowrite - the vector to the write function 55740266059SGregory Neil Shapiro</li> 55840266059SGregory Neil Shapiro<li> 55940266059SGregory Neil Shapiroseek - the vector to the seek function 56040266059SGregory Neil Shapiro</li> 56140266059SGregory Neil Shapiro<li> 56240266059SGregory Neil Shapiroset - the vector to the set function 56340266059SGregory Neil Shapiro</li> 56440266059SGregory Neil Shapiro<li> 56540266059SGregory Neil Shapiroget - the vector to the get function 56640266059SGregory Neil Shapiro</li> 56740266059SGregory Neil Shapiro<li> 56840266059SGregory Neil Shapirotimeout - the default to be used for a timeout when SM_TIME_DEFAULT specified 56940266059SGregory Neil Shapiro</li> 57040266059SGregory Neil Shapiro</menu> 57140266059SGregory Neil Shapiro</menu> 57240266059SGregory Neil ShapiroYou should avoid trying to change or use the other structure members of the 57340266059SGregory Neil ShapiroSM_FILE_T. The file pointer content (internal structure members) of an active 57440266059SGregory Neil Shapirofile should only be set and observed with the "info" functions. 57540266059SGregory Neil ShapiroThe two exceptions to the above statement are the structure members 57640266059SGregory Neil Shapiro<i>cookie</i> and <i>ival</i>. <i>Cookie</i> is of type <tt>void *</tt> 577*d39bd2c1SGregory Neil Shapirowhile <i>ival</i> is of type <tt>int</tt>. 578*d39bd2c1SGregory Neil ShapiroThese two structure members exist specifically 579*d39bd2c1SGregory Neil Shapirofor your created file type to use. 580*d39bd2c1SGregory Neil ShapiroThe <i>sm_io</i> functions 581*d39bd2c1SGregory Neil Shapirowill not change or set these two structure members; 582*d39bd2c1SGregory Neil Shapiroonly specific file type will change or set these variables. 58340266059SGregory Neil Shapiro</p> 58440266059SGregory Neil Shapiro<p> 58540266059SGregory Neil ShapiroFor maintaining information privately about status for a file type the 58640266059SGregory Neil Shapiroinformation should be encapsulated in a <i>cookie</i>. A <i>cookie</i> 58740266059SGregory Neil Shapirois an opaque type that contains information that is only known to 58840266059SGregory Neil Shapirothe file type layer itself. The <i>sm_io</i> package will know 58940266059SGregory Neil Shapironothing about the contents of the <i>cookie</i>; <i>sm_io</i> only 59040266059SGregory Neil Shapiromaintains the location of the <i>cookie</i> so that it may be passed 59140266059SGregory Neil Shapiroto the functions of a file type. It is up to the file type to 59240266059SGregory Neil Shapirodetermine what to do with the <i>cookie</i>. It is the responsibility 59340266059SGregory Neil Shapiroof the file type's open to create the cookie and point the SM_FILE_T's 59440266059SGregory Neil Shapiro<i>cookie</i> at the address of the cookie. 59540266059SGregory Neil ShapiroIt is the responsibility of close to clean up 59640266059SGregory Neil Shapiroany resources that the cookie and instance of the file type have used. 59740266059SGregory Neil Shapiro</p> 59840266059SGregory Neil Shapiro<p> 59940266059SGregory Neil ShapiroFor the <i>cookie</i> to be passed to all members of a function type 60040266059SGregory Neil Shapirocleanly the location of the cookie must assigned during 60140266059SGregory Neil Shapirothe call to open. The file type functions should not attempt to 60240266059SGregory Neil Shapiromaintain the <i>cookie</i> internally since the file type may have 603*d39bd2c1SGregory Neil Shapiroseveral instances (file pointers). 60440266059SGregory Neil Shapiro</p> 60540266059SGregory Neil Shapiro<p> 60640266059SGregory Neil ShapiroThe SM_FILE_T's member <i>ival</i> may be used in a manner similar to 60740266059SGregory Neil Shapiro<i>cookie</i>. It is not to be used for maintaining the file's offset 60840266059SGregory Neil Shapiroor access status (other members do that). It is intended as a "light" 60940266059SGregory Neil Shapiroreference. 61040266059SGregory Neil Shapiro</p> 61140266059SGregory Neil Shapiro<p> 61240266059SGregory Neil ShapiroThe file type vector functions are called by the <tt>sm_io_*()</tt> 61340266059SGregory Neil Shapirofunctions after <i>sm_io</i> processing has occurred. The <i>sm_io</i> 61440266059SGregory Neil Shapiroprocessing validates SM_FILE_T's and may then handle the call entirely 61540266059SGregory Neil Shapiroitself or pass the request to the file type vector functions. 61640266059SGregory Neil Shapiro</p> 61740266059SGregory Neil Shapiro<p> 61840266059SGregory Neil ShapiroAll of the "int" functions should return -1 (minus one) on failure 61940266059SGregory Neil Shapiroand 0 (zero) or greater on success. <i>Errno</i> should be set to 62040266059SGregory Neil Shapiroprovide diagnostic information to the caller if it has not already 62140266059SGregory Neil Shapirobeen set by another function the file type function used. 62240266059SGregory Neil Shapiro</p> 62340266059SGregory Neil Shapiro<p> 62440266059SGregory Neil ShapiroExamples are a wonderful manner of clarifying details. Below is an example 62540266059SGregory Neil Shapiroof an open function. 62640266059SGregory Neil Shapiro</p> 62740266059SGregory Neil Shapiro<p> 62840266059SGregory Neil ShapiroThis shows the setup. 62940266059SGregory Neil Shapiro<menu> 63040266059SGregory Neil Shapiro<pre> 63140266059SGregory Neil ShapiroSM_FILE_T *fp; 63240266059SGregory Neil ShapiroSM_FILE_T SM_IO_SET_TYPE(vector, "my_type", myopen, myclose, myread, mywrite, 63340266059SGregory Neil Shapiro myseek, myget, myset, SM_TIME_FOREVER); 63440266059SGregory Neil Shapiro 63540266059SGregory Neil Shapirofp = sm_io_open(&vector, 1000, "data", SM_IO_RDONLY, NULL); 63640266059SGregory Neil Shapiro 63740266059SGregory Neil Shapiroif (fp == NULL) 63840266059SGregory Neil Shapiro return(-1); 63940266059SGregory Neil Shapiro</pre> 64040266059SGregory Neil ShapiroThe above code open's a file of type "my_type". The <i>info</i> is set 64140266059SGregory Neil Shapiroto a string "data". "data" may be the name of a file or have some special 64240266059SGregory Neil Shapiromeaning to the file type. For sake of the example, we will have it be 64340266059SGregory Neil Shapirothe name of a file in the home directory of the user running the program. 64440266059SGregory Neil ShapiroNow the only file type function that is dependent on this information 64540266059SGregory Neil Shapirowill be the open function. 64640266059SGregory Neil Shapiro<br> 64740266059SGregory Neil ShapiroWe have also specified read-only access (SM_IO_RDONLY) and that no <i>rpool</i> 64840266059SGregory Neil Shapirowill be used. The <i>timeout</i> has been set to 1000 milliseconds which 64940266059SGregory Neil Shapirodirects that the file and all associated setup should be done within 65040266059SGregory Neil Shapiro1000 milliseconds or return that the function erred (with errno==EAGAIN). 65140266059SGregory Neil Shapiro<pre> 65240266059SGregory Neil Shapiroint myopen(fp, info, flags, rpools) 65340266059SGregory Neil Shapiro SM_FILE_T *fp; 65440266059SGregory Neil Shapiro const void *info; 65540266059SGregory Neil Shapiro int flags; 65640266059SGregory Neil Shapiro void *rpool; 65740266059SGregory Neil Shapiro{ 65840266059SGregory Neil Shapiro /* 65940266059SGregory Neil Shapiro ** now we could do the open raw (i.e with read(2)), but we will 66040266059SGregory Neil Shapiro ** use file layering instead. We will use the <i>stdio</i> file 66140266059SGregory Neil Shapiro ** type (different than the system's stdio). 66240266059SGregory Neil Shapiro */ 66340266059SGregory Neil Shapiro struct passwd *pw; 66440266059SGregory Neil Shapiro char path[PATH_MAX]; 66540266059SGregory Neil Shapiro 66640266059SGregory Neil Shapiro pw = getpwuid(getuid()); 66740266059SGregory Neil Shapiro sm_io_snprintf(path, PATH_MAX, "%s/%s", pw->pw_dir, info); 66840266059SGregory Neil Shapiro 66940266059SGregory Neil Shapiro /* 67040266059SGregory Neil Shapiro ** Okay. Now the path pass-in has been prefixed with the 67140266059SGregory Neil Shapiro ** user's HOME directory. We'll call the regular stdio (SmFtStdio) 67240266059SGregory Neil Shapiro ** now to handle the rest of the open. 67340266059SGregory Neil Shapiro */ 67440266059SGregory Neil Shapiro fp->cookie = sm_io_open(SmFtStdio, path, flags, rpools); 67540266059SGregory Neil Shapiro if (fp->cookie == NULL) 67640266059SGregory Neil Shapiro return(-1) /* errno set by sm_io_open call */ 67740266059SGregory Neil Shapiro else 67840266059SGregory Neil Shapiro return(0); 67940266059SGregory Neil Shapiro} 68040266059SGregory Neil Shapiro</pre> 68140266059SGregory Neil ShapiroLater on when a write is performed the function <tt>mywrite</tt> will 68240266059SGregory Neil Shapirobe invoked. To match the above <tt>myopen</tt>, <tt>mywrite</tt> could 68340266059SGregory Neil Shapirobe written as: 68440266059SGregory Neil Shapiro<pre> 68540266059SGregory Neil Shapiroint mywrite(fp, buf, size) 68640266059SGregory Neil Shapiro SM_FILE_T *fp; 68740266059SGregory Neil Shapiro char *buf; 68840266059SGregory Neil Shapiro size_t size; 68940266059SGregory Neil Shapiro{ 69040266059SGregory Neil Shapiro /* 69140266059SGregory Neil Shapiro ** As an example, we can change, modify, refuse, filter, etc. 69240266059SGregory Neil Shapiro ** the content being passed through before we ask the SmFtStdio 69340266059SGregory Neil Shapiro ** to do the actual write. 69440266059SGregory Neil Shapiro ** This example is very simple and contrived, but this keeps it 69540266059SGregory Neil Shapiro ** clear. 69640266059SGregory Neil Shapiro */ 69740266059SGregory Neil Shapiro if (size == 0) 69840266059SGregory Neil Shapiro return(0); /* why waste the cycles? */ 69940266059SGregory Neil Shapiro if (*buf == 'X') 70040266059SGregory Neil Shapiro *buf = 'Y'; 70140266059SGregory Neil Shapiro 70240266059SGregory Neil Shapiro /* 70340266059SGregory Neil Shapiro ** Note that the file pointer passed to the next level is the 70440266059SGregory Neil Shapiro ** one that was stored in the cookie during the open. 70540266059SGregory Neil Shapiro */ 70640266059SGregory Neil Shapiro return(sm_io_write(fp->cookie, buf, size)); 70740266059SGregory Neil Shapiro} 70840266059SGregory Neil Shapiro</pre> 70940266059SGregory Neil ShapiroAs a thought-exercise for the fair reader: how would you modify the 71040266059SGregory Neil Shapiroabove two functions to make a "tee". That is the program will call 71140266059SGregory Neil Shapiro<tt>sm_io_open</tt> or <tt>sm_io_write</tt> and two or more files will 71240266059SGregory Neil Shapirobe opened and written to. (Hint: create a cookie to hold two or more 71340266059SGregory Neil Shapirofile pointers). 71440266059SGregory Neil Shapiro</menu> 71540266059SGregory Neil Shapiro</p> 71640266059SGregory Neil Shapiro<p></p> 71740266059SGregory Neil Shapiro<hr> 71840266059SGregory Neil Shapiro<br> 71940266059SGregory Neil Shapiro<hr> 72040266059SGregory Neil Shapiro<p></p> 72140266059SGregory Neil Shapiro<center> 72240266059SGregory Neil Shapiro<h1> 72340266059SGregory Neil Shapiro<a name="defaultapi"> 72440266059SGregory Neil Shapirolibsm sm_io default API definition 72540266059SGregory Neil Shapiro</a> 72640266059SGregory Neil Shapiro</h1> 72740266059SGregory Neil Shapiro</center> 72840266059SGregory Neil Shapiro<h2> Introduction </h2> 72940266059SGregory Neil Shapiro<p> 73040266059SGregory Neil ShapiroA number of <i>sm_io</i> API's perform similar to their <i>stdio</i> 73140266059SGregory Neil Shapirocounterparts (same name as when the "sm_io_" is removed). 73240266059SGregory Neil ShapiroOne difference between <i>sm_io</i> and <i>stdio</i> functions is that 73340266059SGregory Neil Shapiroif a "file pointer" (FILE/SM_FILE_T) 73440266059SGregory Neil Shapirois one of the arguments for the function, then it is now the first 73540266059SGregory Neil Shapiroargument. <i>Sm_io</i> is standardized so that when a file pointer is 73640266059SGregory Neil Shapiroone of the arguments to function then it will always be the first 7375b0945b5SGregory Neil Shapiroargument. Many of the <i>sm_io</i> function take a <i>timeout</i> 73840266059SGregory Neil Shapiroargument (see <a href="#timeouts"><b>Timeouts</b></a>). 73940266059SGregory Neil Shapiro</p> 74040266059SGregory Neil Shapiro<p> 74140266059SGregory Neil ShapiroThe API you have selected is one of these. Please consult the 74240266059SGregory Neil Shapiroappropriate <i>stdio</i> man page for now. 74340266059SGregory Neil Shapiro</p> 74440266059SGregory Neil Shapiro 74540266059SGregory Neil Shapiro</body> 74640266059SGregory Neil Shapiro</html> 747