catopen(3C)															       catopen(3C)

NAME

       catopen(), catclose() - open and close a message catalog for reading

SYNOPSIS

DESCRIPTION

       The function opens a message catalog and returns a catalog descriptor.  The specifies the name of the message catalog being opened.  A con-
       taining a slash specifies a path name for the message catalog.  Otherwise, the environment variable is used (see environ(5)).  If specifies
       more  than one path, returns the catalog descriptor for the first path on which it is able to successfully open the specified message cata-
       log.  If does not exist in the environment, or if a message catalog cannot be opened for any path, uses a system-wide  default  path.   The
       default	is  affected by if the value of is If the value of is zero, the default is affected by the environment variable See environ(5) for
       details.

       If is invoked from or programs with owner root, the environment variable is not directly used to locate	message  catalogs.   Instead,  the
       paths  which  are  available  both  in  the  configuration  file  and  environment variable are considered to locate message catalogs.  See
       nlspath(4) for details.

       Example: If the environment variable is set to:

       and the configuration file has an entry:

       only path is considered for locating catalog files.  This feature is provided only for backward compatibility for those	or  root  programs
       which  are  depending  on the environment variable.  All new or root programs should not depend on the environment variable and should only
       use absolute path names.

       A message catalog descriptor remains valid in a process until the process closes it or until a successful call to one of the functions.	 A
       change in the setting of the category may invalidate existing open catalogs.

       A  file descriptor is used to implement the message catalog descriptor and the close-on-exec flag is set for the message catalog descriptor
       (see fcntl(2)).

       If is zero, the environment variable is used to locate the catalog.  If is the category is used to locate the message  catalog  only  if  a
       successful call to has been made prior to the call to The result of setting to any other value is undefined.

       The function closes the message catalog a message catalog descriptor returned from an earlier successful call to

RETURN VALUE

       Upon success, returns a message catalog descriptor.  Otherwise, returns a value of (nl_catd)-1 and sets to indicate the error.

       Upon success, returns zero.  Otherwise, returns -1 and sets to indicate the error.

ERRORS

       fails without opening a message catalog and sets for the last path attempted under any of the following conditions:

	      A component of the path prefix denies search permission, or
				     read permission is denied for the named file.

	      The maximum number of file descriptors allowed are currently open.

	      The length of the specified path name exceeds
				     bytes, or the length of a component of the path name exceeds bytes while is in effect.

	      The system file table is full.

	      The named catalog does not exist or the path is null.

	      A component of the path prefix is not a directory.

       can be used to provide default messages when called following a failed (see catgets(3C)).  returns its parameter if it is passed an invalid
       catalog descriptor.

       fails if the following is true:

	      is not a valid open message catalog descriptor.

WARNINGS

       When using does not provide a default value for

AUTHOR

       and were developed by HP.

FILES

       Include file containing native language types.

       Message catalog default path for core HP-UX products only.

SEE ALSO

       fcntl(2), catgets(3C), setlocale(3C), nlspath(4), environ(5), thread_safety(5).

STANDARDS CONFORMANCE

																       catopen(3C)