← Back to branch summary

~ubuntu-branches/ubuntu/trusty/tla/trusty

« back to all changes in this revision

Viewing changes to src/docs-hackerlab/texi/prefixes.texi

  • Committer: Bazaar Package Importer
  • Author(s): Andrew Suffield
  • Date: 2004-05-30 20:13:29 UTC
  • Revision ID: james.westby@ubuntu.com-20040530201329-mgovd2u99mkxi0hf
Tags: upstream-1.2
Import upstream version 1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/docs-hackerlab/texi/prefixes.texi
 
1
@need 3200
 
2
 
 
3
@node Naming Conventions in the Hackerlab C Library
 
4
@appendix Naming Conventions in the Hackerlab C Library
 
5
 
 
6
This appendix describes the naming conventions used in the Hackerlab
 
7
C library.
 
8
 
 
9
@menu
 
10
* C Identifiers and Macros::
 
11
* Header Files::
 
12
@end menu
 
13
 
 
14
@need 3200
 
15
 
 
16
@node C Identifiers and Macros
 
17
@section C Identifiers and Macros
 
18
 
 
19
C identifiers and macro names are divided into categories related by
 
20
functionality.  For each category, a unique @geindex category stub
 
21
@dfn{category stub} is chosen
 
22
which is an alphanumeric string.  If a category has the stub @code{STUB},
 
23
most names in that category begin with the string @code{STUB_}.  In some
 
24
cases, the name @code{STUB} is used as an identifier by itself.  If @code{STUB}
 
25
is the name of a data structure, there may be functions named
 
26
@code{make_STUB} and @code{free_STUB}.  For some data types, a @code{sizeof_STUB}
 
27
macro is defined.  Case distinctions do not matter: a stub may be
 
28
used with any combination of upper and lowercase letters.
 
29
 
 
30
 
 
31
If a name is publicly visible, but is not intended to be used outside
 
32
of the implementation of the Hackerlab C Library, it is given a prefix
 
33
of the form @code{STUB__}.
 
34
 
 
35
 
 
36
The stubs currently in use are:
 
37
 
 
38
@example
 
39
@group
 
40
        ar              dynamically sized arrays
 
41
        bits            shared bitset trees
 
42
        bits_tree       bitset trees
 
43
        bitset          flat bitsets
 
44
        char            manipulating 8-bit characters
 
45
@end group
 
46
@group
 
47
        cvt             number/string conversions
 
48
        errno           manipulating error codes
 
49
        file_name       manipulating file names
 
50
        hash            computing hash values
 
51
        hashtree        the hashtree data structure
 
52
@end group
 
53
@group
 
54
        invariant       testing invariants
 
55
        lim             limited allocation
 
56
        mem             manipulating arrays of bytes
 
57
        MACHINE         machine-specific parameters
 
58
        must            errorless allocation
 
59
@end group
 
60
@group
 
61
        opt             command line option processing
 
62
        panic           aborting programs
 
63
        path            manipulating directory search paths
 
64
        piw             the Program Instrumentation Workbench
 
65
        pow2_array      power-or-two sized sparse arrays
 
66
@end group
 
67
@group
 
68
        printfmt        formatted I/O
 
69
        reserv          reserved file descriptors
 
70
        rx              regexp pattern matching
 
71
        safe            errorless I/O functions
 
72
        str             manipulating ISO 8859-1 strings
 
73
@end group
 
74
@group
 
75
        t               fundamental typedefs (e.g. `t_uint8')
 
76
        uni             foundational Unicode support
 
77
@end group
 
78
@group
 
79
        unidata         the Unicode character database
 
80
        url             url-based virtual file systems
 
81
        vfdbuf          descriptor-based buffered I/O
 
82
        vu              virtual descriptor-based i/o
 
83
        xml             XML utilities
 
84
@end group
 
85
@group
 
86
@end group
 
87
@end example
 
88
 
 
89
There are also some exceptions.  Some versions of the library
 
90
export the Posix.2 interface for regexp pattern matching (@code{regcomp},
 
91
@code{regexec} etc.).  Some versions of the library export standard
 
92
interfaces for memory allocation (@code{malloc}, @code{free}, etc.).
 
93
 
 
94
 
 
95
 
 
96
 
 
97
@need 3200
 
98
 
 
99
@node Header Files
 
100
@section Header Files
 
101
 
 
102
Hackerlab C Library header files are always named by two directories
 
103
and a file name, as in this example:
 
104
 
 
105
@example
 
106
@group
 
107
        <hackerlab/machine/types.h>
 
108
@end group
 
109
@group
 
110
@end group
 
111
@end example
 
112
 
 
113
Every public header file can be included by itself -- without having
 
114
to include any other header file first.  Some Hackerlab header files
 
115
have the effect of including other Hackerlab header files.
 
116
 
 
117
 
 
118
Every Hackerlab header file may be safely included more than once.
 
119
A CPP macro beginning with @code{INCLUDE__} is used to protect the contents
 
120
of each header file from being interpreted more than once.  For
 
121
example, the header @code{<hackerlab/machine/types.h>} contains:
 
122
 
 
123
@example
 
124
@group
 
125
        #ifndef INCLUDE__MACHINE__TYPES_H
 
126
        #define INCLUDE__MACHINE__TYPES_H
 
127
        ...
 
128
        #endif  /* INCLUDE__MACHINE__TYPES_H */
 
129
@end group
 
130
@group
 
131
@end group
 
132
@end example
 
133
 
 
134
 
 
135
 
 
136
 
 
137
 
 
138