1502 Remove conversion cruft from manpages

[unleashed.git] / usr / src / man / man3c / gettext.3c

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GETTEXT 3C "Jun 4, 2008"
.SH NAME
gettext, dgettext, dcgettext, ngettext, dngettext, dcngettext, textdomain,
bindtextdomain, bind_textdomain_codeset \- message handling functions
.SH SYNOPSIS
.SS "Solaris and GNU-compatible"
.LP
.nf
#include <libintl.h>

\fBchar *\fR\fBgettext\fR(\fBconst char *\fR\fImsgid\fR);
.fi

.LP
.nf
\fBchar *\fR\fBdgettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid\fR);
.fi

.LP
.nf
\fBchar *\fR\fBtextdomain\fR(\fBconst char *\fR\fIdomainname\fR);
.fi

.LP
.nf
\fBchar *\fR\fBbindtextdomain\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fIdirname\fR);
.fi

.LP
.nf
#include <libintl.h>
#include <locale.h>

\fBchar *\fR\fBdcgettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid\fR,
     \fBint\fR \fIcategory\fR);
.fi

.SS "GNU-compatible"
.LP
.nf
#include <libintl.h>

\fBchar *\fR\fBngettext\fR(\fBconst char *\fR\fImsgid1\fR, \fBconst char *\fR\fImsgid2\fR,
     \fBunsigned long int\fR \fIn\fR);
.fi

.LP
.nf
\fBchar *\fR\fBdngettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid1\fR,
     \fBconst char *\fR\fImsgid2\fR, \fBunsigned long int\fR \fIn\fR);
.fi

.LP
.nf
\fBchar *\fR\fBbind_textdomain_codeset\fR(\fBconst char *\fR\fIdomainname\fR,
     \fBconst char *\fR\fIcodeset\fR);
.fi

.LP
.nf
extern int _nl_msg_cat_cntr;
extern int *_nl_domain_bindings;
.fi

.LP
.nf
#include <libintl.h>
#include <locale.h>

