Standard C Library Functions                          catopen(3C)


NAME

     catopen, catclose - open/close a message catalog


SYNOPSIS

     #include <nl_types.h>

     nl_catd catopen(const char *name, int oflag);

     int catclose(nl_catd catd);


DESCRIPTION

     The catopen() function opens a message catalog and returns a
     message  catalog descriptor.  name specifies the name of the
     message catalog to be opened. If name contains a  "/",  then
     name  specifies a complete pathname for the message catalog;
     otherwise, the environment  variable  NLSPATH  is  used  and
     /usr/lib/locale/locale/LC_MESSAGES  must  exist.  If NLSPATH
     does not exist in the environment, or if a  message  catalog
     cannot  be  opened in any of the paths specified by NLSPATH,
     then the default path /usr/lib/locale/locale/LC_MESSAGES  is
     used.  In  the  "C"  locale,  catopen()  will always succeed
     without checking the default search path.

     The names of message catalogs  and  their  location  in  the
     filesystem  can  vary from one system to another. Individual
     applications can choose to name or locate  message  catalogs
     according  to their own special needs. A mechanism is there-
     fore required to specify where the catalog resides.

     The NLSPATH variable provides both the location  of  message
     catalogs,  in the form of a search path, and the naming con-
     ventions associated with message catalog files.   For  exam-
     ple:

       NLSPATH=/nlslib/%L/%N.cat:/nlslib/%N/%L

     The metacharacter % introduces a substitution  field,  where
     %L  substitutes  the  current  setting  of  either  the LANG
     environment variable, if the value of oflag  is  0,  or  the
     LC_MESSAGES   category,   if   the   value   of   oflag   is
     NL_CAT_LOCALE, and %N substitutes  the  value  of  the  name
     parameter  passed to catopen().  Thus, in the above example,
     catopen() will search in  /nlslib/$LANG/name.cat,  if  oflag
     is  0,  or  in  /nlslib/{LC_MESSAGES}/name.cat,  if oflag is
     NL_CAT_LOCALE.

SunOS 5.11          Last change: 29 Dec 1996                    1


Standard C Library Functions                          catopen(3C)

     The NLSPATH variable will normally be set  up  on  a  system
     wide basis (in /etc/profile) and thus makes the location and
     naming conventions associated with  message  catalogs  tran-
     sparent to both programs and users.

     The full set of metacharacters is:

     %N    The value of the name parameter passed to catopen().

     %L    The value of LANG or LC_MESSAGES.

     %l    The  value  of  the  language  element  of   LANG   or
           LC_MESSAGES.

     %t    The  value  of  the  territory  element  of  LANG   or
           LC_MESSAGES.

     %c    The  value  of  the  codeset  element   of   LANG   or
           LC_MESSAGES.

     %%    A single %.

     The  LANG  environment  variable  provides  the  ability  to
     specify  the user's requirements for native languages, local
     customs and character set, as an ASCII string in the form

       LANG=language[_territory[.codeset]]

     A user who speaks German as it is spoken in Austria and  has
     a  terminal which operates in ISO 8859/1 codeset, would want
     the setting of the LANG variable to be

       LANG=De_A.88591

     With this setting it should be possible  for  that  user  to
     find any relevant catalogs should they exist.

     Should  the  LANG  variable  not  be  set,  the   value   of
     LC_MESSAGES  as returned by setlocale() is used.  If this is

SunOS 5.11          Last change: 29 Dec 1996                    2


Standard C Library Functions                          catopen(3C)

     NULL, the default path as defined in <nl_types.h> is used.

     A message catalogue descriptor remains valid  in  a  process
     until that process closes it, or a successful call to one of
     the  exec  functions.  A  change  in  the  setting  of   the
     LC_MESSAGES  category  may  invalidate existing open catalo-
     gues.

     If a file descriptor is used to implement message  catalogue
     descriptors, the FD_CLOEXEC flag will be set; see <fcntl.h>.

     If the value of oflag argument is 0,  the  LANG  environment
     variable  is  used to locate the catalogue without regard to
     the  LC_MESSAGES  category.   If  the  oflag   argument   is
     NL_CAT_LOCALE,  the  LC_MESSAGES  category is used to locate
     the message catalogue.

     The catclose() function closes the message  catalog  identi-
     fied by catd.  If a file descriptor is used to implement the
     type nl_catd, that file descriptor will be closed.


RETURN VALUES

     Upon successful  completion,  catopen()  returns  a  message
     catalog descriptor for use on  subsequent calls to catgets()
     and catclose().  Otherwise it returns (nl_catd) -1.

     Upon successful completion, catclose() returns 0.  Otherwise
     it returns -1 and sets errno to indicate the error.


ERRORS

     The catopen() function may fail if:

     EACCES          Search permission is  denied  for  the  com-
                     ponent  of  the  path  prefix of the message
                     catalogue or read permission is  denied  for
                     the message catalogue.

     EMFILE          There   are   OPEN_MAX   file    descriptors
                     currently open in the calling process.

     ENAMETOOLONG    The length of the pathname  of  the  message
                     catalogue  exceeds  PATH_MAX,  or a pathname
                     component is longer than NAME_MAX.

SunOS 5.11          Last change: 29 Dec 1996                    3


Standard C Library Functions                          catopen(3C)

     ENAMETOOLONG    Pathname resolution of a symbolic link  pro-
                     duced  an  intermediate  result whose length
                     exceeds PATH_MAX.

     ENFILE          Too many files are  currently  open  in  the
                     system.

     ENOENT          The message catalogue does not exist or  the
                     name argument points to an empty string.

     ENOMEM          Insufficient storage space is available.

     ENOTDIR         A component of the path prefix of  the  mes-
                     sage catalogue is not a directory.

     The catclose() function may fail if:

     EBADF    The catalogue descriptor is not valid.

     EINTR    The catclose() function was interrupted by  a  sig-
              nal.


USAGE

     The catopen() and catclose() functions can be used safely in
     multithreaded  applications, as long as setlocale(3C) is not
     being called to change the locale.


ATTRIBUTES

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

SunOS 5.11          Last change: 29 Dec 1996                    4


Standard C Library Functions                          catopen(3C)

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     gencat(1),  catgets(3C),   gettext(3C),   nl_types.h(3HEAD),
     setlocale(3C), attributes(5), environ(5)

SunOS 5.11          Last change: 29 Dec 1996                    5


Man(1) output converted with man2html


FhG Schily's Home VED powered