Copyright 2005 Sun Microsystems, Inc. All rights reserved.
Use is subject to license terms.


The contents of this file are subject to the terms of the
Common Development and Distribution License, Version 1.0 only
(the "License"). You may not use this file except in compliance
with the License.

You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
See the License for the specific language governing permissions
and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]


sgsmsg 1ONBLD "Jun 2, 1999"
sgsmsg - generate message strings for SGS subsystem.
sgsmsg [ -cl ] [ -d\0 "data" ] [ -h\0 "defs" ] [ -i\0 "ident" ] [ -m\0 "messages" ] [ -n\0 "name" ] file \.\.\.
\f3sgsmsg\f1 generates several message files from an input string definition \f2file\f1. \f3sgsmsg\f1 provides a flexible, centralized, mechanism of collecting character strings within a code group such as an executable or shared object. All character strings are captured into a single data array within the \f2data\f1 file. The data array is similar to that produced by xstr (1)), and helps reduce the relocation overhead incurred by string pointers.

Indexes into the data array are generated as definitions within the \f2defs\f1 file. The code group can reference each character string via predefined macros.

The character strings may also be translated into an internationalized format and captured in the \f2messages\f1 file. By default these message strings are suitable for gettext (3I) manipulation. The \f3-c\f1 option provides for these message strings to be translated into a form suitable for catgets (3C) manipulation.

One of more input \f2file\f1s contains a definition for each character string used by a particular code group. The interpretation of a definition is determined by the first character of each line within the input \f2file\f1:


