exstr(1) (Essential Utilities) exstr(1)
NAME
exstr - extract strings from source files
SYNOPSIS
exstr file...
exstr -e file...
exstr -r [-d] file...
DESCRIPTION
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 meanings of the options are:
-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:
file:line:position:msgfile:msgnum:string
file the name of a C-language source file
line line number in the file
position character position in the line
msgfile null
msgnum null
string 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.
7/91 Page 1
exstr(1) (Essential Utilities) exstr(1)
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 language. 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
LCMESSAGES environment variable (see environ(5)).
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/LCMESSAGES. (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.
EXAMPLES
The following examples show uses of exstr.
Assume that the file foo.c contains two strings:
main()
{
printf("This is an example\n");
printf("Hello world!\n");
}
Page 2 7/91
exstr(1) (Essential Utilities) exstr(1)
The exstr utility, invoked with the argument foo.c extracts strings
from the named file and prints them on the standard output.
exstr foo.c produces the following output:
foo.c:This is an example\n
foo.c:Hello world!\n
exstr -e foo.c > foo.stringsout produces the following output in the
file foo.stringsout:
foo.c:3:8:::This is an example\n
foo.c:4:8:::Hello world!\n
You must edit foo.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 foo.stringsout looks like after you
add this information:
foo.c:3:8:UX:1:This is an example\n
foo.c:4:8:UX:2:Hello world!\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().
exstr -r foo.c <foo.stringsout >intlfoo.c produces the following
output:
extern char *gettxt();
main()
{
printf(gettxt("UX:1", ""));
printf(gettxt("UX:2", ""));
}
exstr -rd foo.c <foo.stringsout >intlfoo.c uses the extracted strings
as a second argument to gettxt().
extern char *gettxt();
main()
{
printf(gettxt("UX:1", "This is an example\n"));
printf(gettxt("UX:2", "Hello world!\n"));
}
FILES
7/91 Page 3
exstr(1) (Essential Utilities) exstr(1)
/usr/lib/locale/locale/LCMESSAGES/*
files created by mkmsgs(1)
SEE ALSO
gettxt(1), mkmsgs(1), printf(1), srchtxt(1).
environ(5), gettxt(3C), printf(3S), setlocale(3C) in the Programmer's
Reference Manual.
DIAGNOSTICS
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.
Page 4 7/91