Commit | Line | Data |
---|---|---|
1baba00f KB |
1 | .\" Copyright (c) 1980 The Regents of the University of California. |
2 | .\" All rights reserved. | |
b74e1486 | 3 | .\" |
11b71354 | 4 | .\" %sccs.include.redist.roff% |
b74e1486 | 5 | .\" |
11b71354 CL |
6 | .\" @(#)xstr.1 6.4 (Berkeley) %G% |
7 | .\" | |
8 | .Dd | |
9 | .Dt XSTR 1 | |
10 | .Os BSD 3 | |
11 | .Sh NAME | |
12 | .Nm xstr | |
13 | .Nd "extract strings from C programs to implement shared strings" | |
14 | .Sh SYNOPSIS | |
15 | .Nm xstr | |
16 | .Op Fl c | |
17 | .Op Fl | |
18 | .Op Ar file | |
19 | .Sh DESCRIPTION | |
20 | .Nm Xstr | |
b74e1486 | 21 | maintains a file |
11b71354 | 22 | .Pa strings |
b74e1486 KM |
23 | into which strings in component parts of a large program are hashed. |
24 | These strings are replaced with references to this common area. | |
25 | This serves to implement shared constant strings, most useful if they | |
26 | are also read-only. | |
11b71354 CL |
27 | .Pp |
28 | Available options: | |
29 | .Bl -tag -width Ds | |
30 | .It Fl | |
31 | .Nm Xstr | |
32 | reads from the standard input. | |
33 | .It Fl c | |
34 | .Nm Xstr | |
35 | will extract the strings from the C source | |
36 | .Ar file | |
37 | or the standard input | |
38 | .Pq Fl , | |
39 | replacing | |
b74e1486 KM |
40 | string references by expressions of the form (&xstr[number]) |
41 | for some number. | |
42 | An appropriate declaration of | |
11b71354 | 43 | .Nm xstr |
b74e1486 KM |
44 | is prepended to the file. |
45 | The resulting C text is placed in the file | |
11b71354 | 46 | .Pa x.c , |
b74e1486 KM |
47 | to then be compiled. |
48 | The strings from this file are placed in the | |
11b71354 | 49 | .Pa strings |
b74e1486 KM |
50 | data base if they are not there already. |
51 | Repeated strings and strings which are suffices of existing strings | |
52 | do not cause changes to the data base. | |
11b71354 CL |
53 | .El |
54 | .Pp | |
b74e1486 | 55 | After all components of a large program have been compiled a file |
11b71354 | 56 | .Pa xs.c |
b74e1486 | 57 | declaring the common |
11b71354 | 58 | .Nm xstr |
b74e1486 | 59 | space can be created by a command of the form |
11b71354 CL |
60 | .Bd -literal -offset indent |
61 | xstr | |
62 | .Ed | |
63 | .Pp | |
64 | The file | |
65 | .Pa xs.c | |
66 | should then be compiled and loaded with the rest | |
b74e1486 KM |
67 | of the program. |
68 | If possible, the array can be made read-only (shared) saving | |
69 | space and swap overhead. | |
11b71354 CL |
70 | .Pp |
71 | .Nm Xstr | |
b74e1486 KM |
72 | can also be used on a single file. |
73 | A command | |
11b71354 CL |
74 | .Bd -literal -offset indent |
75 | xstr name | |
76 | .Ed | |
77 | .Pp | |
b74e1486 | 78 | creates files |
11b71354 | 79 | .Pa x.c |
b74e1486 | 80 | and |
11b71354 | 81 | .Pa xs.c |
b74e1486 | 82 | as before, without using or affecting any |
11b71354 | 83 | .Pa strings |
b74e1486 | 84 | file in the same directory. |
11b71354 | 85 | .Pp |
b74e1486 | 86 | It may be useful to run |
11b71354 | 87 | .Nm xstr |
b74e1486 KM |
88 | after the C preprocessor if any macro definitions yield strings |
89 | or if there is conditional code which contains strings | |
90 | which may not, in fact, be needed. | |
b74e1486 | 91 | An appropriate command sequence for running |
11b71354 | 92 | .Nm xstr |
b74e1486 | 93 | after the C preprocessor is: |
11b71354 CL |
94 | .Pp |
95 | .Bd -literal -offset indent -compact | |
96 | cc \-E name.c | xstr \-c \- | |
97 | cc \-c x.c | |
98 | mv x.o name.o | |
99 | .Ed | |
100 | .Pp | |
101 | .Nm Xstr | |
b74e1486 | 102 | does not touch the file |
11b71354 | 103 | .Pa strings |
b74e1486 | 104 | unless new items are added, thus |
11b71354 | 105 | .Xr make 1 |
b74e1486 | 106 | can avoid remaking |
11b71354 | 107 | .Pa xs.o |
b74e1486 | 108 | unless truly necessary. |
11b71354 CL |
109 | .Sh FILES |
110 | .Bl -tag -width /tmp/xsxx* -compact | |
111 | .It Pa strings | |
112 | Data base of strings | |
113 | .It Pa x.c | |
114 | Massaged C source | |
115 | .It Pa xs.c | |
116 | C source for definition of array `xstr' | |
117 | .It Pa /tmp/xs* | |
118 | Temp file when `xstr name' doesn't touch | |
119 | .Pa strings | |
120 | .El | |
121 | .Sh SEE ALSO | |
122 | .Xr mkstr 1 | |
123 | .Sh BUGS | |
b74e1486 KM |
124 | If a string is a suffix of another string in the data base, |
125 | but the shorter string is seen first by | |
11b71354 | 126 | .Nm xstr |
b74e1486 KM |
127 | both strings will be placed in the data base, when just |
128 | placing the longer one there will do. | |
11b71354 CL |
129 | .Sh HISTORY |
130 | The | |
131 | .Nm | |
132 | command appeared in | |
133 | .Bx 3.0 . |