Standard C Library Functions                          gettext(3C)


NAME

     gettext, dgettext, dcgettext, ngettext,  dngettext,  dcnget-
     text,  textdomain, bindtextdomain, bind_textdomain_codeset -
     message handling functions


SYNOPSIS

  Solaris and GNU-compatible
     #include <libintl.h>

     char *gettext(const char *msgid);

     char *dgettext(const char *domainname, const char *msgid);

     char *textdomain(const char *domainname);

     char *bindtextdomain(const char *domainname, const char *dirname);

     #include <libintl.h>
     #include <locale.h>

     char *dcgettext(const char *domainname, const char *msgid,
          int category);

  GNU-compatible
     #include <libintl.h>

     char *ngettext(const char *msgid1, const char *msgid2,
          unsigned long int n);

     char *dngettext(const char *domainname, const char *msgid1,
          const char *msgid2, unsigned long int n);

     char *bind_textdomain_codeset(const char *domainname,
          const char *codeset);

     extern int _nl_msg_cat_cntr;
     extern int *_nl_domain_bindings;

     #include <libintl.h>
     #include <locale.h>

     char *dcngettext(const char *domainname, const char *msgid1,
          const char *msgid2, unsigned long int n, int category);

SunOS 5.11           Last change: 4 Jun 2008                    1


Standard C Library Functions                          gettext(3C)


DESCRIPTION

     The gettext(), dgettext(), and dcgettext() functions attempt
     to  retrieve  a  target  string based on the specified msgid
     argument within the context of a  specific  domain  and  the
     current locale. The length of strings returned by gettext(),
     dgettext(), and dcgettext() is undetermined until the  func-
     tion  is  called.  The  msgid  argument is a null-terminated
     string.

     The ngettext(), dngettext(), and dcngettext() functions  are
     equivalent   to   gettext(),  dgettext(),  and  dcgettext(),
     respectively, except  for  the  handling  of  plural  forms.
     These   functions  work  only  with  GNU-compatible  message
     catalogues.  The ngettext(), dngettext(),  and  dcngettext()
     functions  search  for  the  message string using the msgid1
     argument as the key and the  n  argument  to  determine  the
     plural  form.  If no message catalogues are found, msgid1 is
     returned if n == 1, otherwise msgid2 is returned.

     The  NLSPATH  environment  variable  (see   environ(5))   is
     searched  first  for the location of the LC_MESSAGES catalo-
     gue. The setting of the LC_MESSAGES category of the  current
     locale  determines  the  locale  used by gettext() and dget-
     text() for string retrieval. The  category  argument  deter-
     mines  the  locale  used  by  dcgettext(). If NLSPATH is not
     defined and the current  locale  is  "C",  gettext(),  dget-
     text(),  and  dcgettext()  simply  return the message string
     that was passed.  In a locale  other than "C", if NLSPATH is
     not defined or if a message catalogue is not found in any of
     the components specified by NLSPATH, the routines search for
     the message catalogue using the scheme described in the fol-
     lowing paragraph.

     The LANGUAGE environment variable is examined  to  determine
     the  GNU-compatible message catalogues to be used. The value
     of LANGUAGE is a list of locale names separated by  a  colon
     (':')  character.   If LANGUAGE is defined, each locale name
     is tried in the specified order and if a GNU-compatible mes-
     sage  catalogue  is  found,  the  message is returned.  If a
     GNU-compatible message catalogue is found but failed to find
     a  corresponding  msgid,  the  msgid  string  is  return. If
     LANGUAGE is not defined or if a Solaris message catalogue is
     found  or  no  GNU-compatible  message catalogue is found in
     processing LANGUAGE, the pathname used to locate the message
     catalogue  is  dirname/locale/category/domainname.mo,  where
     dirname is  the  directory  specified  by  bindtextdomain(),
     locale  is a locale name, and category is either LC_MESSAGES
     if gettext(),  dgettext(),  ngettext(),  or  dngettext()  is
     called,  or  LC_XXX where the name is the same as the locale

SunOS 5.11           Last change: 4 Jun 2008                    2


