mirror of https://github.com/mkerrisk/man-pages
132 lines
4.8 KiB
Plaintext
132 lines
4.8 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "CATOPEN" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" catopen
|
|
.SH NAME
|
|
catopen \- open a message catalog
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <nl_types.h>
|
|
.br
|
|
.sp
|
|
nl_catd catopen(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB);
|
|
\fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIcatopen\fP() function shall open a message catalog and return
|
|
a message catalog descriptor. The \fIname\fP argument
|
|
specifies the name of the message catalog to be opened. If \fIname\fP
|
|
contains a \fB'/'\fP , then \fIname\fP specifies a
|
|
complete name for the message catalog. Otherwise, the environment
|
|
variable \fINLSPATH\fP is used with \fIname\fP substituted for
|
|
the \fB%N\fP conversion specification (see the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables). If \fINLSPATH\fP
|
|
exists in the environment when the process
|
|
starts, then if the process has appropriate privileges, the behavior
|
|
of \fIcatopen\fP() is undefined. If \fINLSPATH\fP does not
|
|
exist in the environment, or if a message catalog cannot be found
|
|
in any of the components specified by \fINLSPATH\fP, then an
|
|
implementation-defined default path shall be used. This default may
|
|
be affected by the setting of \fILC_MESSAGES\fP if the value
|
|
of \fIoflag\fP is NL_CAT_LOCALE, or the \fILANG\fP environment variable
|
|
if \fIoflag\fP is 0.
|
|
.LP
|
|
A message catalog descriptor shall remain valid in a process until
|
|
that process closes it, or a successful call to one of the
|
|
\fIexec\fP functions. A change in the setting of the \fILC_MESSAGES\fP
|
|
category may
|
|
invalidate existing open catalogs.
|
|
.LP
|
|
If a file descriptor is used to implement message catalog descriptors,
|
|
the FD_CLOEXEC flag shall be set; see \fI<fcntl.h>\fP.
|
|
.LP
|
|
If the value of the \fIoflag\fP argument is 0, the \fILANG\fP environment
|
|
variable is used to locate the catalog without
|
|
regard to the \fILC_MESSAGES\fP category. If the \fIoflag\fP argument
|
|
is NL_CAT_LOCALE, the \fILC_MESSAGES\fP category is used
|
|
to locate the message catalog (see the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables).
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIcatopen\fP() shall return a message
|
|
catalog descriptor for use on subsequent calls to \fIcatgets\fP()
|
|
and \fIcatclose\fP(). Otherwise,
|
|
\fIcatopen\fP() shall return ( \fBnl_catd\fP) -1 and set \fIerrno\fP
|
|
to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIcatopen\fP() function may fail if:
|
|
.TP 7
|
|
.B EACCES
|
|
Search permission is denied for the component of the path prefix of
|
|
the message catalog or read permission is denied for the
|
|
message catalog.
|
|
.TP 7
|
|
.B EMFILE
|
|
{OPEN_MAX} file descriptors are currently open in the calling process.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
The length of a pathname of the message catalog exceeds {PATH_MAX}
|
|
or a pathname component is longer than {NAME_MAX}.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
Pathname resolution of a symbolic link produced an intermediate result
|
|
whose length exceeds {PATH_MAX}.
|
|
.TP 7
|
|
.B ENFILE
|
|
Too many files are currently open in the system.
|
|
.TP 7
|
|
.B ENOENT
|
|
The message catalog does not exist or the \fIname\fP argument points
|
|
to an empty string.
|
|
.TP 7
|
|
.B ENOMEM
|
|
Insufficient storage space is available.
|
|
.TP 7
|
|
.B ENOTDIR
|
|
A component of the path prefix of the message catalog is not a directory.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
Some implementations of \fIcatopen\fP() use \fImalloc\fP() to allocate
|
|
space for
|
|
internal buffer areas. The \fIcatopen\fP() function may fail if there
|
|
is insufficient storage space available to accommodate these
|
|
buffers.
|
|
.LP
|
|
Conforming applications must assume that message catalog descriptors
|
|
are not valid after a call to one of the \fIexec\fP functions.
|
|
.LP
|
|
Application writers should be aware that guidelines for the location
|
|
of message catalogs have not yet been developed. Therefore
|
|
they should take care to avoid conflicting with catalogs used by other
|
|
applications and the standard utilities.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIcatclose\fP() , \fIcatgets\fP() , the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<fcntl.h>\fP, \fI<nl_types.h>\fP, the Shell
|
|
and Utilities volume of IEEE\ Std\ 1003.1-2001
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|