\(bu 3
Entries that begin with a \f3#, \f3$\f1 or a newline are treated as comments and are copied (as is) to the \f2messages\f1 file.
\(bu 3
Entries that begin with a \f3@\f1 are translated and will be written to one or more of the output files. Two translations are possible dependent upon whether one or more tokens follow the \f3@\f1 character.

An \f4@\f1 character followed by a single token is interpreted as one of two reserved message output \f2indicators\f1, or a message \f2identifier\f1. The reserved output indicator \f4_START_\f1 enables output to the \f2messages\f1 file (note that the occurrence of any \f4@\f1 token will also enable message output). The reserved output indicator \f4_END_\f1 disables output to the \f2messages\f1 file. These two indicators provides a means of isolating only those character strings that require translation into the \f2messages\f1 file.

Besides the reserved output indicators, an \f4@\f1 character followed by a single token is taken to be a message \f2identifier\f1. This identifier will be translated into a \f2domain\f1 name for gettext (3I) output, or a \f2setid\f1 for catgets (3C) output. This translated value is determine by substituting the message \f2identifier\f1 token for the associated definition from in the \f2ident\f1 file. Note that a message \f2identifier\f1 is required for catgets (3C) use but is optional for gettext (3I).

An \f4@\f1 character followed by multiple tokens is taken to be a string \f2definition\f1 followed by a quoted character string. Character strings can be continued over multiple lines by ending the preceding line with a backslash - all initial whitespace on the continuation line will is ignored. Character strings can contain the escape sequences \en for newline, \et for tab, \ev for vertical tab, \eb for backspace, \er for carriage return, \ef for formfeed, \e\e for backslash, and \e" for double quote.

The character string is copied to the \f2data\f1 array and an index into this array is generated as the \f2definition\f1 within the string \f2defs\f1 file. The character string is also translated to the appropriate message format and written to the \f2messages\f1 file.


12 -c By default, strings generated in the \f2messages\f1 file are suitable for msgfmt (1) processing, which provides for message extraction via gettext (3I). This option causes the formatting of the message strings to be suitable for gencat (1) processing, which provides for message extraction via catgets (3C).

-d\0 data Specify a \f2data\f1 file is to be created. This file contains a single data array, by default named (\f2__name\f1[]), containing all the strings defined in the string definition \f2file\f1.

-h\0 defs Specify a \f2defs\f1 file is to be created. This file contains definitions for each character string contained in the data array within the \f2data\f1 file. These definitions represent offsets in the data array for each string. Reference to individual strings should use one of the two defined macros \f4MSG_INTL\f1 (which specifies a user defined message extraction function), or \f4MSG_ORIG\f1 (which specifies a direct access to the \f2__name\f1[] array).

-i\0 ident Specify an \f2ident\f1 file from which to interpret a message identifier token.

-l Indicate that the \f2data\f1 array be defined local (\f2static\f1). This is useful for establishing individual string arrays on a per-object basis.

-m\0 messages Specify a \f2messages\f1 file is to be created. This contain message strings suitable for delivery to a localization group.

-n\0 name Specify an alternative interface \f2name\f1. This name is used to label the message data array (\f2__name\f1[]) and the user defined message extraction function (const char * \f2_name\f1(int)) which will interface with this array.

The following examples provide a simplified guide to using the \f3sgsmsg command, including sample input files and generated output files.

The following \f2ident\f1 file provides message \f2identifiers\f1 for the link-editor utilities ld (1), , and . These identifiers are referenced from the input string definition files of the respective code groups:

% cat sgs.ident
# mesgid setid domain

The following string definition \f2file\f1 defines a small number of strings used by :

% cat libld.msg
# Message file for cmd/sgs/libld.

# System call messages
@ MSG_SYS_OPEN "file %s: cannot open file: %s"
@ MSG_SYS_MMAP "file %s: cannot mmap file: %s"

# Symbol processing errors
@ MSG_SYM_DIFFTYPE "symbol `%s' has differing types:"
@ MSG_SYM_DIFFATTR "symbol `%s' has differing %s:\\n\\
  \\t(file %s value=0x%x; file %s value=0x%x);"
@ _END_

# The following strings represent reserved names. Reference to
# these strings is via the MSG_ORIG() macro, and thus no
# translations are required.
@ MSG_PTH_DEVZERO "/dev/zero"

Using the above input files, the following string and message data files can be generated:

% sgsmsg  -i sgs.ident  -m messages  -d msg.c  -h msg.h \\
    -n libld_msg  libld.msg
% cat msg.c
const char __libld_msg[] = { 0x00,
 0x66, 0x69, 0x6c, 0x65, 0x20, 0x25, 0x73, 0x3a, \.\.\.\.
 0x61, 0x6e, 0x6e, 0x6f, 0x74, 0x20, 0x6f, 0x70, \.\.\.\.

% cat msg.h
extern const char __libld_msg[];
#define MSG_ORIG(x) &__libld_msg[x]
extern const char * _libld_msg(int);
#define MSG_INTL(x) _libld_msg(x)
#define MSG_SYS_OPEN 1
#define MSG_SYS_MMAP 31
#define MSG_STR_EMPTY 167
#define MSG_PTH_DEVZERO 168
#define MSG_SUNW_OST_SGS 178

% cat messages
# Message file for cmd/sgs/libld.
domain "SUNW_OST_SGS"
# System call messages
msgid "file %s: cannot open file: %s"
msgstr ""
msgid "file %s: cannot mmap file: %s"
msgstr ""
# Symbol processing errors
msgid "symbol `%s' has differing types:"
msgstr ""
msgid "symbol `%s' has differing %s:\\n\\t(file %s value=0x%x; file %s value=0x%x);"
msgstr ""

References to the string data from the code group should use one of the two defined macros depending upon whether an original or localized string is required. For example, the simple open (2) of a file would use the original string, however its associated error message should be localized:

const char * file = MSG_ORIG(MSG_PTH_DEVZERO);
if ((fd = open(file, O_RDWR, 0)) == -1) {
 int err = errno;
 (void) fprintf(stderr, MSG_INTL(MSG_SYS_OPEN), file,
 return (1);

The \f3MSG_INTL\f1 definition provides for a user defined message extraction function that allows the greatest flexibility in providing an objects localization. Normally this interface is quite simple. For a code group that resides in a shared object the following interface can be provided by the user:

extern char * _dgettext(const char *, const char *);
const char *
_libld_msg(int mid)
 return (_dgettext(MSG_ORIG(MSG_SUNW_OST_SGS),

For a code group that resides in an executable the following interface, and initialization can be provided by the user:

#include <locale.h>

main(int argc, char ** argv)
 (void) setlocale(LC_MESSAGES, MSG_ORIG(MSG_STR_EMPTY));
 (void) textdomain(MSG_ORIG(MSG_SUNW_OST_SGS));

const char *
_ld_msg(int mid)
 return (gettext(MSG_ORIG(mid)));
A non-zero error return indicates a processing error.

gencat (1), ld (1), msgfmt (1), catgets (3C), gettext (3C).