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.man.txt
+++ new/usr/src/tools/sgs/sgsmsg/sgsmsg.1onbld.man.txt
1 -sgsmsg(1l) sgsmsg(1l)
1 +sgsmsg(1ONBLD) illumos Build Tools sgsmsg(1ONBLD)
2 2
3 3
4 4
5 5 NAME
6 6 sgsmsg - generate message strings for SGS subsystem.
7 7
8 8 SYNOPSIS
9 9 sgsmsg [ -cl ] [ -d data ] [ -h defs ] [ -i ident ]
10 10 [ -m messages ] [ -n name ] file ...
11 11
12 12 AVAILABILITY
13 13 SUNWonld
14 14
15 15 DESCRIPTION
16 16 sgsmsg generates several message files from an input string definition
17 17 file. sgsmsg provides a flexible, centralized, mechanism of collecting
18 18 character strings within a code group such as an executable or shared
19 19 object. All character strings are captured into a single data array
20 20 within the data file. The data array is similar to that produced by
21 21 xstr(1)), and helps reduce the relocation overhead incurred by string
22 22 pointers.
23 23
24 24 Indexes into the data array are generated as definitions within the
25 25 defs file. The code group can reference each character string via
26 26 predefined macros.
27 27
28 28 The character strings may also be translated into an internationalized
29 29 format and captured in the messages file. By default these message
30 30 strings are suitable for gettext(3I) manipulation. The -c option
31 31 provides for these message strings to be translated into a form
32 32 suitable for catgets(3C) manipulation.
33 33
34 34 OPERANDS
35 35 One of more input files contains a definition for each character string
36 36 used by a particular code group. The interpretation of a definition is
37 37 determined by the first character of each line within the input file:
38 38
39 39 o Entries that begin with a #, $ or a newline are treated as
40 40 comments and are copied (as is) to the messages file.
41 41 o Entries that begin with a @ are translated and will be written
42 42 to one or more of the output files. Two translations are
43 43 possible dependent upon whether one or more tokens follow the @
44 44 character.
45 45
46 46
47 47 An @ character followed by a single token is interpreted as one of two
48 48 reserved message output indicators, or a message identifier. The
49 49 reserved output indicator _START_ enables output to the messages file
50 50 (note that the occurrence of any @ token will also enable message
51 51 output). The reserved output indicator _END_ disables output to the
52 52 messages file. These two indicators provides a means of isolating only
53 53 those character strings that require translation into the messages
54 54 file.
55 55
56 56 Besides the reserved output indicators, an @ character followed by a
57 57 single token is taken to be a message identifier. This identifier will
58 58 be translated into a domain name for gettext(3I) output, or a setid for
59 59 catgets(3C) output. This translated value is determine by substituting
60 60 the message identifier token for the associated definition from in the
61 61 ident file. Note that a message identifier is required for catgets(3C)
62 62 use but is optional for gettext(3I).
63 63
64 64 An @ character followed by multiple tokens is taken to be a string
65 65 definition followed by a quoted character string. Character strings can
66 66 be continued over multiple lines by ending the preceding line with a
67 67 backslash - all initial whitespace on the continuation line will is
68 68 ignored. Character strings can contain the escape sequences \n for
69 69 newline, \t for tab, \v for vertical tab, \b for backspace, \r for
70 70 carriage return, \f for formfeed, \\ for backslash, and \" for double
71 71 quote.
72 72
73 73 The character string is copied to the data array and an index into this
74 74 array is generated as the definition within the string defs file. The
75 75 character string is also translated to the appropriate message format
76 76 and written to the messages file.
77 77
78 78 OPTIONS
79 79 -c By default, strings generated in the messages file are
80 80 suitable for msgfmt(1) processing, which provides for
81 81 message extraction via gettext(3I). This option causes the
82 82 formatting of the message strings to be suitable for
83 83 gencat(1) processing, which provides for message extraction
84 84 via catgets(3C).
85 85
86 86 -d data Specify a data file is to be created. This file contains a
87 87 single data array, by default named (__name[]), containing
88 88 all the strings defined in the string definition file.
89 89
90 90 -h defs Specify a defs file is to be created. This file contains
91 91 definitions for each character string contained in the data
92 92 array within the data file. These definitions represent
93 93 offsets in the data array for each string. Reference to
94 94 individual strings should use one of the two defined macros
95 95 MSG_INTL (which specifies a user defined message extraction
96 96 function), or MSG_ORIG (which specifies a direct access to
97 97 the __name[] array).
98 98
99 99 -i ident Specify an ident file from which to interpret a message
100 100 identifier token.
101 101
102 102 -l Indicate that the data array be defined local (static).
103 103 This is useful for establishing individual string arrays on
104 104 a per-object basis.
105 105
106 106 -m messages Specify a messages file is to be created. This contain
107 107 message strings suitable for delivery to a localization
108 108 group.
109 109
110 110 -n name Specify an alternative interface name. This name is used to
111 111 label the message data array (__name[]) and the user
112 112 defined message extraction function (const char *
113 113 _name(int)) which will interface with this array.
114 114
115 115 EXAMPLES
116 116 The following examples provide a simplified guide to using the sgsmsg
117 117 command, including sample input files and generated output files.
118 118
119 119 The following ident file provides message identifiers for the link-
120 120 editor utilities ld(1), libld.so.2, and liblddbg.so.3. These
121 121 identifiers are referenced from the input string definition files of
122 122 the respective code groups:
123 123
124 124 % cat sgs.ident
125 125
126 126 # mesgid setiddomain
127 127
|
↓ open down ↓ |
116 lines elided |
↑ open up ↑ |
128 128 MSG_ID_LD 1 SUNW_OST_SGS
129 129 MSG_ID_LIBLD 2 SUNW_OST_SGS
130 130 MSG_ID_LIBLDDBG 3 SUNW_OST_SGS
131 131
132 132
133 133 The following string definition file defines a small number of strings
134 134 used by libld.so.2:
135 135
136 136 % cat libld.msg
137 137
138 - # ident "%Z%%M% %I% %E% SMI"
139 -
140 138 @ _START_
141 139
142 140 # Message file for cmd/sgs/libld.
143 141
144 142 @ MSG_ID_LIBLD
145 143
146 144 # System call messages
147 145
148 146 @ MSG_SYS_OPEN "file %s: cannot open file: %s"
149 147 @ MSG_SYS_MMAP "file %s: cannot mmap file: %s"
150 148
151 149 # Symbol processing errors
152 150
153 151 @ MSG_SYM_DIFFTYPE "symbol `%s' has differing types:"
154 152 @ MSG_SYM_DIFFATTR "symbol `%s' has differing %s:\n\
155 153 \t(file %s value=0x%x; file %s value=0x%x);"
156 154
157 155 @ _END_
158 156
159 157 # The following strings represent reserved names. Reference to
160 158 # these strings is via the MSG_ORIG() macro, and thus no
161 159 # translations are required.
162 160
163 161 @ MSG_STR_EMPTY ""
164 162 @ MSG_PTH_DEVZERO "/dev/zero"
165 163 @ MSG_SUNW_OST_SGS "SUNW_OST_SGS"
166 164
167 165
168 166 Using the above input files, the following string and message data
169 167 files can be generated:
170 168
171 169 % sgsmsg -i sgs.ident -m messages -d msg.c -h msg.h \
172 170 -n libld_msg libld.msg
173 171 % cat msg.c
174 172
175 173 const char __libld_msg[] = { 0x00,
176 174 0x66, 0x69, 0x6c, 0x65, 0x20, 0x25, 0x73, 0x3a, ....
177 175 0x61, 0x6e, 0x6e, 0x6f, 0x74, 0x20, 0x6f, 0x70, ....
178 176 ....
179 177 0x00
180 178 };
181 179
182 180 % cat msg.h
183 181
184 182 extern const char __libld_msg[];
185 183
186 184 #define MSG_ORIG(x) &__libld_msg[x]
187 185
188 186 extern const char * _libld_msg(int);
189 187
190 188 #define MSG_INTL(x) _libld_msg(x)
191 189
192 190 #define MSG_SYS_OPEN 1
193 191 #define MSG_SYS_MMAP 31
194 192 #define MSG_SYM_DIFFTYPE 61
195 193 #define MSG_SYM_DIFFATTR 94
196 194 #define MSG_STR_EMPTY 167
197 195 #define MSG_PTH_DEVZERO 168
198 196 #define MSG_SUNW_OST_SGS 178
199 197
200 198 % cat messages
201 199
202 200 # Message file for cmd/sgs/libld.
203 201
204 202 domain "SUNW_OST_SGS"
205 203
206 204 # System call messages
207 205
208 206 msgid "file %s: cannot open file: %s"
209 207 msgstr ""
210 208 msgid "file %s: cannot mmap file: %s"
211 209 msgstr ""
212 210
213 211 # Symbol processing errors
214 212
215 213 msgid "symbol `%s' has differing types:"
216 214 msgstr ""
217 215 msgid "symbol `%s' has differing %s:\n\t(file %s value=0x%x; file %s value=0x%x);"
218 216 msgstr ""
219 217
220 218
221 219 References to the string data from the code group should use one of the
222 220 two defined macros depending upon whether an original or localized
223 221 string is required. For example, the simple open(2) of a file would
224 222 use the original string, however its associated error message should be
225 223 localized:
226 224
227 225 const char * file = MSG_ORIG(MSG_PTH_DEVZERO);
228 226
229 227 if ((fd = open(file, O_RDWR, 0)) == -1) {
230 228 int err = errno;
231 229 (void) fprintf(stderr, MSG_INTL(MSG_SYS_OPEN), file,
232 230 strerror(err));
233 231 return (1);
234 232 }
235 233
236 234
237 235 The MSG_INTL definition provides for a user defined message extraction
238 236 function that allows the greatest flexibility in providing an objects
239 237 localization. Normally this interface is quite simple. For a code
240 238 group that resides in a shared object the following interface can be
241 239 provided by the user:
242 240
243 241 extern char * _dgettext(const char *, const char *);
244 242
245 243 const char *
246 244 _libld_msg(int mid)
247 245 {
248 246 return (_dgettext(MSG_ORIG(MSG_SUNW_OST_SGS),
249 247 MSG_ORIG(mid)));
250 248 }
251 249
252 250
253 251 For a code group that resides in an executable the following interface,
254 252 and initialization can be provided by the user:
255 253
256 254 #include <locale.h>
257 255
258 256 int
259 257 main(int argc, char ** argv)
260 258 {
261 259 ......
262 260 (void) setlocale(LC_MESSAGES, MSG_ORIG(MSG_STR_EMPTY));
263 261 (void) textdomain(MSG_ORIG(MSG_SUNW_OST_SGS));
264 262 ......
265 263 }
266 264
267 265 const char *
|
↓ open down ↓ |
118 lines elided |
↑ open up ↑ |
268 266 _ld_msg(int mid)
269 267 {
270 268 return (gettext(MSG_ORIG(mid)));
271 269 }
272 270
273 271
274 272 EXIT STATUS
275 273 A non-zero error return indicates a processing error.
276 274
277 275 SEE ALSO
278 - gencat(1), ld(1), msgfmt(1), catgets(3C), gettext(3I).
276 + gencat(1), ld(1), msgfmt(1), catgets(3C), gettext(3C).
279 277
280 278
281 279
282 - 2 Jun 1999 sgsmsg(1l)
280 + June 2, 1999 sgsmsg(1ONBLD)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX