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