bindtextdomain(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);

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

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


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
     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  dir-
     name.

     If  domainname is a non-empty string and has been bound pre-
     viously,  bindtextdomain()  replaces  the  old  binding with
     dirname. 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.


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
     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
           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
           domainname and path predicate dirname after a success-
           ful call to bindtextdomain()

     dirname/locale/LC_XXX/domainname.mo
           location for  files  containing  messages  for  domain
           domainname,  language  locale, and path predicate dir-
           name after a successful call to  bindtextdomain()  for
           dcgettext()  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       |
    | MT-Level                    | Safe with exceptions        |
    |_____________________________|_____________________________|


SEE ALSO

     msgfmt(1),   xgettext(1),   iconv_open(3C),   setlocale(3C),
     attributes(5), environ(5)

Man(1) output converted with man2html