'\"macro stdmacro
.if n .pH g1.exstr @(#)exstr	40.22 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} exstr 1 "Essential Utilities" "\&"
.if \nX=1 .ds x} exstr 1 "Essential Utilities"
.if \nX=2 .ds x} exstr 1 "" "\&"
.if \nX=3 .ds x} exstr "" "" "\&"
.TH \*(x}
.SH NAME
\f4exstr\f1 \- extract strings from source files
.SH SYNOPSIS
\f4exstr\f1
.IR "file" "\|.\|.\|.\|"
.br
\f4exstr\f1
\f4\-e\f1
.IR "file" "\|.\|.\|.\|"
.br
\f4exstr\f1
\f4\-r\f1
\f1[\f4\-d\f1]
.IR "file" "\|.\|.\|.\|"
.SH DESCRIPTION
The 
\f4exstr\fP
utility is used to extract strings from C-language source files and
replace them by calls to the message retrieval function
(see 
\f4gettxt\fP(3C)).
This utility will extract all character strings surrounded by double quotes,
not just strings used as arguments to the
\f4printf\f1 command or the \f4printf\fP routine.
In the first form, \f4exstr\fP 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:
.TP 8
\f4\-e\f1
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:
.PP
.RS 12
.I "file:line:position:msgfile:msgnum:string"
.TP 10
.I file\^
the name of a C-language source file
.PD 0
.TP 10
.I line
line number in the file
.TP 10
.I position
character position in the line
.TP 10
.I msgfile
null
.TP 10
.I msgnum
null
.TP 10
.I string
the extracted text string
.RE
.PD
.IP "" 8
Normally you would redirect this output into a file.
Then you would edit this file to add the values you
want to use for
.I msgfile
and
.IR msgnum :
.RS 12
.TP 10
.I msgfile
the file that contains the text strings that will replace
.IR string .
A file with this name must be created and installed
in the appropriate place by the
\f4mkmsgs\fP(1)
utility.
.TP 10
.I msgnum
the sequence number of the string in
.IR msgfile .
.RE
.IP "" 8
The next step is to use
\f4exstr \-r\f1
to replace
.IR string s
in
.IR file .
.TP 8
\f4\-r\f1
Replace strings in a C-language source file with
function calls to the message retrieval
function
\f4gettxt\fP(\^).
.TP 8
\f4\-d\f1
This option is used together with the \f4\-r\f1 option.
If the message retrieval fails when
\f4gettxt\fP(\^)
is invoked at run-time,
then the extracted string is printed.
.P
You would use the capability provided by
\f4exstr\fP
on an application program that needs to run in an international environment
and have messages print in more than one language.
\f4exstr\fP
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
\f4LC_MESSAGES\f1
environment variable
(see
\f4environ\fP(5)).
.PP
The first step is to use
\f4exstr \-e\f1
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
.RI ( msgfile )
and fifth
.RI ( msgnum )
entries on a line.
The message files named must have been created by
\f4mkmsgs\fP(1)
and exist in
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES\f1.
(The directory
.I locale
corresponds to the language in which the text strings are written;
see
\f4setlocale\fP(3C)).
The message numbers used must correspond to the sequence numbers of strings
in the message files. 
.P
Now use this modified file as input to
\f4exstr \-r\f1
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
\f4gettxt\fP(\^).
The \f2msgfile\f1 and \f2msgnum\f1 fields are used to
construct the first argument to
\f4gettxt\fP(\^).
The second argument to
\f4gettxt\fP(\^)
is printed if the message retrieval fails at run-time.
This argument is the null string,
unless the
\f4\-d\f1
option is used.
.P
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
\f4exstr \-e\f1
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.
.SH EXAMPLES
The following examples show uses of \f4exstr\fP.
.P
Assume that the file
\f4foo.c\f1
contains two strings:
.PP
.RS
.nf
.ft 4
main(\^)
{
	printf("This is an example\\n");
	printf("Hello world!\\n");
}
.ft
.fi
.RE
.P
The \f4exstr\fP utility, invoked with the argument \f4foo.c\f1
extracts strings from the named file and prints them on the
standard output.
.P
\f4exstr foo.c\f1 produces the following output:
.PP
.RS
\f4foo.c:This is an example\\n\f1
.br
\f4foo.c:Hello world!\\n\f1
.RE
.P
\f4exstr \-e foo.c > foo.stringsout\f1 produces the following output
in the file
\f4foo.stringsout\f1:
.PP
.RS
\f4foo.c:3:8:::This is an example\\n\f1
.br
\f4foo.c:4:8:::Hello world!\\n\f1
.RE
.P
You must edit
\f4foo.stringsout\f1
to add the values you want to use for the \f2msgfile\f1 and \f2msgnum\f1
fields before these strings can be replaced by calls to the retrieval
function.
If \f4UX\f1 is the name of the message file, and
the numbers \f41\f1 and \f42\f1 represent the sequence number of the
strings in the file,
here is what
\f4foo.stringsout\f1
looks like after you add this information:
.PP
.RS
\f4foo.c:3:8:UX:1:This is an example\\n\f1
.br
\f4foo.c:4:8:UX:2:Hello world!\\n\f1
.RE
.P
The \f4exstr\fP utility can now be invoked with the \f4\-r\f1
option to replace the strings in the source file by calls
to the message retrieval function
\f4gettxt\fP(\^).
.P
\f4exstr \-r foo.c <foo.stringsout >intlfoo.c\f1
produces the following output:
.PP
.RS
.nf
.ft 4
extern char \(**gettxt(\^);
main(\^)
{
	printf(gettxt("UX:1", ""));
	printf(gettxt("UX:2", ""));
}
.ft
.fi
.RE
.P
\f4exstr \-rd foo.c <foo.stringsout >intlfoo.c\f1
uses the extracted strings as a
second argument to
\f4gettxt\fP(\^).
.PP
.RS
.nf
.ft 4
extern char \(**gettxt(\^);
main(\^)
{
	printf(gettxt("UX:1", "This is an example\\n"));
	printf(gettxt("UX:2", "Hello world!\\n"));
}
.ft
.fi
.RE
.SH FILES
.TP 2.5i
\f4/usr/lib/locale/\f2locale\f4/LC_MESSAGES/\(**\f1
files created by
\f4mkmsgs\fP(1)
.SH SEE ALSO
\f4gettxt\fP(1),
\f4mkmsgs\fP(1),
\f4printf\fP(1),
\f4srchtxt\fP(1).
.br
\f4gettxt\fP(3C), \f4printf\fP(3S), \f4setlocale\fP(3C) in the
.IR "Programmer's Reference Manual" .
.br
\f4environ\fP(5) in the
.IR "System Administrator's Reference Manual" .
.SH DIAGNOSTICS
The error messages produced by \f4exstr\fP
are intended to be self-explanatory.
They indicate errors in the command line or format errors
encountered within the input file.
.Ee
