0001 File : README
0002 Author : Richard A. O'Keefe.
0003 Updated: 30 April 1984
0004 Purpose: Explain the new strings package.
0006 The UNIX string libraries (described in the string(3) manual page)
0007 differ from UNIX to UNIX (e.g. strtok is not in V7 or 4.1bsd). Worse,
0008 the sources are not in the public domain, so that if there is a string
0009 routine which is nearly what you want but not quite you can't take a
0010 copy and modify it. And of course C programmers on non-UNIX systems
0011 are at the mercy of their supplier.
0013 This package was designed to let me do reasonable things with C's
0014 strings whatever UNIX (V7, PaNiX, UX63, 4.1bsd) I happen to be using.
0015 Everything in the System III manual is here and does just what the S3
0016 manual says it does. There are also lots of new goodies. I'm sorry
0017 about the names, but the routines do have to work on asphyxiated-at-
0018 birth systems which truncate identifiers. The convention is that a
0019 routine is called
0020 str [n] [c] <operation>
0021 If there is an "n", it means that the function takes an (int) "length"
0022 argument, which bounds the number of characters to be moved or looked
0023 at. If the function has a "set" argument, a "c" in the name indicates
0024 that the complement of the set is used. Functions or variables whose
0025 names start with _ are support routines which aren't really meant for
0026 general use. I don't know what the "p" is doing in "strpbrk", but it
0027 is there in the S3 manual so it's here too. "istrtok" does not follow
0028 this rule, but with 7 letters what can you do?
0030 I have included new versions of atoi(3) and atol(3) as well. They
0031 use a new primitive str2int, which takes a pair of bounds and a radix,
0032 and does much more thorough checking than the normal atoi and atol do.
0033 The result returned by atoi & atol is valid if and only if errno == 0.
0034 There is also an output conversion routine int2str, with itoa and ltoa
0035 as interface macros. Only after writing int2str did I notice that the
0036 str2int routine has no provision for unsigned numbers. On reflection,
0037 I don't greatly care. I'm afraid that int2str may depend on your "C"
0038 compiler in unexpected ways. Do check the code with -S.
0040 Several of these routines have "asm" inclusions conditional on the
0041 VaxAsm option. These insertions can make the routines which have them
0042 quite a bit faster, but there is a snag. The VAX architects, for some
0043 reason best known to themselves and their therapists, decided that all
0044 "strings" were shorter than 2^16 bytes. Even when the length operands
0045 are in 32-bit registers, only 16 bits count. So the "asm" versions do
0046 not work for long strings. If you can guarantee that all your strings
0047 will be short, define VaxAsm in the makefile, but in general, and when
0048 using other machines, do not define it.
0050 To use this library, you need the "strings.a" library file and the
0051 "strings.h" and "ctypes.h" header files. The other header files are
0052 for compiling the library itself, though if you are hacking extensions
0053 you may find them useful. General users really shouldn't see them.
0054 I've defined a few macros I find useful in "strings.h"; if you have no
0055 need for "index", "rindex", "streql", and "beql", just edit them out.
0056 On the 4.1bsd system I am using declaring all these functions 'extern'
0057 does not mean that they will all be loaded; but only the ones you use.
0058 When using lesser systems you may find it necessary to break strings.h
0059 up, or you could get by with just adding "extern" declarations for the
0060 functions you want as you need them. Many of these functions have the
0061 same names as functions in the "standard C library", by design as this
0062 is a replacement/reimplementation of part of that library. So you may
0063 have to talk the loader into loading this library first. Again, I've
0064 found no problems on 4.1bsd.
0066 You may wonder at my failure to provide manual pages for this code.
0067 For the things in V7, 4.?, or SIII, you should be able to use whichever
0068 manual page came with that system, and anything I might write would be
0069 so like it as to raise suspicions of violating AT&T copyrights. In the
0070 sources you will find comments which provide far more documentation for
0071 these routines than AT&T ever provided for their strings stuff, I just
0072 don't happen to have put it in nroff -man form. Had I done so, the .3
0073 files would have outbulked the .c files!
0075 These files are in the public domain. This includes getopt.c, which
0076 is the work of Henry Spencer, University of Toronto Zoology, who says of
0077 it "None of this software is derived from Bell software. I had no access
0078 to the source for Bell's versions at the time I wrote it. This software
0079 is hereby explicitly placed in the public domain. It may be used for
0080 any purpose on any machine by anyone." I would greatly prefer it if *my*
0081 material received no military use.