catopen(S)                     6 January 1993                     catopen(S)


 Name

    catopen, catclose - open/close a message catalog

 Syntax


    cc  . . .  -lintl


    #include  <nl_types.h>

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

    int catclose (catd)
    nl_catd catd;


 Description

    catopen opens a message catalog and returns a catalog descriptor for use
    by catgets(S).  The name argument is the name of the message catalog to
    be opened.  If name contains a ``/'' then name specifies a pathname for
    the message catalog.  Otherwise, the environment variable NLSPATH is used
    with name substituted for %N (see environ(M)).  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 /usr/lib/nls/msg/%l/%N.cat is used.
    ``%l'' is replaced by the language component defined for $LANG.

    oflag is reserved for future use and should be set to 0 (zero).  The
    results of setting this field to any other value are undefined.

    Archives:

    If the special syntax for name:

           <programname>@<archivename>

    is used, then only archives are opened by catopen.  The environment vari-
    able NLSPATH is used with the archivename part of name substituted for %A
    (see environ(M)).  Only parts of the path containing a %A are recognized.
    When the archive is opened successfully, the entry named programname is
    used as message catalog.

    catclose closes the message catalog identified by the catd catalog
    descriptor.

    The catopen routine fails if one of the following is true:

    [ENOMEM]    Insufficient storage space is available.

    IEIBNV     The LANG variable is not defined or contains incorrect data.

    IENOOP     No message file was found according to NLSPATH.

    IENMEM     Out of memory.

    The catclose routine fails if the following is true:


    IEBADC     The message file could not be found or the message catalog
                file descriptor has already been closed.


 Return value

    If successful, catopen returns a message catalog descriptor for use on
    subsequent calls to catgets and catclose.  If unsuccessful, catopen
    returns (nlcatd)-1.

    catclose returns 0 if successful; otherwise it returns -1.

 Notes

    Using catopen may cause another file descriptor to be allocated by the
    calling process, in addition to stdin, stdout and stderr.  Applications
    should take care not to close this file descriptor by mistake.

 See also

    catgets(S), environ(M)

 Standards conformance

    catopen and catclose are conformant with:
    X/Open Portability Guide, Issue 3, 1989.