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.

0

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 \f2ident\f1 file provides message \f2identifiers\f1 for the link-editor utilities ld (1), libld.so.2 , and liblddbg.so.3 . These identifiers are referenced from the input string definition files of the respective code groups:

% cat sgs.ident
# mesgid setid domain
MSG_ID_LD 1 SUNW_OST_SGS
MSG_ID_LIBLD 2 SUNW_OST_SGS
MSG_ID_LIBLDDBG 3 SUNW_OST_SGS

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

% cat libld.msg
@ _START_
# Message file for cmd/sgs/libld.
@ MSG_ID_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_STR_EMPTY ""
@ MSG_PTH_DEVZERO "/dev/zero"
@ MSG_SUNW_OST_SGS "SUNW_OST_SGS"

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, \.\.\.\.
 \.\.\.\.
 0x00
};

% 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_SYM_DIFFTYPE 61
#define MSG_SYM_DIFFATTR 94
#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,
 strerror(err));
 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),
 MSG_ORIG(mid)));
}

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

#include <locale.h>

int
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)));
}