share/man/man1/exstr.1

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1990, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH EXSTR 1 "Jul 5, 1990"
   7 .SH NAME
   8 exstr \- extract strings from source files
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBexstr\fR \fIfilename\fR...
  13 .fi
  14
  15 .LP
  16 .nf
  17 \fBexstr\fR \fB-e\fR \fIfilename\fR...
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBexstr\fR \fB-r\fR [\fB-d\fR] \fIfilename\fR...
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBexstr\fR utility is used to extract strings from C-language source files
  29 and replace them by calls to the message retrieval function (see
  30 \fBgettxt\fR(3C)). This utility will extract all character strings surrounded
  31 by double quotes, not just strings used as arguments to the \fBprintf\fR
  32 command or the \fBprintf\fR routine. In the first form, \fBexstr\fR finds all
  33 strings in the source files and writes them on the standard output. Each string
  34 is preceded by the source file name and a colon (\fB:\fR).
  35 .sp
  36 .LP
  37 The first step is to use \fBexstr\fR \fB-e\fR to extract a list of strings and
  38 save it in a file. Next, examine this list and determine which strings can be
  39 translated and subsequently retrieved by the message retrieval function. Then,
  40 modify this file by deleting lines that can't be translated and, for lines that
  41 can be translated, by adding the message file names and the message numbers as
  42 the fourth (\fImsgfile\fR) and fifth (\fImsgnum\fR) entries on a line. The
  43 message files named must have been created by \fBmkmsgs\fR(1) and exist in
  44 \fB/usr/lib/locale/\fR\fBlocale\fR\fB/\fR\fBLC_MESSAGES\fR\fB   \fR. (The
  45 directory \fBlocale\fR corresponds to the language in which the text strings
  46 are written; see \fBsetlocale\fR(3C)). The message numbers used must correspond
  47 to the sequence numbers of strings in the message files.
  48 .sp
  49 .LP
  50 Now use this modified file as input to \fBexstr\fR \fB-r\fR to produce a new
  51 version of the original C-language source file in which the strings have been
  52 replaced by calls to the message retrieval function \fBgettxt\fR(). The
  53 \fImsgfile\fR and \fImsgnum\fR fields are used to construct the first argument
  54 to \fBgettxt\fR(). The second argument to \fBgettxt\fR() is printed if the
  55 message retrieval fails at run-time. This argument is the null string, unless
  56 the \fB-d\fR option is used.
  57 .sp
  58 .LP
  59 This utility cannot replace strings in all instances. For example, a static
  60 initialized character string cannot be replaced by a function call. A second
  61 example is that a string could be in a form of an escape sequence which could
  62 not be translated. In order not to break existing code, the files created by
  63 invoking \fBexstr\fR \fB-e\fR must be examined and lines containing strings not
  64 replaceable by function calls must be deleted. In some cases the code may
  65 require modifications so that strings can be extracted and replaced by calls to
  66 the message retrieval function.
  67 .SH OPTIONS
  68 .sp
  69 .LP
  70 The following options are supported:
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fB-e\fR \fR
  75 .ad
  76 .RS 7n
  77 Extract a list of strings from the named C-language source files, with
  78 positional information. This list is produced on standard output in the
  79 following format:
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fIfile:line:position:msgfile:msgnum:string\fR \fR
  84 .ad
  85 .sp .6
  86 .RS 4n
  87
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fIfile\fR \fR
  94 .ad
  95 .sp .6
  96 .RS 4n
  97 the name of a C-language source file
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fIline\fR \fR
 104 .ad
 105 .sp .6
 106 .RS 4n
 107 line number in the file
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fIposition\fR \fR
 114 .ad
 115 .sp .6
 116 .RS 4n
 117 character position in the line
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fImsgfile\fR \fR
 124 .ad
 125 .sp .6
 126 .RS 4n
 127 null
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fImsgnum\fR \fR
 134 .ad
 135 .sp .6
 136 .RS 4n
 137 null
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fIstring\fR \fR
 144 .ad
 145 .sp .6
 146 .RS 4n
 147 the extracted text string
 148 .RE
 149
 150 Normally you would redirect this output into a file. Then you would edit this
 151 file to add the values you want to use for \fImsgfile\fR and \fImsgnum\fR:
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fImsgfile\fR \fR
 156 .ad
 157 .RS 12n
 158 the file that contains the text strings that will replace \fIstring\fR. A file
 159 with this name must be created and installed in the appropriate place by the
 160 \fBmkmsgs\fR(1) utility.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fImsgnum\fR \fR
 167 .ad
 168 .RS 12n
 169 the sequence number of the string in \fImsgfile\fR.
 170 .RE
 171
 172 The next step is to use \fBexstr\fR \fB-r\fR to replace \fIstring\fRs in
 173 \fBfile\fR.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fB-r\fR \fR
 180 .ad
 181 .RS 7n
 182 Replace strings in a C-language source file with function calls to the message
 183 retrieval function \fBgettxt\fR().
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fB-d\fR \fR
 190 .ad
 191 .RS 7n
 192 This option is used together with the \fB-r\fR option. If the message retrieval
 193 fails when \fBgettxt\fR() is invoked at run-time, then the extracted string is
 194 printed. You would use the capability provided by \fBexstr\fR on an application
 195 program that needs to run in an international environment and have messages
 196 print in more than one language. \fBexstr\fR replaces text strings with
 197 function calls that point at strings in a message data base. The data base used
 198 depends on the run-time value of the \fBLC_MESSAGES\fR environment variable
 199 (see \fBenviron\fR(5)).
 200 .RE
 201
 202 .SH EXAMPLES
 203 .LP
 204 \fBExample 1 \fRThe following examples show uses of exstr
 205 .sp
 206 .LP
 207 Assume that the file \fBexample.c\fR contains two strings:
 208
 209 .sp
 210 .in +2
 211 .nf
 212 main()
 213
 214 {
 215
 216         printf("This is an example\en");
 217
 218         printf("Hello world!\en");
 219
 220 }\fI\fR
 221 .fi
 222 .in -2
 223
 224 .sp
 225 .LP
 226 The \fBexstr\fR utility, invoked with the argument \fBexample.c\fR extracts
 227 strings from the named file and prints them on the standard output.
 228
 229 .sp
 230 .in +2
 231 .nf
 232 example% \fBexstr example.c\fR
 233 .fi
 234 .in -2
 235 .sp
 236
 237 .sp
 238 .LP
 239 produces the following output:
 240
 241 .sp
 242 .in +2
 243 .nf
 244 example.c:This is an example\en
 245 example.c:Hello world!\en
 246 .fi
 247 .in -2
 248 .sp
 249
 250 .sp
 251 .LP
 252 The \fBexstr\fR utility, invoked with the \fB-e\fR option and the argument
 253 \fBexample.c\fR, and redirecting output to the file \fBexample.stringsout\fR
 254
 255 .sp
 256 .in +2
 257 .nf
 258 example% \fBexstr -e example.c > example.stringsout\fR
 259 .fi
 260 .in -2
 261 .sp
 262
 263 .sp
 264 .LP
 265 produces the following output in the file \fBexample.stringsout\fR
 266
 267 .sp
 268 .in +2
 269 .nf
 270 example.c:3:8:::This is an example\en
 271 example.c:4:8:::Hello world!\en
 272 .fi
 273 .in -2
 274 .sp
 275
 276 .sp
 277 .LP
 278 You must edit \fBexample.stringsout\fR to add the values you want to use for
 279 the \fImsgfile\fR and \fImsgnum\fR fields before these strings can be replaced
 280 by calls to the retrieval function. If \fBUX\fR is the name of the message
 281 file, and the numbers \fB1\fR and \fB2\fR represent the sequence number of the
 282 strings in the file, here is what \fBexample.stringsout\fR looks like after you
 283 add this information:
 284
 285 .sp
 286 .in +2
 287 .nf
 288 example.c:3:8:UX:1:This is an example\en
 289 example.c:4:8:UX:2:Hello world!\en
 290 .fi
 291 .in -2
 292 .sp
 293
 294 .sp
 295 .LP
 296 The \fBexstr\fR utility can now be invoked with the \fB-r\fR option to replace
 297 the strings in the source file by calls to the message retrieval function
 298 \fBgettxt()\fR.
 299
 300 .sp
 301 .in +2
 302 .nf
 303 example% \fBexstr -r example.c <example.stringsout >intlexample.c\fR
 304 .fi
 305 .in -2
 306 .sp
 307
 308 .sp
 309 .LP
 310 produces the following output:
 311
 312 .sp
 313 .in +2
 314 .nf
 315 \fBextern char *gettxt();
 316
 317 main()
 318
 319 {
 320
 321         printf(gettxt("UX:1", ""));
 322
 323         printf(gettxt("UX:2", ""));
 324
 325 }\fR\fI\fR
 326 .fi
 327 .in -2
 328 .sp
 329
 330 .sp
 331 .LP
 332 The following example:
 333
 334 .sp
 335 .in +2
 336 .nf
 337 example% \fBexstr -rd example.c <example.stringsout >intlexample.c\fR
 338 .fi
 339 .in -2
 340 .sp
 341
 342 .sp
 343 .LP
 344 uses the extracted strings as a second argument to \fBgettxt()\fR:
 345
 346 .sp
 347 .in +2
 348 .nf
 349 extern char *gettxt();
 350
 351 main()
 352
 353 {
 354
 355         printf(gettxt("UX:1", "This is an example\en"));
 356
 357         printf(gettxt("UX:2", "Hello world!\en"));
 358
 359 }\fI\fR
 360 .fi
 361 .in -2
 362 .sp
 363
 364 .SH FILES
 365 .sp
 366 .ne 2
 367 .na
 368 \fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_MESSAGES/* \fR\fR
 369 .ad
 370 .sp .6
 371 .RS 4n
 372 files created by \fBmkmsgs\fR(1)
 373 .RE
 374
 375 .SH SEE ALSO
 376 .sp
 377 .LP
 378 \fBgettxt\fR(1), \fBmkmsgs\fR(1), \fBprintf\fR(1), \fBsrchtxt\fR(1),
 379 \fBgettxt\fR(3C), \fBprintf\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
 380 \fBenviron\fR(5)
 381 .SH DIAGNOSTICS
 382 .sp
 383 .LP
 384 The error messages produced by \fBexstr\fR are intended to be self-explanatory.
 385 They indicate errors in the command line or format errors encountered within
 386 the input file.