sgsmsg(1ONBLD) illumos Build Tools sgsmsg(1ONBLD)

sgsmsg - generate message strings for SGS subsystem.

sgsmsg [ -cl ] [ -d data ] [ -h defs ] [ -i ident ] [ -m messages ] [ -n name ] file ...

SUNWonld

sgsmsg generates several message files from an input string definition file. sgsmsg 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 data 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 defs 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 messages file. By default these message strings are suitable for gettext(3I) manipulation. The -c option provides for these message strings to be translated into a form suitable for catgets(3C) manipulation.

One of more input files 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 file:

  • Entries that begin with a #, $ or a newline are treated as comments and are copied (as is) to the messages file.
  • Entries that begin with a @ 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 @ character.

An @ character followed by a single token is interpreted as one of two reserved message output indicators, or a message identifier. The reserved output indicator _START_ enables output to the messages file (note that the occurrence of any @ token will also enable message output). The reserved output indicator _END_ disables output to the messages file. These two indicators provides a means of isolating only those character strings that require translation into the messages file.

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

An @ character followed by multiple tokens is taken to be a string definition 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 \n for newline, \t for tab, \v for vertical tab, \b for backspace, \r for carriage return, \f for formfeed, \\ for backslash, and \" for double quote.

The character string is copied to the data array and an index into this array is generated as the definition within the string defs file. The character string is also translated to the appropriate message format and written to the messages file.

-c
By default, strings generated in the messages 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 data
Specify a data file is to be created. This file contains a single data array, by default named (__name[]), containing all the strings defined in the string definition file.
-h defs
Specify a defs file is to be created. This file contains definitions for each character string contained in the data array within the data file. These definitions represent offsets in the data array for each string. Reference to individual strings should use one of the two defined macros MSG_INTL (which specifies a user defined message extraction function), or MSG_ORIG (which specifies a direct access to the __name[] array).
-i ident
Specify an ident file from which to interpret a message identifier token.
-l
Indicate that the data array be defined local (static). This is useful for establishing individual string arrays on a per-object basis.
-m messages
Specify a messages file is to be created. This contain message strings suitable for delivery to a localization group.
-n name
Specify an alternative interface name. This name is used to label the message data array (__name[]) and the user defined message extraction function (const char * _name(int)) which will interface with this array.

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

The following ident file provides message identifiers 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 file 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 MSG_INTL 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)));
}

A non-zero error return indicates a processing error.

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