exstr(1) exstr(1)
NAME
exstr - extract strings from source files
SYNOPSIS
exstr [-e] file ... Format 1
exstr -r [-d] file ... Format 2
DESCRIPTION
exstr is used to extract strings from C-language source files (Format
1) and replace them by calls to a function (Format 2) that retrieves
matching strings from a message catalog at program runtime [see
gettxt(3C)]. This utility will extract all strings of one or more
printable characters surrounded by double quotes ("..."), not just
strings used as arguments to printf commands.
Format 1: Extract strings from C source files
exstr [-e] file ...
No option specified:
exstr finds all strings in the named source file and writes them
to standard output. Each string is preceded by the source file
name and a colon.
-e exstr lists the strings that it finds plus information about
their position in file. This list consists of lines made up of
the following fields:
file:line:column:msgfile:msgnum:string
file the name of the C-language source file
line line number in the file containing string
column column number at which string begins
msgfile empty field
msgnum empty field
string the extracted text string
You normally redirect the output to a file which you can
subsequently edit in order to add a message file name
and a message number to the msgfile and msgnum fields.
msgfile Name of the file containing the text strings that are to
replace the original strings in the C source files. A
file with this name must be created and installed at the
appropriate place in the file tree by using the mkmsgs
command [see mkmsgs(1)].
Page 1 Reliant UNIX 5.44 Printed 11/98
exstr(1) exstr(1)
msgnum The sequence number of the string in msgfile.
To replace strings in the source file you use the second
format of exstr.
file Name of the C source file in which exstr is to search for
strings. You may name more than one file.
Format 2: Replace strings in C source files
exstr -r [-d] file ...
-r exstr replaces each string in file with a call to the gettxt(3C)
function, which retrieves a matching string at program runtime.
-d This option must only be used together with the -r option. If the
gettxt(3C) function call fails at program runtime, the extracted
string is printed instead. This option is set by default; it is
retained to provide compatibility with other systems.
file Name of the C source file in which exstr is to search for
strings. You may name more than one file.
Application usage
exstr is useful for application programs that need to run in an inter-
national environment and print messages in more than one language.
exstr replaces text strings in C source files with function calls that
point at strings in a message database. The database used depends on
the runtime value of the LCMESSAGES environment variable [see
environ(5)].
Procedural steps with exstr
- First, use exstr -e file.c > outfile to extract the required
strings from a named C source file (file.c) and to save them
together with positional information in a file named outfile.
- Next, examine the list of strings in outfile and determine which
strings can be translated to another language and subsequently
retrieved by the message retrieval function gettxt(3C).
- Then, modify this file by deleting lines that cannot be translated
and, for lines that can be translated, by adding the message file
names and the appropriate message numbers to the msgfile and msgnum
fields. The message files named must have been created beforehand
with mkmsgs and must reside in the directory
/usr/lib/locale/Locale/LCMESSAGES. The basename of the directory
/usr/lib/locale/Locale, i.e. Locale, corresponds to the language in
which the text strings are written in the message files [see
setlocale(3C)]. The message numbers used must correspond to the
sequence numbers of strings in the message files.
Page 2 Reliant UNIX 5.44 Printed 11/98
exstr(1) exstr(1)
- Now use your modified file (outfile) as input to exstr -r to pro-
duce a new version (newfile.c) of the original C-language source
file file.c, in which the strings have been replaced by calls to
the message retrieval function gettxt(3C). This can be done by
issuing the following call:
exstr -r file.c < outfile > newfile.c
Two arguments are passed to the gettxt(3C) function. The first
argument consists of the fields msgfile and msgnum in outfile; the
second argument consists of the strings to be printed if the call
to gettxt(3C) fails at runtime. This argument is the original
string (see above).
Restrictions
exstr cannot be used to replace all types of strings in C source
files. For example:
- A static initialized character string cannot be replaced by a func-
tion call.
- Strings in the form of escape sequences cannot be translated into
another language and should therefore not be replaced using exstr.
In order to prevent invalid code from being generated, the output
produced by invoking exstr -e must be examined, and lines contain-
ing strings that are not directly replaceable by function calls to
gettxt(3C) must be deleted or modified accordingly.
ERROR MESSAGES
The most important error messages are listed below. They are intended
to be self-explanatory.
ERROR: cannot replace string '%s' in line (%d) of file (%s)
ERROR: stdin: invalid message number '%s'
ERROR: stdin: invalid message file name '%s'
ERROR: stdin: badly formed replacement string
LOCALE
The LCMESSAGES environment variable governs the language in which
message texts are displayed. If LCMESSAGES is undefined or is defined
as the null string, it defaults to the value of LANG. If LANG is like-
wise undefined or null, the system acts as if it were not internation-
alized.
The LCALL environment variable governs the entire locale. LCALL
takes precedence over all the other environment variables which affect
internationalization.
Page 3 Reliant UNIX 5.44 Printed 11/98
exstr(1) exstr(1)
EXAMPLES
The following example shows how exstr can be used:
Let us assume that the C source file file.c contains two strings:
main()
{
printf("First string\n");
printf("Second string\n");
}
When exstr is invoked (without options) with the argument file.c, it
extracts the strings enclosed in double quotes from the named file and
prints them on the standard output.
$ exstr file.c
file.c:First string\n
file.c:Second string\n
The strings themselves and supplementary information about their posi-
tions in the file can be obtained with the -e option. To examine the
extracted strings and possibly delete or modify them, you must
redirect the standard output to a file named outfile.
$ exstr -e file.c > outfile
$ cat outfile
file.c:3:8:::First string\n
file.c:4:8:::Second string\n
Each output line consists of six colon-separated fields. Field 1 con-
tains the name of the C source file; field 2 the numbers of the lines
containing the strings (3 and 4 in this case); field 3 the column
number of the first character in the string (8 in this example); field
6 the string itself without double quotes. Fields 4 and 5 you can edit
to define the message file from which gettxt(3C) is to retrieve the
new string at runtime and the message number of the string in the mes-
sage file, respectively. If UX is the name of the message file, and
the numbers 1 and 2 represent the sequence numbers of the strings in
the file, here is what outfile should look like after you have added
this information:
file.c:3:8:UX:1:First string\n
file.c:4:8:UX:2:Second string\n
You can now call exstr -r to replace the strings in the C source file
by calls to the message retrieval function gettxt(3C). The modified
file outfile is passed as an input argument to exstr. The output is
redirected to newfile.c, which will subsequently contain the follow-
ing new source code:
Page 4 Reliant UNIX 5.44 Printed 11/98
exstr(1) exstr(1)
$ exstr -r file.c < outfile > newfile.c
$ cat newfile.c
extern char *gettxt();
main()
{
printf(gettxt("UX:1",""));
printf(gettxt("UX:2",""));
}
If the -d option is also specified in this call, the string extracted
from the original C source file will be passed to gettxt(3C) as the
second argument instead of the null string "". This string will then
be output at program runtime if the call to gettxt(3C) fails:
$ exstr -rd file.c < outfile > newfile.c
$ cat newfile.c
extern char *gettxt();
main()
{
printf(gettxt("UX:1","First string\n"));
printf(gettxt("UX:2","Second string\n"));
}
FILES
/usr/lib/locale/Locale/LCMESSAGES
Directory containing the message files, where the basename of the
directory /usr/lib/locale/Locale, i.e. Locale, corresponds to the
language in which the text strings are written in the message
file.
SEE ALSO
gettxt(1), mkmsgs(1), printf(1), srchtxt(1), gettxt(3C),
setlocale(3C), printf(3S), environ(5).
Programmer's Guide: Internationalization - Localization.
Page 5 Reliant UNIX 5.44 Printed 11/98