Annotation of src/usr.bin/xstr/xstr.1, Revision 1.10
1.10 ! mpech 1: .\" $OpenBSD: xstr.1,v 1.9 2000/12/17 21:33:02 millert 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
1.9 millert 81: database if they are not there already.
1.1 deraadt 82: Repeated strings and strings which are suffixes of existing strings
1.9 millert 83: do not cause changes to the database.
1.1 deraadt 84: .It Fl l Ar array
1.8 aaron 85: Specify the named array in program references to abstracted strings.
86: The default array name is
87: .Dq xstr .
1.1 deraadt 88: .El
89: .Pp
90: After all components of a large program have been compiled a file
91: .Pa xs.c
92: declaring the common
1.5 aaron 93: .Nm
1.1 deraadt 94: space can be created by a command of the form
95: .Bd -literal -offset indent
1.10 ! mpech 96: $ xstr
1.1 deraadt 97: .Ed
98: .Pp
99: The file
100: .Pa xs.c
101: should then be compiled and loaded with the rest
102: of the program.
103: If possible, the array can be made read-only (shared) saving
104: space and swap overhead.
105: .Pp
1.5 aaron 106: .Nm
1.1 deraadt 107: can also be used on a single file.
108: A command
109: .Bd -literal -offset indent
1.10 ! mpech 110: $ xstr name
1.1 deraadt 111: .Ed
112: .Pp
113: creates files
114: .Pa x.c
115: and
116: .Pa xs.c
117: as before, without using or affecting any
118: .Pa strings
119: file in the same directory.
120: .Pp
121: It may be useful to run
1.5 aaron 122: .Nm
1.1 deraadt 123: after the C preprocessor if any macro definitions yield strings
124: or if there is conditional code which contains strings
125: which may not, in fact, be needed.
126: An appropriate command sequence for running
1.5 aaron 127: .Nm
1.1 deraadt 128: after the C preprocessor is:
129: .Pp
130: .Bd -literal -offset indent -compact
1.10 ! mpech 131: $ cc \-E name.c | xstr \-c \-
! 132: $ cc \-c x.c
! 133: $ mv x.o name.o
1.1 deraadt 134: .Ed
135: .Pp
1.5 aaron 136: .Nm
1.1 deraadt 137: does not touch the file
138: .Pa strings
1.4 pjanzen 139: unless new items are added, so that
1.1 deraadt 140: .Xr make 1
141: can avoid remaking
142: .Pa xs.o
143: unless truly necessary.
144: .Sh FILES
145: .Bl -tag -width /tmp/xsxx* -compact
146: .It Pa strings
1.9 millert 147: database of strings
1.1 deraadt 148: .It Pa x.c
1.3 aaron 149: massaged C source
1.1 deraadt 150: .It Pa xs.c
1.8 aaron 151: C source for definition of array
152: .Dq xstr
1.1 deraadt 153: .It Pa /tmp/xs*
1.8 aaron 154: temporary file when
155: .Dq xstr name
156: doesn't touch
1.1 deraadt 157: .Pa strings
158: .El
159: .Sh SEE ALSO
160: .Xr mkstr 1
1.7 aaron 161: .Sh HISTORY
162: The
163: .Nm
164: command appeared in
165: .Bx 3.0 .
1.1 deraadt 166: .Sh BUGS
1.9 millert 167: If a string is a suffix of another string in the database,
1.1 deraadt 168: but the shorter string is seen first by
1.5 aaron 169: .Nm
1.9 millert 170: both strings will be placed in the database, when just
1.1 deraadt 171: placing the longer one there will do.
![[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