1 .\" ident "%Z%%M% %I% %E% SMI"
2 .\" Copyright 2005 Sun Microsystems, Inc. All rights reserved.
3 .\" Use is subject to license terms.
4 .\"
5 .\" CDDL HEADER START
6 .\"
7 .\" The contents of this file are subject to the terms of the
8 .\" Common Development and Distribution License, Version 1.0 only
9 .\" (the "License"). You may not use this file except in compliance
10 .\" with the License.
11 .\"
12 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
13 .\" or http://www.opensolaris.org/os/licensing.
14 .\" See the License for the specific language governing permissions
15 .\" and limitations under the License.
16 .\"
17 .\" When distributing Covered Code, include this CDDL HEADER in each
18 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
19 .\" If applicable, add the following below this CDDL HEADER, with the
20 .\" fields enclosed by brackets "[]" replaced with your own identifying
21 .\" information: Portions Copyright [yyyy] [name of copyright owner]
22 .\"
23 .\" CDDL HEADER END
24 .\"
25 .if n .tr \--
26 .TH sgsmsg 1l "2 Jun 1999"
27 .SH NAME
28 sgsmsg \- generate message strings for SGS subsystem.
29 .SH SYNOPSIS
30 .B sgsmsg
31 [
32 .B \-cl
33 ] [
34 .BI \-d\0 "data"
35 ] [
36 .BI \-h\0 "defs"
37 ] [
38 .BI \-i\0 "ident"
39 ]
40 .if n .ti +5n
41 [
42 .BI \-m\0 "messages"
43 ] [
44 .BI \-n\0 "name"
45 ]
46 .I file \.\.\.
47 .SH AVAILABILITY
48 SUNWonld
49 .SH DESCRIPTION
50 \f3sgsmsg\f1 generates several message files from an input string definition
51 \f2file\f1. \f3sgsmsg\f1 provides a flexible, centralized, mechanism
52 of collecting character strings within a code group such as an executable or
53 shared object. All character strings are captured into a single data array
54 within the \f2data\f1 file.
55 The data array is similar to that produced by
56 .BR xstr (1)),
57 and helps reduce the relocation overhead incurred by string pointers.
58 .LP
59 Indexes into the data array are generated as
60 definitions within the \f2defs\f1 file. The code group can reference each
61 character string via predefined macros.
62 .LP
63 The character strings may also be translated into an internationalized
64 format and captured in the
65 \f2messages\f1 file. By default these message strings are suitable for
66 .BR gettext (3I)
67 manipulation. The \f3\-c\f1 option provides for these message strings to be
68 translated into a form suitable for
69 .BR catgets (3C)
70 manipulation.
71 .SH OPERANDS
72 .LP
73 One of more input \f2file\f1s contains a definition for each character
74 string used by a particular code group. The interpretation of a
75 definition is determined by the first character of each line within
76 the input \f2file\f1:
77 .LP
78 .PD 0
79 .RS +4
80 .IP \(bu 3
81 Entries that begin with a \f3#\fI, \f3$\f1 or a newline are treated as
82 comments and are copied (as is) to the \f2messages\f1 file.
83 .IP \(bu 3
84 Entries that begin with a \f3@\f1 are translated and will be written to
85 one or more of the output files. Two translations are possible dependent upon
86 whether one or more tokens follow the \f3@\f1 character.
87 .RE
88 .PD
89 .sp
90 .LP
91 An \f4@\f1 character followed by a single token is interpreted as one of
92 two reserved message output
93 \f2indicators\f1, or a message \f2identifier\f1. The reserved output
94 indicator \f4_START_\f1 enables output to the \f2messages\f1 file (note that
95 the occurrence of any \f4@\f1 token will also enable message output).
96 The reserved output indicator \f4_END_\f1 disables output to the
97 \f2messages\f1 file. These two indicators provides a means of isolating
98 only those character strings that require translation into the \f2messages\f1
99 file.
100 .LP
101 Besides the reserved output indicators, an \f4@\f1 character followed by a
102 single token is taken to be a
103 message \f2identifier\f1. This identifier will be translated into a
104 \f2domain\f1 name for
105 .BR gettext (3I)
106 output, or a \f2setid\f1 for
107 .BR catgets (3C)
108 output. This translated value is determine by substituting the message
109 \f2identifier\f1 token
110 for the associated definition from in the \f2ident\f1 file. Note that
111 a message \f2identifier\f1 is required for
112 .BR catgets (3C)
113 use but is optional for
114 .BR gettext (3I).
115 .LP
116 An \f4@\f1 character followed by multiple tokens is taken to be a
117 string \f2definition\f1 followed by a quoted character string. Character
118 strings can be continued over multiple lines by ending the preceding
119 line with a backslash - all initial whitespace on the continuation line will
120 is ignored. Character strings can contain the escape sequences
121 .B \en
122 for newline,
123 .B \et
124 for tab,
125 .B \ev
126 for vertical tab,
127 .B \eb
128 for backspace,
129 .B \er
130 for carriage return,
131 .B \ef
132 for formfeed,
133 .B \e\e
134 for backslash, and
135 \e"
136 for double quote.
137 .LP
138 The character string is copied to the \f2data\f1 array
139 and an index into this array is generated as the \f2definition\f1 within
140 the string
141 \f2defs\f1 file. The character string is also translated to the appropriate
142 message format and written to the \f2messages\f1 file.
143 .SH OPTIONS
144 .TP 12
145 .B \-c
146 By default, strings generated in the \f2messages\f1 file are suitable for
147 .BR msgfmt (1)
148 processing, which provides for message extraction via
149 .BR gettext (3I).
150 This option causes the formatting of the message strings to be suitable for
151 .BR gencat (1)
152 processing, which provides for message extraction via
153 .BR catgets (3C).
154 .TP
155 .BI \-d\0 data
156 Specify a \f2data\f1 file is to be created.
157 This file contains a single data array, by default named (\f2__name\f1[]),
158 containing all the strings
159 defined in the string definition \f2file\f1.
160 .TP
161 .BI \-h\0 defs
162 Specify a \f2defs\f1 file is to be created.
163 This file contains definitions for each character string contained in
164 the data array within the \f2data\f1 file. These definitions represent
165 offsets in the data array for each string. Reference to individual strings
166 should use one of the two defined macros \f4MSG_INTL\f1 (which specifies
167 a user defined message extraction function), or \f4MSG_ORIG\f1
168 (which specifies a direct access to the \f2__name\f1[] array).
169 .TP
170 .BI \-i\0 ident
171 Specify an \f2ident\f1 file from which to interpret a message identifier
172 token.
173 .TP
174 .B \-l
175 Indicate that the \f2data\f1 array be defined local (\f2static\f1). This
176 is useful for establishing individual string arrays on a per-object basis.
177 .TP
178 .BI \-m\0 messages
179 Specify a \f2messages\f1 file is to be created. This
180 contain message strings suitable for delivery to a localization group.
181 .TP
182 .BI \-n\0 name
183 Specify an alternative interface \f2name\f1. This name is used to label
184 the message data array (\f2__name\f1[]) and the user defined message
185 extraction function (const char * \f2_name\f1(int)) which will interface
186 with this array.
187 .SH EXAMPLES
188 The following examples provide a simplified guide to using the \f3sgsmsg\fP
189 command, including sample input files and generated output files.
190 .LP
191 The following \f2ident\f1 file provides message \f2identifiers\f1 for
192 the link-editor utilities
193 .BR ld (1),
194 .BR libld.so.2 ,
195 and
196 .BR liblddbg.so.3 .
197 These identifiers are referenced from the input string definition files
198 of the respective code groups:
199 .if n .ta 1.8i 2.2i
200 .if t .ta 1.6i 2.2i
201 .RS
202 .nf
203 .ft 3
204
205 % cat sgs.ident
206 .ft 1
207 .if t .sp 0.35
208 .if n .sp
209 # mesgid setid domain
210 .if t .sp 0.35
211 .if n .sp
212 MSG_ID_LD 1 SUNW_OST_SGS
213 MSG_ID_LIBLD 2 SUNW_OST_SGS
214 MSG_ID_LIBLDDBG 3 SUNW_OST_SGS
215
216 .fi
217 .RE
218 .if t .bp
219 .LP
220 The following string definition \f2file\f1 defines a small number of
221 strings used by
222 .BR libld.so.2 :
223 .ta 2.2i
224 .RS
225 .nf
226 .ft 3
227
228 % cat libld.msg
229 .ft 1
230 .if t .sp 0.35
231 .if n .sp
232 # ident "%Z%%M% %I% %E% SMI"
233 .if t .sp 0.35
234 .if n .sp
235 @ _START_
236 .if t .sp 0.35
237 .if n .sp
238 # Message file for cmd/sgs/libld.
239 .if t .sp 0.35
240 .if n .sp
241 @ MSG_ID_LIBLD
242
243 # System call messages
244 .if t .sp 0.35
245 .if n .sp
246 @ MSG_SYS_OPEN "file %s: cannot open file: %s"
247 @ MSG_SYS_MMAP "file %s: cannot mmap file: %s"
248
249 # Symbol processing errors
250 .if t .sp 0.35
251 .if n .sp
252 @ MSG_SYM_DIFFTYPE "symbol `%s' has differing types:"
253 @ MSG_SYM_DIFFATTR "symbol `%s' has differing %s:\\n\\
254 \ \\t(file %s value=0x%x; file %s value=0x%x);"
255 .if t .sp 0.35
256 .if n .sp
257 @ _END_
258
259 # The following strings represent reserved names. Reference to
260 # these strings is via the MSG_ORIG() macro, and thus no
261 # translations are required.
262 .if t .sp 0.35
263 .if n .sp
264 @ MSG_STR_EMPTY ""
265 @ MSG_PTH_DEVZERO "/dev/zero"
266 @ MSG_SUNW_OST_SGS "SUNW_OST_SGS"
267
268 .fi
269 .RE
270 .LP
271 Using the above input files, the following string and message data files can be
272 generated:
273 .if t .ta 0.5i 2.2i
274 .if n .ta 0.5i 0.8i 3.0i
275 .RS
276 .nf
277 .ft 3
278
279 % sgsmsg\ \ \-i sgs.ident\ \ \-m\ messages\ \ \-d\ msg.c\ \ \-h\ msg.h \\
280 \ \ \ \ \-n\ libld_msg\ \ libld.msg
281 % cat msg.c
282 .ft 1
283 .if t .sp 0.35
284 .if n .sp
285 const char __libld_msg[] = { 0x00,
286 0x66, 0x69, 0x6c, 0x65, 0x20, 0x25, 0x73, 0x3a, \.\.\.\.
287 0x61, 0x6e, 0x6e, 0x6f, 0x74, 0x20, 0x6f, 0x70, \.\.\.\.
288 \.\.\.\.
289 0x00
290 };
291
292 .if t .bp
293 .ft 3
294 % cat msg.h
295 .ft 1
296 .if t .sp 0.35
297 .if n .sp
298 extern const char __libld_msg[];
299 .if t .sp 0.35
300 .if n .sp
301 #define MSG_ORIG(x) &__libld_msg[x]
302 .if t .sp 0.35
303 .if n .sp
304 extern const char * _libld_msg(int);
305 .if t .sp 0.35
306 .if n .sp
307 #define MSG_INTL(x) _libld_msg(x)
308 .if t .sp 0.35
309 .if n .sp
310 #define MSG_SYS_OPEN 1
311 #define MSG_SYS_MMAP 31
312 #define MSG_SYM_DIFFTYPE 61
313 #define MSG_SYM_DIFFATTR 94
314 #define MSG_STR_EMPTY 167
315 #define MSG_PTH_DEVZERO 168
316 #define MSG_SUNW_OST_SGS 178
317
318 .ft 3
319 % cat messages
320 .ft 1
321 .if t .sp 0.35
322 .if n .sp
323 # Message file for cmd/sgs/libld.
324 .if t .sp 0.35
325 .if n .sp
326 domain "SUNW_OST_SGS"
327 .if t .sp 0.35
328 .if n .sp
329 # System call messages
330 .if t .sp 0.35
331 .if n .sp
332 msgid "file %s: cannot open file: %s"
333 msgstr ""
334 msgid "file %s: cannot mmap file: %s"
335 msgstr ""
336 .if t .sp 0.35
337 .if n .sp
338 # Symbol processing errors
339 .if t .sp 0.35
340 .if n .sp
341 msgid "symbol `%s' has differing types:"
342 msgstr ""
343 msgid "symbol `%s' has differing %s:\\n\\t(file %s value=0x%x; file %s value=0x%x);"
344 msgstr ""
345
346 .fi
347 .RE
348 .LP
349 References to the string data from the code group
350 should use one of the two defined macros
351 depending upon whether an original or localized string is required.
352 For example, the simple
353 .BR open (2)
354 of a file would use the original string, however its associated
355 error message should be localized:
356 .if n .ta 0.75i
357 .if t .ta 0.5i 2.2i
358 .RS
359 .nf
360 .ft 3
361
362 const char * file = MSG_ORIG(MSG_PTH_DEVZERO);
363 .if t .sp 0.35
364 .if n .sp
365 if ((fd = open(file, O_RDWR, 0)) == -1) {
366 int err = errno;
367 (void) fprintf(stderr, MSG_INTL(MSG_SYS_OPEN), file,
368 strerror(err));
369 return (1);
370 }
371
372 .fi
373 .RE
374 .if t .bp
375 .LP
376 The \f3MSG_INTL\f1 definition provides for a user defined message
377 extraction function
378 that allows the greatest flexibility in providing an objects localization.
379 Normally this interface is quite simple. For a code group that resides
380 in a shared object the following interface can be provided by the user:
381 .RS
382 .nf
383 .ft 3
384
385 extern char * _dgettext(const char *, const char *);
386 .if t .sp 0.35
387 .if n .sp
388 const char *
389 _libld_msg(int mid)
390 {
391 return (_dgettext(MSG_ORIG(MSG_SUNW_OST_SGS),
392 MSG_ORIG(mid)));
393 }
394
395 .fi
396 .RE
397 .LP
398 For a code group that resides in an executable the following interface,
399 and initialization can be provided by the user:
400 .RS
401 .nf
402 .ft 3
403
404 #include <locale.h>
405
406 int
407 main(int argc, char ** argv)
408 {
409 \&\.\.\.\.\.\.
410 (void) setlocale(LC_MESSAGES, MSG_ORIG(MSG_STR_EMPTY));
411 (void) textdomain(MSG_ORIG(MSG_SUNW_OST_SGS));
412 \&\.\.\.\.\.\.
413 }
414
415 const char *
416 _ld_msg(int mid)
417 {
418 return (gettext(MSG_ORIG(mid)));
419 }
420 .sp
421 .SH "EXIT STATUS"
422 A non-zero error return indicates a processing error.
423 .RE
424 .PD
425 .SH "SEE ALSO"
426 .BR gencat (1),
427 .BR ld (1),
428 .BR msgfmt (1),
429 .BR catgets (3C),
430 .BR gettext (3I).
431 .br
432 .TZ LLM
433 .if n .tr \-\-