Annotation of src/usr.bin/xstr/xstr.1, Revision 1.6
1.6 ! aaron 1: .\" $OpenBSD: xstr.1,v 1.5 1999/06/05 01:21:52 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
1.5 aaron 39: .Os
1.1 deraadt 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
1.5 aaron 47: .Op Fl
1.1 deraadt 48: .Op Ar file
49: .Sh DESCRIPTION
1.5 aaron 50: .Nm
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
1.6 ! aaron 58: The options are as follows:
1.1 deraadt 59: .Bl -tag -width Ds
60: .It Fl
1.6 ! aaron 61: Cause
1.5 aaron 62: .Nm
1.6 ! aaron 63: to read from the standard input.
1.1 deraadt 64: .It Fl c
1.5 aaron 65: .Nm
1.1 deraadt 66: will extract the strings from the C source
67: .Ar file
68: or the standard input
69: .Pq Fl ,
70: replacing
71: string references by expressions of the form (&xstr[number])
72: for some number.
73: An appropriate declaration of
1.5 aaron 74: .Nm
1.1 deraadt 75: is prepended to the file.
76: The resulting C text is placed in the file
77: .Pa x.c ,
78: to then be compiled.
79: The strings from this file are placed in the
80: .Pa strings
81: data base if they are not there already.
82: Repeated strings and strings which are suffixes of existing strings
83: do not cause changes to the data base.
84: .It Fl l Ar array
85: Specify the named array in program references to abstracted
86: strings. The default array name is xstr.
87: .El
88: .Pp
89: After all components of a large program have been compiled a file
90: .Pa xs.c
91: declaring the common
1.5 aaron 92: .Nm
1.1 deraadt 93: space can be created by a command of the form
94: .Bd -literal -offset indent
95: xstr
96: .Ed
97: .Pp
98: The file
99: .Pa xs.c
100: should then be compiled and loaded with the rest
101: of the program.
102: If possible, the array can be made read-only (shared) saving
103: space and swap overhead.
104: .Pp
1.5 aaron 105: .Nm
1.1 deraadt 106: can also be used on a single file.
107: A command
108: .Bd -literal -offset indent
109: xstr name
110: .Ed
111: .Pp
112: creates files
113: .Pa x.c
114: and
115: .Pa xs.c
116: as before, without using or affecting any
117: .Pa strings
118: file in the same directory.
119: .Pp
120: It may be useful to run
1.5 aaron 121: .Nm
1.1 deraadt 122: after the C preprocessor if any macro definitions yield strings
123: or if there is conditional code which contains strings
124: which may not, in fact, be needed.
125: An appropriate command sequence for running
1.5 aaron 126: .Nm
1.1 deraadt 127: after the C preprocessor is:
128: .Pp
129: .Bd -literal -offset indent -compact
130: cc \-E name.c | xstr \-c \-
131: cc \-c x.c
132: mv x.o name.o
133: .Ed
134: .Pp
1.5 aaron 135: .Nm
1.1 deraadt 136: does not touch the file
137: .Pa strings
1.4 pjanzen 138: unless new items are added, so that
1.1 deraadt 139: .Xr make 1
140: can avoid remaking
141: .Pa xs.o
142: unless truly necessary.
143: .Sh FILES
144: .Bl -tag -width /tmp/xsxx* -compact
145: .It Pa strings
1.3 aaron 146: data base of strings
1.1 deraadt 147: .It Pa x.c
1.3 aaron 148: massaged C source
1.1 deraadt 149: .It Pa xs.c
150: C source for definition of array `xstr'
151: .It Pa /tmp/xs*
1.3 aaron 152: temporary file when `xstr name' doesn't touch
1.1 deraadt 153: .Pa strings
154: .El
155: .Sh SEE ALSO
156: .Xr mkstr 1
157: .Sh BUGS
158: If a string is a suffix of another string in the data base,
159: but the shorter string is seen first by
1.5 aaron 160: .Nm
1.1 deraadt 161: both strings will be placed in the data base, when just
162: placing the longer one there will do.
163: .Sh HISTORY
164: The
165: .Nm
166: command appeared in
167: .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