← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to strings/README

  • Committer: brian
  • Date: 2008-06-25 05:29:13 UTC
  • Revision ID: brian@localhost.localdomain-20080625052913-6upwo0jsrl4lnapl
clean slate

Show diffs side-by-side

added added

removed removed

Lines of Context:
strings/README
 
1
File   : README
 
2
Author : Richard A. O'Keefe.
 
3
Updated: 30 April 1984
 
4
Purpose: Explain the new strings package.
 
5
 
 
6
    The UNIX string libraries (described in the string(3) manual page)
 
7
differ from UNIX to UNIX (e.g. strtok is not in V7 or 4.1bsd).  Worse,
 
8
the sources are not in the public domain, so that if there is a string
 
9
routine which is nearly what you want but not quite you can't  take  a
 
10
copy  and  modify it.  And of course C programmers on non-UNIX systems
 
11
are at the mercy of their supplier.
 
12
 
 
13
    This package was designed to let me do reasonable things with  C's
 
14
strings  whatever UNIX (V7, PaNiX, UX63, 4.1bsd) I happen to be using.
 
15
Everything in the System III manual is here and does just what the  S3
 
16
manual  says  it does.  There are also lots of new goodies.  I'm sorry
 
17
about the names, but the routines do have to work  on  asphyxiated-at-
 
18
birth  systems  which  truncate identifiers.  The convention is that a
 
19
routine is called
 
20
 str [n] [c] <operation>
 
21
If there is an "n", it means that the function takes an (int) "length"
 
22
argument, which bounds the number of characters to be moved or  looked
 
23
at.  If the function has a "set" argument, a "c" in the name indicates
 
24
that  the complement of the set is used.  Functions or variables whose
 
25
names start with _ are support routines which aren't really meant  for
 
26
general  use.  I don't know what the "p" is doing in "strpbrk", but it
 
27
is there in the S3 manual so it's here too.  "istrtok" does not follow
 
28
this rule, but with 7 letters what can you do?
 
29
 
 
30
    I have included new versions of atoi(3) and atol(3) as well.  They
 
31
use a new primitive str2int, which takes a pair of bounds and a radix,
 
32
and does much more thorough checking than the normal atoi and atol do.
 
33
The result returned by atoi & atol is valid if and only if errno == 0.
 
34
There is also an output conversion routine int2str, with itoa and ltoa
 
35
as interface macros.  Only after writing int2str did I notice that the
 
36
str2int routine has no provision for unsigned numbers.  On reflection,
 
37
I don't greatly care.   I'm afraid that int2str may depend on your "C"
 
38
compiler in unexpected ways.  Do check the code with -S.
 
39
 
 
40
    Several of these routines have "asm" inclusions conditional on the
 
41
VaxAsm option.  These insertions can make the routines which have them
 
42
quite a bit faster, but there is a snag.  The VAX architects, for some
 
43
reason best known to themselves and their therapists, decided that all
 
44
"strings" were shorter than 2^16 bytes.  Even when the length operands
 
45
are in 32-bit registers, only 16 bits count.  So the "asm" versions do
 
46
not work for long strings.  If you can guarantee that all your strings
 
47
will be short, define VaxAsm in the makefile, but in general, and when
 
48
using other machines, do not define it.
 
49
 
 
50
    To use this library, you need the "strings.a" library file and the
 
51
"strings.h" and "ctypes.h" header files.  The other header  files  are
 
52
for compiling the library itself, though if you are hacking extensions
 
53
you  may  find  them useful.  General users really shouldn't see them.
 
54
I've defined a few macros I find useful in "strings.h"; if you have no
 
55
need for "index", "rindex", "streql", and "beql", just edit them  out.
 
56
On the 4.1bsd system I am using declaring all these functions 'extern'
 
57
does not mean that they will all be loaded; but only the ones you use.
 
58
When using lesser systems you may find it necessary to break strings.h
 
59
up, or you could get by with just adding "extern" declarations for the
 
60
functions you want as you need them.  Many of these functions have the
 
61
same names as functions in the "standard C library", by design as this
 
62
is a replacement/reimplementation of part of that library.  So you may
 
63
have to talk the loader into loading this library first.   Again, I've
 
64
found no problems on 4.1bsd.
 
65
 
 
66
    You may wonder at my failure to provide manual pages for this code.
 
67
For the things in V7, 4.?, or SIII, you should be able to use whichever
 
68
manual page came with that system,  and anything I might write would be
 
69
so like it as to raise suspicions of violating AT&T copyrights.  In the
 
70
sources you will find comments which provide far more documentation for
 
71
these routines than AT&T ever provided for their strings stuff,  I just
 
72
don't happen to have put it in nroff -man form.   Had I done so, the .3
 
73
files would have outbulked the .c files!
 
74
 
 
75
    These files are in the public domain.  This includes getopt.c, which
 
76
is the work of Henry Spencer, University of Toronto Zoology, who says of
 
77
it "None of this software is derived from Bell software. I had no access
 
78
to the source for Bell's versions at the time I wrote it.  This software
 
79
is hereby explicitly placed in the public domain.  It may  be  used  for
 
80
any purpose on any machine by anyone." I would greatly prefer it if *my*
 
81
material received no military use.
 
82