exstr(1) - osol9

1exstr(1)                         User Commands                        exstr(1)
2
3
4

NAME

6       exstr - extract strings from source files
7

SYNOPSIS

9       exstr filename...
10
11
12       exstr -e filename...
13
14
15       exstr -r [-d] filename...
16
17

DESCRIPTION

19       The  exstr  utility  is  used to extract strings from C-language source
20       files and replace them by calls to the message retrieval function  (see
21       gettxt(3C)). This utility will extract all character strings surrounded
22       by double quotes, not just strings used as arguments to the printf com‐
23       mand  or the printf routine. In the first form, exstr finds all strings
24       in the source files and writes them on the standard output. Each string
25       is preceded by the source file name and a colon (:).
26
27
28       The first step is to use exstr -e to extract a list of strings and save
29       it in a file. Next, examine this list and determine which  strings  can
30       be translated and subsequently retrieved by the message retrieval func‐
31       tion. Then, modify this file by deleting lines that can't be translated
32       and, for lines that can be translated, by adding the message file names
33       and the message numbers as the  fourth  (msgfile)  and  fifth  (msgnum)
34       entries  on  a  line. The message files named must have been created by
35       mkmsgs(1) and  exist  in  /usr/lib/locale/locale/LC_MESSAGES    .  (The
36       directory  locale corresponds to the language in which the text strings
37       are written; see setlocale(3C)). The message numbers used  must  corre‐
38       spond to the sequence numbers of strings in the message files.
39
40
41       Now  use  this modified file as input to exstr -r to produce a new ver‐
42       sion of the original C-language source file in which the  strings  have
43       been  replaced by calls to the message retrieval function gettxt(). The
44       msgfile and msgnum fields are used to construct the first  argument  to
45       gettxt().  The  second  argument  to gettxt() is printed if the message
46       retrieval fails at run-time. This argument is the null  string,  unless
47       the -d option is used.
48
49
50       This  utility  cannot  replace strings in all instances. For example, a
51       static initialized character string cannot be replaced  by  a  function
52       call. A second example is that a string could be in a form of an escape
53       sequence which could not be translated. In order not to break  existing
54       code, the files created by invoking exstr -e must be examined and lines
55       containing strings not replaceable by function calls must  be  deleted.
56       In some cases the code may require modifications so that strings can be
57       extracted and replaced by calls to the message retrieval function.
58

OPTIONS

60       The following options are supported:
61
62       -e     Extract a list of  strings  from  the  named  C-language  source
63              files,  with  positional  information.  This list is produced on
64              standard output in the following format:
65
66              file:line:position:msgfile:msgnum:string
67
68
69
70
71              file
72
73                  the name of a C-language source file
74
75
76              line
77
78                  line number in the file
79
80
81              position
82
83                  character position in the line
84
85
86              msgfile
87
88                  null
89
90
91              msgnum
92
93                  null
94
95
96              string
97
98                  the extracted text string
99
100              Normally you would redirect this output into a  file.  Then  you
101              would  edit this file to add the values you want to use for msg‐
102              file and msgnum:
103
104              msgfile     the file that contains the text  strings  that  will
105                          replace  string.  A file with this name must be cre‐
106                          ated and installed in the appropriate place  by  the
107                          mkmsgs(1) utility.
108
109
110              msgnum      the sequence number of the string in msgfile.
111
112              The next step is to use exstr -r to replace strings in file.
113
114
115       -r     Replace  strings in a C-language source file with function calls
116              to the message retrieval function gettxt().
117
118
119       -d     This option is used together with the -r option. If the  message
120              retrieval  fails  when gettxt() is invoked at run-time, then the
121              extracted string is printed. You would use the  capability  pro‐
122              vided by exstr on an application program that needs to run in an
123              international environment and have messages print in  more  than
124              one  language.  exstr  replaces text strings with function calls
125              that point at strings in a message data base. The data base used
126              depends  on  the  run-time  value of the LC_MESSAGES environment
127              variable (see environ(5)).
128
129

EXAMPLES

131       Example 1 The following examples show uses of exstr
132
133
134       Assume that the file example.c contains two strings:
135
136
137         main()
138
139         {
140
141                 printf("This is an example\n");
142
143                 printf("Hello world!\n");
144
145         }
146
147
148
149       The exstr utility, invoked with the argument example.c extracts strings
150       from the named file and prints them on the standard output.
151
152
153         example% exstr example.c
154
155
156
157
158       produces the following output:
159
160
161         example.c:This is an example\n
162         example.c:Hello world!\n
163
164
165
166
167       The  exstr  utility,  invoked with the -e option and the argument exam‐
168       ple.c, and redirecting output to the file example.stringsout
169
170
171         example% exstr -e example.c > example.stringsout
172
173
174
175
176       produces the following output in the file example.stringsout
177
178
179         example.c:3:8:::This is an example\n
180         example.c:4:8:::Hello world!\n
181
182
183
184
185       You must edit example.stringsout to add the values you want to use  for
186       the  msgfile  and msgnum fields before these strings can be replaced by
187       calls to the retrieval function. If UX is the name of the message file,
188       and the numbers 1 and 2 represent the sequence number of the strings in
189       the file, here is what example.stringsout looks like after you add this
190       information:
191
192
193         example.c:3:8:UX:1:This is an example\n
194         example.c:4:8:UX:2:Hello world!\n
195
196
197
198
199       The  exstr utility can now be invoked with the -r option to replace the
200       strings in the source file by calls to the message  retrieval  function
201       gettxt().
202
203
204         example% exstr -r example.c <example.stringsout >intlexample.c
205
206
207
208
209       produces the following output:
210
211
212         extern char *gettxt();
213
214         main()
215
216         {
217
218              printf(gettxt("UX:1", ""));
219
220              printf(gettxt("UX:2", ""));
221
222         }
223
224
225
226
227       The following example:
228
229
230         example% exstr -rd example.c <example.stringsout >intlexample.c
231
232
233
234
235       uses the extracted strings as a second argument to gettxt():
236
237
238         extern char *gettxt();
239
240         main()
241
242         {
243
244                 printf(gettxt("UX:1", "This is an example\n"));
245
246                 printf(gettxt("UX:2", "Hello world!\n"));
247
248         }
249
250
251

FILES

253       /usr/lib/locale/locale/LC_MESSAGES/*
254
255           files created by mkmsgs(1)
256
257

ATTRIBUTES

259       See attributes(5) for descriptions of the following attributes:
260
261
262
263
264       ┌─────────────────────────────┬─────────────────────────────┐
265       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
266       ├─────────────────────────────┼─────────────────────────────┤
267       │Availability                 │SUNWtoo                      │
268       └─────────────────────────────┴─────────────────────────────┘
269

DIAGNOSTICS

275       The error messages produced by exstr are intended to  be  self-explana‐
276       tory. They indicate errors in the command line or format errors encoun‐
277       tered within the input file.
278
279
280
281SunOS 5.11                        5 Jul 1990                          exstr(1)