Standard C Library Functions                          gettext(3C)

     category name specified by the category argument  to  dcget-
     text() or dcngettext().

     For gettext() and ngettext(), the domain used is set by  the
     last  valid  call  to  textdomain().   If  a  valid  call to
     textdomain() has not been made, the default domain   (called
     messages) is used.

     For dgettext(), dcgettext(), dngettext(), and  dcngettext(),
     the domain used is specified by the domainname argument. The
     domainname argument is equivalent in syntax and  meaning  to
     the  domainname  argument  to  textdomain(), except that the
     selection of the domain is valid only for  the  duration  of
     the  dgettext(),  dcgettext(),  dngettext(), or dcngettext()
     function call.

     The textdomain() function sets or queries the  name  of  the
     current  domain  of  the active LC_MESSAGES locale category.
     The domainname argument is a null-terminated string that can
     contain only the characters allowed in legal filenames.

     The domainname argument is the unique name of  a  domain  on
     the  system.   If  there  are  multiple versions of the same
     domain on one system, namespace collisions can be avoided by
     using  bindtextdomain().   If  textdomain() is not called, a
     default domain is selected. The setting of  domain  made  by
     the  last  valid  call  to textdomain() remains valid across
     subsequent calls to setlocale(3C), and gettext().

     The domainname argument is applied to the  currently  active
     LC_MESSAGES locale.

     The current setting of the domain  can  be  queried  without
     affecting  the  current  state  of  the  domain  by  calling
     textdomain() with domainname set to the null  pointer.  Cal-
     ling  textdomain()  with  a  domainname  argument  of a null
     string sets the domain to the default domain (messages).

     The bindtextdomain() function binds the path predicate for a
     message domain domainname to the value contained in dirname.
     If domainname is a non-empty string and has not  been  bound
     previously, bindtextdomain() binds domainname with dirname.

SunOS 5.11           Last change: 4 Jun 2008                    3


Standard C Library Functions                          gettext(3C)

     If domainname is a non-empty string and has been bound  pre-
     viously, bindtextdomain() replaces the old binding with dir-
     name.  The dirname argument can be an absolute  or  relative
     pathname  being  resolved  when  gettext(),  dgettext(),  or
     dcgettext() are called. If domainname is a null  pointer  or
     an empty string, bindtextdomain() returns NULL. User defined
     domain names cannot begin  with  the  string  SYS_.   Domain
     names  beginning  with  this  string are reserved for system
     use.

     The  bind_textdomain_codeset()  function  can  be  used   to
     specify the output codeset for message catalogues for domain
     domainname.  The codeset argument must be  a  valid  codeset
     name  that can be used for the iconv_open(3C) function, or a
     null pointer. If the codeset argument is the  null  pointer,
     bind_textdomain_codeset()  returns  the  currently  selected
     codeset for the domain with the name domainname.  It returns
     a  null  pointer if a codeset has not yet been selected. The
     bind_textdomain_codeset()  function  can  be  used  multiple
     times.   If  used  multiple  times  with the same domainname
     argument, the later call overrides the settings made by  the
     earlier  one. The bind_textdomain_codeset() function returns
     a pointer to a string containing the name  of  the  selected
     codeset.  The string is allocated internally in the function
     and must not be changed by the user.

     The     external     variables     _nl_msg_cat_cntr      and
     _nl_domain_bindings  are provided for the compatibility with
     the GNU gettext() implementation.


RETURN VALUES

     The gettext(), dgettext(), and dcgettext() functions  return
     the  message  string  if the search succeeds. Otherwise they
     return the msgid string.

     The  ngettext(),  dngettext(),  and  dcngettext()  functions
     return  the  message  string if the search succeeds.  If the
     search fails, msgid1 is returned if n == 1. Otherwise msgid2
     is returned.

     The individual bytes of the string  returned  by  gettext(),
     dgettext(), dcgettext(), ngettext(), dngettext(), or dcnget-
     text() can contain any value other than NULL.  If msgid is a
     null  pointer,  the  return  value  is undefined. The string
     returned must not be modified by  the  program  and  can  be
     invalidated      by      a      subsequent      call      to
     bind_textdomain_codeset() or setlocale(3C).  If the  domain-
     name  argument  to   dgettext(),dcgettext(), dngettext(), or

