| 1 | .\" Copyright (c) 1980 The Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" %sccs.include.redist.roff% |
| 5 | .\" |
| 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 |
| 21 | maintains a file |
| 22 | .Pa strings |
| 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. |
| 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 |
| 40 | string references by expressions of the form (&xstr[number]) |
| 41 | for some number. |
| 42 | An appropriate declaration of |
| 43 | .Nm xstr |
| 44 | is prepended to the file. |
| 45 | The resulting C text is placed in the file |
| 46 | .Pa x.c , |
| 47 | to then be compiled. |
| 48 | The strings from this file are placed in the |
| 49 | .Pa strings |
| 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. |
| 53 | .El |
| 54 | .Pp |
| 55 | After all components of a large program have been compiled a file |
| 56 | .Pa xs.c |
| 57 | declaring the common |
| 58 | .Nm xstr |
| 59 | space can be created by a command of the form |
| 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 |
| 67 | of the program. |
| 68 | If possible, the array can be made read-only (shared) saving |
| 69 | space and swap overhead. |
| 70 | .Pp |
| 71 | .Nm Xstr |
| 72 | can also be used on a single file. |
| 73 | A command |
| 74 | .Bd -literal -offset indent |
| 75 | xstr name |
| 76 | .Ed |
| 77 | .Pp |
| 78 | creates files |
| 79 | .Pa x.c |
| 80 | and |
| 81 | .Pa xs.c |
| 82 | as before, without using or affecting any |
| 83 | .Pa strings |
| 84 | file in the same directory. |
| 85 | .Pp |
| 86 | It may be useful to run |
| 87 | .Nm xstr |
| 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. |
| 91 | An appropriate command sequence for running |
| 92 | .Nm xstr |
| 93 | after the C preprocessor is: |
| 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 |
| 102 | does not touch the file |
| 103 | .Pa strings |
| 104 | unless new items are added, thus |
| 105 | .Xr make 1 |
| 106 | can avoid remaking |
| 107 | .Pa xs.o |
| 108 | unless truly necessary. |
| 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 |
| 124 | If a string is a suffix of another string in the data base, |
| 125 | but the shorter string is seen first by |
| 126 | .Nm xstr |
| 127 | both strings will be placed in the data base, when just |
| 128 | placing the longer one there will do. |
| 129 | .Sh HISTORY |
| 130 | The |
| 131 | .Nm |
| 132 | command appeared in |
| 133 | .Bx 3.0 . |