libs/src/sio/README

   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 ======================================================================
   5
   6
   7 1. What is SIO ?
   8
   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.
  11
  12
  13 2. Why would you care to use it ?
  14
  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
  18         system supports it.
  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
  21    write with Swrite)
  22 e. You get source
  23
  24
  25
  26 3. Setting up the Stream I/O (SIO) library
  27
  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).
  31         2) testing SIO
  32         3) installing the library and manpages
  33
  34
  35 3.1. How to compile the Stream I/O (SIO) library
  36
  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.
  40
  41 For the following systems, here is what you need to do:
  42
  43         SunOS 4.x:
  44                 make "DEFS=-DHAVE_MMAP -DHAVE_ONEXIT -DHAVE_MEMCPY -DHAVE_ISATTY"
  45
  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
  49         tested this)
  50
  51         Ultrix 4.x:
  52                 make "DEFS=-DHAVE_MEMCPY -DHAVE_ATEXIT -DHAVE_ISATTY"
  53
  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"
  58
  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
  64 defined.
  65
  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).
  71
  72
  73 3.2. Testing SIO
  74
  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:
  79
  80         testlib all
  81
  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
  85 ANSI-compatible.
  86 In such a case, you can test the rest of the SIO functions by typing:
  87
  88         testlib all Sprint
  89
  90 (anything after the 'all' argument is interpreted as a function that
  91 should not be tested).
  92
  93 The README file in the "suite" directory describes how to do a
  94 few more tests that cannot be done automatically.
  95
  96
  97 3.3. Installing the library and manpages
  98
  99 The 'make' command will create libsio.a in the current directory.
 100 The Makefile includes an "install" target. Doing a 'make install' will
 101 cause the following:
 102
 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
 106
 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:
 110
 111         make install LIBDIR=/usr/local/lib INCLUDEDIR=/usr/local/include MANDIR=/usr/local/man/man3
 112
 113
 114 4. Epilogue
 115
 116 Feel free to modify SIO to suit your needs. Please let me know of
 117 any bugs you find.
 118
 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).
 128