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