1
======================================================================
2
NOTE: I use vi with a tabstop value of 3. Using the same tabstop
3
value will make the text/code look properly indented.
4
======================================================================
9
SIO is a library that provides _stream_ I/O which is what most Unix
10
programs do. As such it is a competitor to stdio.
13
2. Why would you care to use it ?
15
a. SIO is a little faster than stdio
16
b. SIO provides an easier-to-use interface (IMHO)
17
c. SIO is capable of using memory mapping for reading files if the operating
19
d. If you have a program that uses read(2)/write(2) it is trivial
20
to convert it to use SIO (just replace read with Sread and
26
3. Setting up the Stream I/O (SIO) library
28
There are 3 steps to the process:
29
1) modifying the SIO configuration file (but you can skip this
30
step if you are using one of the operating systems listed below).
32
3) installing the library and manpages
35
3.1. How to compile the Stream I/O (SIO) library
37
All the system-dependent stuff of SIO is placed in the sioconf.h file.
38
If your system is not listed below, you will need to read that file
39
to see what flags you need to set to properly compile SIO.
41
For the following systems, here is what you need to do:
44
make "DEFS=-DHAVE_MMAP -DHAVE_ONEXIT -DHAVE_MEMCPY -DHAVE_ISATTY"
46
SunOS 5.x (aka Solaris 2.y):
47
make "DEFS=-DHAVE_MMAP -DHAVE_ATEXIT -DHAVE_MEMCPY -DHAVE_ISATTY"
48
(I don't have access to a system running Solaris 2.y so I have not
52
make "DEFS=-DHAVE_MEMCPY -DHAVE_ATEXIT -DHAVE_ISATTY"
54
If your system is one of the above, then you can skip to the next subsection.
55
However, I should mention that the library compiles by default with
56
debugging enabled (i.e. uses the -g flag of cc). You can override this
57
by appending to the invocation of 'make' the argument "DEBUG=-O"
59
If your system is not among the above, then you will need to modify the
60
sioconf.h file. You do this by uncommenting the inclusion of
61
customconf.h. Then, you can override all constants/macros defined in
62
sioconf.h by defining them first in customconf.h. Please read
63
sioconf.h for more information on what constants/macros can be
66
The Makefile has a header that explains what the Makefile can do.
67
The only flag that you may want to define is -DDEBUG which enables
68
assertions in the SIO code (if an assertion fails, the program is
69
terminated with an error message that lists the SIO file and line
70
number where the error occured).
75
After you have successfully compiled SIO, you can use the programs in
76
the "suite" directory to test the SIO functions. Testing should be
77
done before installing the library.
78
The script testlib does everything; just type:
82
The script sprint_test (invoked by testlib) tests Sprint by using a variety
83
of formats and comparing its output with that of an ANSI-compatible printf.
84
At least on Ultrix 4.1 and 4.2 this test fails because printf is not
86
In such a case, you can test the rest of the SIO functions by typing:
90
(anything after the 'all' argument is interpreted as a function that
91
should not be tested).
93
The README file in the "suite" directory describes how to do a
94
few more tests that cannot be done automatically.
97
3.3. Installing the library and manpages
99
The 'make' command will create libsio.a in the current directory.
100
The Makefile includes an "install" target. Doing a 'make install' will
103
a) libsio.a will be installed in LIBDIR
104
b) the necessary SIO header files will be installed in INCLUDEDIR
105
c) the SIO man pages will be installed in MANDIR
107
LIBDIR, INCLUDEDIR, and MANDIR are Makefile variables that you can edit in
108
the Makefile or override when you invoke 'make'.
109
Here is a sample command to install SIO:
111
make install LIBDIR=/usr/local/lib INCLUDEDIR=/usr/local/include MANDIR=/usr/local/man/man3
116
Feel free to modify SIO to suit your needs. Please let me know of
119
If you want to distribute your modifications, please read the COPYRIGHT
120
file. It basically says that you are free to redistribute as long as
121
you retain the original copyright notice and you make sure that your
122
modifications are identifiable. In order to achieve this I have
123
reserved the first 3 components of the version number (for example,
124
1.4.2) and you can identify your mods by appending another component to
125
that version number (for example, 1.4.2.A2). Also, if you distribute a
126
modified version of the library, you take full responsibility for any
127
bugs in the code (not just your code; the whole thing).
added
removed
libs/src/sio/README
