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