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