exstr(1) User Commands exstr(1)
exstr - extract strings from source files
exstr -e filename...
exstr -r [-d] filename...
The exstr utility is used to extract strings from C-language source files and replace them
by calls to the message retrieval function (see gettxt(3C)). This utility will extract all
character strings surrounded by double quotes, not just strings used as arguments to the
printf command or the printf routine. In the first form, exstr finds all strings in the
source files and writes them on the standard output. Each string is preceded by the source
file name and a colon (:).
The first step is to use exstr -e to extract a list of strings and save it in a file.
Next, examine this list and determine which strings can be translated and subsequently
retrieved by the message retrieval function. Then, modify this file by deleting lines that
can't be translated and, for lines that can be translated, by adding the message file
names and the message numbers as the fourth (msgfile) and fifth (msgnum) entries on a
line. The message files named must have been created by mkmsgs(1) and exist in
/usr/lib/locale/locale/LC_MESSAGES . (The directory locale corresponds to the language
in which the text strings are written; see setlocale(3C)). The message numbers used must
correspond to the sequence numbers of strings in the message files.
Now use this modified file as input to exstr -r to produce a new version of the original
C-language source file in which the strings have been replaced by calls to the message
retrieval function gettxt(). The msgfile and msgnum fields are used to construct the first
argument to gettxt(). The second argument to gettxt() is printed if the message retrieval
fails at run-time. This argument is the null string, unless the -d option is used.
This utility cannot replace strings in all instances. For example, a static initialized
character string cannot be replaced by a function call. A second example is that a string
could be in a form of an escape sequence which could not be translated. In order not to
break existing code, the files created by invoking exstr -e must be examined and lines
containing strings not replaceable by function calls must be deleted. In some cases the
code may require modifications so that strings can be extracted and replaced by calls to
the message retrieval function.
The following options are supported:
-e Extract a list of strings from the named C-language source files, with positional
information. This list is produced on standard output in the following format:
the name of a C-language source file
line number in the file
character position in the line
the extracted text string
Normally you would redirect this output into a file. Then you would edit this file
to add the values you want to use for msgfile and msgnum:
msgfile the file that contains the text strings that will replace string. A
file with this name must be created and installed in the appropriate
place by the mkmsgs(1) utility.
msgnum the sequence number of the string in msgfile.
The next step is to use exstr -r to replace strings in file.
-r Replace strings in a C-language source file with function calls to the message
retrieval function gettxt().
-d This option is used together with the -r option. If the message retrieval fails
when gettxt() is invoked at run-time, then the extracted string is printed. You
would use the capability provided by exstr on an application program that needs to
run in an international environment and have messages print in more than one lan-
guage. exstr replaces text strings with function calls that point at strings in a
message data base. The data base used depends on the run-time value of the LC_MES-
SAGES environment variable (see environ(5)).
Example 1 The following examples show uses of exstr
Assume that the file example.c contains two strings:
printf("This is an example\n");
The exstr utility, invoked with the argument example.c extracts strings from the named
file and prints them on the standard output.
example% exstr example.c
produces the following output:
example.c:This is an example\n
The exstr utility, invoked with the -e option and the argument example.c, and redirecting
output to the file example.stringsout
example% exstr -e example.c > example.stringsout
produces the following output in the file example.stringsout
example.c:3:8:::This is an example\n
You must edit example.stringsout to add the values you want to use for the msgfile and
msgnum fields before these strings can be replaced by calls to the retrieval function. If
UX is the name of the message file, and the numbers 1 and 2 represent the sequence number
of the strings in the file, here is what example.stringsout looks like after you add this
example.c:3:8:UX:1:This is an example\n
The exstr utility can now be invoked with the -r option to replace the strings in the
source file by calls to the message retrieval function gettxt().
example% exstr -r example.c <example.stringsout >intlexample.c
produces the following output:
extern char *gettxt();
The following example:
example% exstr -rd example.c <example.stringsout >intlexample.c
uses the extracted strings as a second argument to gettxt():
extern char *gettxt();
printf(gettxt("UX:1", "This is an example\n"));
printf(gettxt("UX:2", "Hello world!\n"));
files created by mkmsgs(1)
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|Availability |SUNWtoo |
gettxt(1), mkmsgs(1), printf(1), srchtxt(1), gettxt(3C), printf(3C), setlocale(3C),
The error messages produced by exstr are intended to be self-explanatory. They indicate
errors in the command line or format errors encountered within the input file.
SunOS 5.11 5 Jul 1990 exstr(1)