gettext(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨페이지이름
검색(S)

gettext

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

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  in  its  entirety  first  for  the location of the
     LC_MESSAGES  catalogue.  The  setting  of  the   LC_MESSAGES
     category of the current locale determines the locale used by
     gettext() and dgettext() for string  retrieval.  If  NLSPATH
     contains  %L  and  the  current  value  of it is a canonical
     locale name to an obsoleted Solaris locale name as described
     in  locale_alias(5)  and there is no message catalog for the
     canonical locale name, for a better backward  compatibility,
     gettext()  and  dgettext()  use the obsoleted Solaris locale
     names in place for %L as aliases for  the  canonical  locale
     name  and  try  to  locate the desired message catalogue. If
     that still does not yield a message catalogue and the  value
     of  %L  is  an  accepted  and supported locale name alias as
     described in locale_alias(5), the matching canonical  locale
     name  is  used in place for %L to locate the desired message
     catalogue. The category argument determines the locale  used
     by  dcgettext().  If  NLSPATH is not defined and the current
     locale is "C", gettext(), dgettext(), 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 following paragraph.


     The  LANGUAGE  environment  variable  is  examined  in   its
     entirety  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 message catalogue is found, it is
     used to return target strings.  If no GNU-compatible message
     catalogue is found for all locales specified in the LANGUAGE
     and if there are accepted and supported locale name  aliases
     for any of the locale names in the LANGUAGE, as specified in
     locale_alias(5) and in the same manner as described  in  the
     NLSPATH  description  at  the  above  for %L and the current
     locale name, the locale name aliases are used once again  to
     search  corresponding   GNU-compatible  message  catalogues.
     If a GNU-compatible message catalogue is found but failed to
     find a corresponding msgid, the msgid string is returned. 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(). In this last stage of search of mes-
     sage catalogue, if there is no message catalogue found  with
     the  locale  name  and  if  the  locale  name has aliases as
     described in locale_alias(5), the locale  name  aliases  are
     used  in  place  of  the  locale  name to locate the message
     catalogue in the same manner as described in the  above  for
     the  processing  of  the  locale name aliases of the locales
     defined at the LANGUAGE.


     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.


     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
     dcngettext() is a null pointer, 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 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:



     tab() box; lw(2.75i) |lw(2.75i) lw(2.75i) |lw(2.75i)  ATTRI-
     BUTE  TYPEATTRIBUTE VALUE _ Interface StabilitySee below.  _
     MT-LevelSafe with exceptions



     The     external     variables     _nl_msg_cat_cntr      and
     _nl_domain_bindings  are  Uncommitted. Otherwise, the inter-
     face is Committed.

See Also
     msgfmt(1),  xgettext(1),  iconv_open(3C),  libintl.h(3HEAD),
     setlocale(3C), attributes(5), environ(5), locale_alias(5)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 1.0 CSS3