Intl(3sadm)

Intl -- internationalization management routines

Synopsis

C++ interface

CC ... -lsysadm -lvtcl -ltclx -ltcl -lsocket -lgen -lm

#include "scoadmin/basicIncl.h"

intlMgr_cl *intlMgrPtr;

localMsg_t*
intlMgr_cl::Localize (const intlMsg_t  *intlMsgPtr,
                      ...);

localMsg_t*
intlMgr_cl::VLocalize (const intlMsg_t  *intlMsgPtr,
                       va_list          argsPtr);

char *
intlMgr_cl::LocalizeExt (const intlMsg_t *intlMsgPtr,
                         unsigned         options,
                         ...);

char *
intlMgr_cl::VLocalizeExt (const intlMsg_t *intlMsgPtr,
                          unsigned         options,
                          va_list          argsPtr);

const char *
intlMgr_cl::LocalizeMsg (const intlMsg_t *intlMsgPtr,
                         ...)

localMsg_t*
intlMgr_cl::LocalizeNonStd (const intlMsg_t &intlMsgPtr,
                            const char      *message);

char *
intlMgr_cl::LocalizeExtNonStd (const intlMsg_t &intlMsgPtr,
                               unsigned         options,
                               const char      *message);

const intlMsg_t *
intlMgr_cl::GetUnixMsg (int errorNum)

C interface

CC ... -lsysadm -lvtcl -ltclx -ltcl -lsocket -lgen -lm

#include "scoadmin/basicIncl.h"

void
IntlMgrInit ();

localMsg_t*
IntlLocalize (const intlMsg_t *intlMsgPtr,
              ...);

localMsg_t*
IntlVLocalize (const intlMsg_t *intlMsgPtr,
               ...);

char *
IntlLocalizeExt (const intlMsg_t *intlMsgPtr,
                 unsigned         options,
                 ...);

char *
IntlVLocalizeExt (const intlMsg_t *intlMsgPtr,
                  unsigned         options,
                  ...);

const char *
IntlLocalizeMsg (const intlMsg_t *intlMsgPtr,
                 ...);

localMsg_t*
IntlLocalizeNonStd (const intlMsg_t *intlMsgPtr,
                    const char      *message);

char *
IntlLocalizeExtNonStd (const intlMsg_t *intlMsgPtr,
                       unsigned         options,
                       const char      *message);

const intlMsg_t *
IntlGetUnixMsg (int  errorNum);

Description

The international management interface includes C and C++ versions. The C interface parallels the member functions to the intlMgr_cl class. The descriptions provided focus on the C++ interface, with the C version indicated in parentheses. All routines use the global internationalization manager; there is no way to create a new intlMgr_cl object from C.

WARNING: If the main or the program is written in C instead of C++, then IntlMgrInit must be called before any use of either the internationalization or error managers, either directly or by indirectly calling C++ code that uses these facilities.

The intlMgr_cl class provides support routines to localize and manipulate internationalized messages. One instance of this class should exist in a process. It internally manages the opening of messages catalogs on an as needed basis.

IntlMgrInit initializes the global intlMgr_cl object. This is only used if the main of a program is in C rather than C++.

intlMgrPtr is a pointer to a single, global, object of this class that is available for use in a process. While multiple intlMgr_cl objects will work, there is no advantage and it may result in message catalogs being opened multiple times.

Localize localizes a message, returning the localized message structure. Returns a pointer to a dynamically allocated structure containing the localized message as well as the module id and message set number. This structure is dynamically allocated with both the struct and the strings contained in one malloc allocation unit. A single call to free will be required to release it. (C interface: IntlLocalize.)

VLocalize localizes a message, returning the localized message structure. This version is to be called after va_start has found the first parameter. Returns a pointer to a dynamically allocated structure containing the localized message as well as the module id and message set number. This structure is dynamically allocated with both the struct and the strings contained in one malloc allocation unit. A single call to free will be required to release it. (C interface: IntlVLocalize.)

LocalizeExt localizes a message returning the localized string, either as plain localized text or in the Tcl localized message format. Returns a pointer to a string containing either a Tcl list or a plain text string, with the localized message. If INTLMGR_STATIC is specified, then it is a pointer to a static string. The string remains valid until another message is localized or the object is deleted. The pointer should not be freed. If INTLMGR_DYNAMIC is specified, then it is a pointer to a dynamically allocated string. Use free to release the storage, not delete. (C interface: IntlLocalizeExt.)

VLocalizeExt localizes a message returning the localized string, either as plain localized text or in the Tcl localized message format. This version is to be called after va_start has found the first parameter. Returns a pointer to a string containing either a Tcl list or a plain text string, with the localized message. If INTLMGR_STATIC is specified, then it is a pointer to a static string. The string remains valid until another message is localized or the object is deleted. The pointer should not be freed. If INTLMGR_DYNAMIC is specified, then it is a pointer to a dynamically allocated string. Use free to release the storage, not delete. (C interface: IntlVLocalizeExt.)

LocalizeMsg localizes a message returning the localized plain localized text as in a transient static. This is a short cut for calling LocalizeExt with the INTLMGR_TEXT and INTLMGR_STATIC options Returns a pointer to a string containing a plain text string, with the localized message. This is a pointer to a static string. The string remains valid until another message is localized or the object is deleted. The pointer should not be freed. (C interface: IntlLocalizeMsg.)

LocalizeNonStd takes a non-standard message and builds a standard localized message structure. Returns a pointer to a dynamically allocated structure containing the localized message as well as the module id and message set number. This structure is dynamically allocated with both the struct and the strings contained in one malloc allocation unit. A single call to free will be required to release it. (C interface: IntlLocalizeNonStd.)

LocalizeExtNonStd takes a non-standard message and builds a standard localized message as either a plain text string or a string in the Tcl localized message format. Returns a pointer to a string containing either a Tcl list or a plain text string, with the localized message. If INTLMGR_STATIC is specified, then it is a pointer to a static string. The string remains valid until another message is localized or the object is deleted. The pointer should not be freed. If INTLMGR_DYNAMIC is specified, then it is a pointer to a dynamically allocated string. Use free to release the storage, not delete. (C interface: IntlLocalizeExtNonStd.)

GetUnixMsg locates the internationalized message associated with a UNIX errno. If the number is out of the valid range, UNIX_ERR_ERRNO_OUT_OF_RANGE is returned. Returns a pointer to a statically allocated internationalized message declaration. (C interface: IntlGetUnixMsg.)

Arguments

other arguments

arguments to format into the localized string as with sprintf. All arguments must have a corresponding format specification in the string taken from the message catalog.

argsPtr

the pointer returned by va_start for the arguments to format into the message.

message

the message returned from a program that does not conform to the system administration internationalization standard.

errorNum

the UNIX errno error number.

intlMsgPtr

a pointer to the declaration of the non-standard message for a specific utility that does use the standard internationalization and error management. This must be a static structure.

options

controlling the localization of the message:

INTLMGR_EXT_FORMAT - convert to the external, Tcl list format.
INTLMGR_TEXT - convert to a localized text string. This is really a pass through option, returning the string unchanged.
INTLMGR_STATIC - do not allocate the message dynamically; instead return a pointer to a static buffer within the object.
INTLMGR_DYNAMIC - dynamically allocate the message. If neither dynamic or static is specified, static is assumed.

References

Intl(3sadm)