Annotation of src/usr.bin/xstr/xstr.1, Revision 1.4
1.4 ! pjanzen 1: .\" $OpenBSD: xstr.1,v 1.3 1998/10/30 00:24:45 aaron Exp $
1.1 deraadt 2: .\" $NetBSD: xstr.1,v 1.4 1994/11/26 09:25:22 jtc Exp $
3: .\"
4: .\" Copyright (c) 1980, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
15: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by the University of
18: .\" California, Berkeley and its contributors.
19: .\" 4. Neither the name of the University nor the names of its contributors
20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" @(#)xstr.1 8.2 (Berkeley) 12/30/93
36: .\"
37: .Dd December 30, 1993
38: .Dt XSTR 1
39: .Os BSD 3
40: .Sh NAME
41: .Nm xstr
42: .Nd "extract strings from C programs to implement shared strings"
43: .Sh SYNOPSIS
44: .Nm xstr
45: .Op Fl c
46: .Op Fl l Ar array
47: .Op Fl
48: .Op Ar file
49: .Sh DESCRIPTION
1.3 aaron 50: .Nm xstr
1.1 deraadt 51: maintains a file
52: .Pa strings
53: into which strings in component parts of a large program are hashed.
54: These strings are replaced with references to this common area.
55: This serves to implement shared constant strings, most useful if they
56: are also read-only.
57: .Pp
58: Available options:
59: .Bl -tag -width Ds
60: .It Fl
1.3 aaron 61: .Nm xstr
1.1 deraadt 62: reads from the standard input.
63: .It Fl c
1.3 aaron 64: .Nm xstr
1.1 deraadt 65: will extract the strings from the C source
66: .Ar file
67: or the standard input
68: .Pq Fl ,
69: replacing
70: string references by expressions of the form (&xstr[number])
71: for some number.
72: An appropriate declaration of
73: .Nm xstr
74: is prepended to the file.
75: The resulting C text is placed in the file
76: .Pa x.c ,
77: to then be compiled.
78: The strings from this file are placed in the
79: .Pa strings
80: data base if they are not there already.
81: Repeated strings and strings which are suffixes of existing strings
82: do not cause changes to the data base.
83: .It Fl l Ar array
84: Specify the named array in program references to abstracted
85: strings. The default array name is xstr.
86: .El
87: .Pp
88: After all components of a large program have been compiled a file
89: .Pa xs.c
90: declaring the common
91: .Nm xstr
92: space can be created by a command of the form
93: .Bd -literal -offset indent
94: xstr
95: .Ed
96: .Pp
97: The file
98: .Pa xs.c
99: should then be compiled and loaded with the rest
100: of the program.
101: If possible, the array can be made read-only (shared) saving
102: space and swap overhead.
103: .Pp
1.3 aaron 104: .Nm xstr
1.1 deraadt 105: can also be used on a single file.
106: A command
107: .Bd -literal -offset indent
108: xstr name
109: .Ed
110: .Pp
111: creates files
112: .Pa x.c
113: and
114: .Pa xs.c
115: as before, without using or affecting any
116: .Pa strings
117: file in the same directory.
118: .Pp
119: It may be useful to run
120: .Nm xstr
121: after the C preprocessor if any macro definitions yield strings
122: or if there is conditional code which contains strings
123: which may not, in fact, be needed.
124: An appropriate command sequence for running
125: .Nm xstr
126: after the C preprocessor is:
127: .Pp
128: .Bd -literal -offset indent -compact
129: cc \-E name.c | xstr \-c \-
130: cc \-c x.c
131: mv x.o name.o
132: .Ed
133: .Pp
1.3 aaron 134: .Nm xstr
1.1 deraadt 135: does not touch the file
136: .Pa strings
1.4 ! pjanzen 137: unless new items are added, so that
1.1 deraadt 138: .Xr make 1
139: can avoid remaking
140: .Pa xs.o
141: unless truly necessary.
142: .Sh FILES
143: .Bl -tag -width /tmp/xsxx* -compact
144: .It Pa strings
1.3 aaron 145: data base of strings
1.1 deraadt 146: .It Pa x.c
1.3 aaron 147: massaged C source
1.1 deraadt 148: .It Pa xs.c
149: C source for definition of array `xstr'
150: .It Pa /tmp/xs*
1.3 aaron 151: temporary file when `xstr name' doesn't touch
1.1 deraadt 152: .Pa strings
153: .El
154: .Sh SEE ALSO
155: .Xr mkstr 1
156: .Sh BUGS
157: If a string is a suffix of another string in the data base,
158: but the shorter string is seen first by
159: .Nm xstr
160: both strings will be placed in the data base, when just
161: placing the longer one there will do.
162: .Sh HISTORY
163: The
164: .Nm
165: command appeared in
166: .Bx 3.0 .
![[BACK]](/icons/back.gif){kind=icon}
Return to xstr.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / xstr