SunOS 5.11           Last change: 4 Jun 2008                    4


Standard C Library Functions                          gettext(3C)

     dcngettext() is a null pointer,  the  the  domain  currently
     bound by textdomain() is used.

     The normal return value from textdomain() is a pointer to  a
     string  containing  the  current  setting  of the domain. If
     domainname is a null pointer, textdomain() returns a pointer
     to the string containing the current domain. If textdomain()
     was not previously called and domainname is a  null  string,
     the name of the default domain is returned.  The name of the
     default domain is messages.  If textdomain() fails,  a  null
     pointer is returned.

     The return value from bindtextdomain() is a  null-terminated
     string  containing  dirname or the directory binding associ-
     ated with domainname if dirname is NULL. If  no  binding  is
     found,  the  default  return  value  is /usr/lib/locale.  If
     domainname  is  a  null  pointer   or   an   empty   string,
     bindtextdomain() takes no action and returns a null pointer.
     The string returned must not be modified by the  caller.  If
     bindtextdomain() fails, a null pointer is returned.


USAGE

     These functions impose no limit on message length.  However,
     a text domainname is limited to TEXTDOMAINMAX (256) bytes.

     The gettext(), dgettext(), dcgettext(),  ngettext(),  dnget-
     text(),  dcngettext(),  textdomain(),  and  bindtextdomain()
     functions can be used safely in multithreaded  applications,
     as  long  as setlocale(3C) is not being called to change the
     locale.

     The gettext(), dgettext(),  dcgettext(),  textdomain(),  and
     bindtextdomain()  functions  work  with both Solaris message
     catalogues and GNU-compatible message catalogues.  The nget-
     text(),         dngettext(),        dcngettext(),        and
     bind_textdomain_codeset()  functions  work  only  with  GNU-
     compatible  message  catalogues.  See msgfmt(1) for informa-
     tion about Solaris  message  catalogues  and  GNU-compatible
     message catalogues.


FILES

     /usr/lib/locale

         default path predicate for message domain files

     /usr/lib/locale/locale/LC_MESSAGES/domainname.mo

SunOS 5.11           Last change: 4 Jun 2008                    5


Standard C Library Functions                          gettext(3C)

         system default location for file containing messages for
         language locale and domainname

     /usr/lib/locale/locale/LC_XXX/domainname.mo

         system default location for file containing messages for
         language  locale  and  domainname  for dcgettext() calls
         where   LC_XXX   is   LC_CTYPE,   LC_NUMERIC,   LC_TIME,
         LC_COLLATE, LC_MONETARY, or LC_MESSAGES

     dirname/locale/LC_MESSAGES/domainname.mo

         location for file containing messages for domain domain-
         name  and path predicate dirname after a successful call
         to bindtextdomain()

     dirname/locale/LC_XXX/domainname.mo

         location  for  files  containing  messages  for   domain
         domainname,  language locale, and path predicate dirname
         after a successful call to bindtextdomain()  for  dcget-
         text()   calls   where   LC_XXX   is  one  of  LC_CTYPE,
         LC_NUMERIC,   LC_TIME,   LC_COLLATE,   LC_MONETARY,   or
         LC_MESSAGES


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    | ATTRIBUTE TYPE              | ATTRIBUTE VALUE             |
    |_____________________________|_____________________________|
    | Interface Stability         | See below.                  |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe with exceptions        |
    |_____________________________|_____________________________|

     The     external     variables     _nl_msg_cat_cntr      and
     _nl_domain_bindings are Uncommitted.


SEE ALSO

     msgfmt(1),  xgettext(1),  iconv_open(3C),  libintl.h(3HEAD),
     setlocale(3C), attributes(5), environ(5)

SunOS 5.11           Last change: 4 Jun 2008                    6


Man(1) output converted with man2html


FhG Schily's Home VED powered