\fBchar *\fR\fBdcngettext\fR(\fBconst char *\fR\fIdomainname\fR, \fBconst char *\fR\fImsgid1\fR,
     \fBconst char *\fR\fImsgid2\fR, \fBunsigned long int\fR \fIn\fR, \fBint\fR \fIcategory\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR functions attempt
to retrieve a target string based on the specified \fImsgid\fR argument within
the context of a specific domain and the current locale. The length of strings
returned by \fBgettext()\fR,  \fBdgettext()\fR, and \fBdcgettext()\fR is
undetermined until the function is called. The \fImsgid\fR argument is a
null-terminated string.
.sp
.LP
The \fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR functions are
equivalent to \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR,
respectively, except for the handling of plural forms.  These functions work
only with GNU-compatible message catalogues.  The \fBngettext()\fR,
\fBdngettext()\fR, and \fBdcngettext()\fR functions search for the message
string using the \fImsgid1\fR argument as the key and the \fIn\fR argument to
determine the plural form.  If no message catalogues are found, \fImsgid1\fR is
returned if \fIn\fR == 1, otherwise \fImsgid2\fR is returned.
.sp
.LP
The \fBNLSPATH\fR environment variable (see \fBenviron\fR(5)) is searched first
for the location of the  \fBLC_MESSAGES\fR catalogue. The setting of the
\fBLC_MESSAGES\fR category of the current locale determines the locale used by
\fBgettext()\fR and \fBdgettext()\fR for string retrieval. The \fIcategory\fR
argument determines the locale used by \fBdcgettext(\|).\fR If \fBNLSPATH\fR is
not defined and the current locale is "C", \fBgettext()\fR, \fBdgettext()\fR,
and \fBdcgettext()\fR simply return the message string that was passed.  In a
locale  other than "C", if \fBNLSPATH\fR is not defined or if a message
catalogue is not found in any of the components specified by \fBNLSPATH\fR, the
routines search for the message catalogue using the scheme described in the
following paragraph.
.sp
.LP
The \fBLANGUAGE\fR environment variable is examined to determine the
GNU-compatible message catalogues to be used. The value of \fBLANGUAGE\fR is a
list of locale names separated by a colon (':') character.  If \fBLANGUAGE\fR
is defined, each locale name is tried in the specified order and if a
GNU-compatible message catalogue is found, the message is returned.  If a
GNU-compatible message catalogue is found but failed to find a corresponding
\fImsgid\fR, the \fImsgid\fR string is return. If \fBLANGUAGE\fR is not defined
or if a Solaris message catalogue is found or no GNU-compatible message
catalogue is found in processing \fBLANGUAGE\fR, the pathname used to locate
the message catalogue is
\fIdirname\fR/\fIlocale\fR/\fIcategory\fR/\fIdomainname\fR.mo, where
\fIdirname\fR is the directory specified by \fBbindtextdomain()\fR,
\fIlocale\fR is a locale name, and \fIcategory\fR is either \fBLC_MESSAGES\fR
if \fBgettext()\fR, \fBdgettext()\fR, \fBngettext()\fR, or \fBdngettext()\fR is
called, or \fBLC_XXX\fR where the name is the same as the locale category name
specified by the \fIcategory\fR argument to \fBdcgettext()\fR or
\fBdcngettext()\fR.
.sp
.LP
For \fBgettext()\fR and \fBngettext()\fR, the domain used is set by the last
valid call to \fBtextdomain()\fR. If a valid call to \fBtextdomain()\fR has not
been made, the default domain  (called \fBmessages\fR) is used.
.sp
.LP
For \fBdgettext()\fR, \fBdcgettext()\fR, \fBdngettext()\fR, and
\fBdcngettext()\fR, the domain used is specified by the \fIdomainname\fR
argument. The \fIdomainname\fR argument is equivalent in syntax and meaning to
the \fIdomainname\fR argument to \fBtextdomain()\fR, except that the selection
of the domain is valid only for the duration of the \fBdgettext()\fR,
\fBdcgettext()\fR, \fBdngettext()\fR, or \fBdcngettext()\fR function call.
.sp
.LP
The \fBtextdomain()\fR function sets or queries the name of the current domain
of the active  \fBLC_MESSAGES\fR locale category. The \fIdomainname\fR argument
is a null-terminated string that can contain only the characters allowed in
legal filenames.
.sp
.LP
The \fIdomainname\fR 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  \fBbindtextdomain()\fR. If
\fBtextdomain()\fR is not called, a default domain is selected. The setting of
domain made by the last valid call to \fBtextdomain()\fR remains valid across
subsequent calls to  \fBsetlocale\fR(3C), and \fBgettext()\fR.
.sp
.LP
The  \fIdomainname\fR argument is applied to the currently active
\fBLC_MESSAGES\fR locale.
.sp
.LP
The current setting of the domain can be queried without affecting the current
state of the domain by calling \fBtextdomain()\fR with \fIdomainname\fR set to
the null pointer. Calling \fBtextdomain()\fR with a  \fIdomainname\fR argument
of a null string sets the domain to the default domain (\fBmessages\fR).
.sp
.LP
The \fBbindtextdomain()\fR function binds the path predicate for a message
domain \fIdomainname\fR to the value contained in \fIdirname\fR. If
\fIdomainname\fR is a non-empty string and has not been bound previously,
\fBbindtextdomain()\fR binds  \fIdomainname\fR with  \fIdirname\fR.
.sp
.LP
If  \fIdomainname\fR is a non-empty string and has been bound previously,
\fBbindtextdomain()\fR replaces the old binding with  \fIdirname\fR. The
\fIdirname\fR argument can be an absolute or relative pathname being resolved
when  \fBgettext()\fR, \fBdgettext()\fR, or \fBdcgettext()\fR are called. If
\fIdomainname\fR is a null pointer or an empty string,  \fBbindtextdomain()\fR
returns \fINULL.\fR User defined domain names cannot begin with the string
\fBSYS_\fR. Domain names beginning with this string are reserved for system
use.
.sp
.LP
The \fBbind_textdomain_codeset()\fR function can be used to specify the output
codeset for message catalogues for domain \fIdomainname\fR.  The \fIcodeset\fR
argument must be a valid codeset name that can be used for the
\fBiconv_open\fR(3C) function, or a null pointer. If the \fIcodeset\fR argument
is the null pointer, \fBbind_textdomain_codeset()\fR returns the currently
selected codeset for the domain with the name \fIdomainname\fR.  It returns a
null pointer if a codeset has not yet been selected. The
\fBbind_textdomain_codeset()\fR function can be used multiple times.  If used
multiple times with the same \fIdomainname\fR argument, the later call
overrides the settings made by the earlier one. The
\fBbind_textdomain_codeset()\fR 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.
.sp
.LP
The external variables \fB_nl_msg_cat_cntr\fR and \fB_nl_domain_bindings\fR are
provided for the compatibility with the GNU \fBgettext()\fR implementation.
.SH RETURN VALUES
.sp
.LP
The \fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR functions return
the message string if the search succeeds. Otherwise they return the
\fImsgid\fR string.
.sp
.LP
The \fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR functions
return the message string if the search succeeds.  If the search fails,
\fImsgid1\fR is returned if \fIn\fR == 1. Otherwise \fImsgid2\fR is returned.
.sp
.LP
The individual bytes of the string returned by \fBgettext()\fR,
\fBdgettext()\fR, \fBdcgettext()\fR, \fBngettext()\fR, \fBdngettext()\fR, or
\fBdcngettext()\fR can contain any value other than \fINULL\fR. If \fImsgid\fR
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
\fBbind_textdomain_codeset()\fR or \fBsetlocale\fR(3C). If the
\fIdomainname\fR argument to  \fBdgettext()\fR,\fBdcgettext()\fR,
\fBdngettext()\fR, or \fBdcngettext()\fR is a null pointer, the the domain
currently bound by \fBtextdomain()\fR is used.
.sp
.LP
The normal return value from \fBtextdomain()\fR is a pointer to a string
containing the current setting of the domain. If \fIdomainname\fR is a null
pointer, \fBtextdomain()\fR returns a pointer to the string containing the
current domain. If \fBtextdomain()\fR was not previously called and
\fIdomainname\fR is a null string, the name of the default domain is returned.
The name of the default domain is \fBmessages\fR. If \fBtextdomain()\fR fails,
a null pointer is returned.
.sp
.LP
The return value from \fBbindtextdomain()\fR is a null-terminated string
containing \fIdirname\fR or the directory binding associated with
\fIdomainname\fR if \fIdirname\fR is \fINULL.\fR If no binding is found, the
default return value is  \fB/usr/lib/locale\fR. If  \fIdomainname\fR is a null
pointer or an empty string, \fBbindtextdomain()\fR takes no action and returns
a null pointer. The string returned must not be modified by the caller. If
\fBbindtextdomain()\fR fails, a null pointer is returned.
.SH USAGE
.sp
.LP
These functions impose no limit on message length. However, a text
\fIdomainname\fR is limited to \fBTEXTDOMAINMAX\fR (256) bytes.
.sp
.LP
The \fBgettext()\fR, \fBdgettext()\fR, \fBdcgettext()\fR, \fBngettext()\fR,
\fBdngettext()\fR, \fBdcngettext()\fR, \fBtextdomain()\fR, and
\fBbindtextdomain()\fR functions can be used safely in multithreaded
applications, as long as \fBsetlocale\fR(3C) is not being called to change the
locale.
.sp
.LP
The \fBgettext()\fR, \fBdgettext()\fR, \fBdcgettext()\fR, \fBtextdomain()\fR,
and \fBbindtextdomain()\fR functions work with both Solaris message catalogues
and GNU-compatible message catalogues.  The \fBngettext()\fR,
\fBdngettext()\fR, \fBdcngettext()\fR, and \fBbind_textdomain_codeset()\fR
functions work only with GNU-compatible message catalogues.  See
\fBmsgfmt\fR(1) for information about Solaris message catalogues and
GNU-compatible message catalogues.
.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/locale\fR\fR
.ad
.sp .6
.RS 4n
default path predicate for message domain files
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_MESSAGES/\fR\fIdomainname\fR\fB\&.m
o\fR\fR
.ad
.sp .6
.RS 4n
system default location for file containing messages for  language
\fIlocale\fR and \fIdomainname\fR
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/locale/\fR\fIlocale\fR\fB/LC_XXX/\fR\fIdomainname\fR\fB\&.mo\fR\
fR
.ad
.sp .6
.RS 4n
system default location for file containing messages for  language
\fIlocale\fR and \fIdomainname\fR for \fBdcgettext()\fR calls where
\fBLC_XXX\fR is  \fBLC_CTYPE\fR, \fBLC_NUMERIC\fR, \fBLC_TIME\fR,
\fBLC_COLLATE\fR, \fBLC_MONETARY\fR, or \fBLC_MESSAGES\fR
.RE

.sp
.ne 2
.na
\fB\fB\fR\fIdirname\fR\fB/\fR\fIlocale\fR\fB/LC_MESSAGES/\fR\fIdomainname\fR\fB
\&.mo\fR\fR
.ad
.sp .6
.RS 4n
location for file containing messages for domain \fIdomainname\fR and path
predicate \fIdirname\fR after a successful call to \fBbindtextdomain()\fR
.RE

.sp
.ne 2
.na
\fB\fB\fR\fIdirname\fR\fB/\fR\fIlocale\fR\fB/LC_XXX/\fR\fIdomainname\fR\fB\&.mo
\fR\fR
.ad
.sp .6
.RS 4n
location for files containing messages for domain \fIdomainname,\fR language
\fIlocale,\fR and path predicate \fIdirname\fR after a successful call to
\fBbindtextdomain()\fR for \fBdcgettext()\fR calls where \fBLC_XXX\fR is one of
\fBLC_CTYPE\fR, \fBLC_NUMERIC\fR, \fBLC_TIME\fR, \fBLC_COLLATE\fR,
\fBLC_MONETARY\fR, or \fBLC_MESSAGES\fR
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     See below.
_
MT-Level        Safe with exceptions
.TE

.sp
.LP
The external variables \fB_nl_msg_cat_cntr\fR and \fB_nl_domain_bindings\fR are
Uncommitted.
.SH SEE ALSO
.sp
.LP
\fBmsgfmt\fR(1), \fBxgettext\fR(1), \fBiconv_open\fR(3C),
\fBlibintl.h\fR(3HEAD), \fBsetlocale\fR(3C), \fBattributes\fR(5),
\fBenviron\fR(5)