jpayne@68: .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
jpayne@68: .\"
jpayne@68: .\" This is free documentation; you can redistribute it and/or
jpayne@68: .\" modify it under the terms of the GNU General Public License as
jpayne@68: .\" published by the Free Software Foundation; either version 2 of
jpayne@68: .\" the License, or (at your option) any later version.
jpayne@68: .\"
jpayne@68: .\" References consulted:
jpayne@68: .\"   GNU glibc-2 source code and manual
jpayne@68: .\"   GNU gettext source code and manual
jpayne@68: .\"   LI18NUX 2000 Globalization Specification
jpayne@68: .\"
jpayne@68: .TH NGETTEXT 3 "May 2001" "GNU gettext 0.22.5"
jpayne@68: .SH NAME
jpayne@68: ngettext, dngettext, dcngettext \- translate message and choose plural form
jpayne@68: .SH SYNOPSIS
jpayne@68: .nf
jpayne@68: .B #include <libintl.h>
jpayne@68: .sp
jpayne@68: .BI "char * ngettext (const char * " msgid ", const char * " msgid_plural ,
jpayne@68: .BI "                 unsigned long int " n );
jpayne@68: .BI "char * dngettext (const char * " domainname ,
jpayne@68: .BI "                  const char * " msgid ", const char * " msgid_plural ,
jpayne@68: .BI "                  unsigned long int " n );
jpayne@68: .BI "char * dcngettext (const char * " domainname ,
jpayne@68: .BI "                   const char * " msgid ", const char * " msgid_plural ,
jpayne@68: .BI "                   unsigned long int " n ", int " category );
jpayne@68: .fi
jpayne@68: .SH DESCRIPTION
jpayne@68: The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions attempt to
jpayne@68: translate a text string into the user's native language, by looking up the
jpayne@68: appropriate plural form of the translation in a message catalog.
jpayne@68: .PP
jpayne@68: Plural forms are grammatical variants depending on the a number. Some languages
jpayne@68: have two forms, called singular and plural. Other languages have three forms,
jpayne@68: called singular, dual and plural. There are also languages with four forms.
jpayne@68: .PP
jpayne@68: The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions work like
jpayne@68: the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions, respectively.
jpayne@68: Additionally, they choose the appropriate plural form, which depends on the
jpayne@68: number \fIn\fP and the language of the message catalog where the translation
jpayne@68: was found.
jpayne@68: .PP
jpayne@68: In the "C" locale, or if none of the used catalogs contain a translation for
jpayne@68: \fImsgid\fP, the \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions
jpayne@68: return \fImsgid\fP if \fIn\fP == 1, or \fImsgid_plural\fP if \fIn\fP != 1.
jpayne@68: .SH "RETURN VALUE"
jpayne@68: If a translation was found in one of the specified catalogs, the appropriate
jpayne@68: plural form is converted to the locale's codeset and returned. The resulting
jpayne@68: string is statically allocated and must not be modified or freed. Otherwise
jpayne@68: \fImsgid\fP or \fImsgid_plural\fP is returned, as described above.
jpayne@68: .SH ERRORS
jpayne@68: \fBerrno\fP is not modified.
jpayne@68: .SH BUGS
jpayne@68: The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid
jpayne@68: warnings in C code predating ANSI C.
jpayne@68: .SH "SEE ALSO"
jpayne@68: .BR gettext (3),
jpayne@68: .BR dgettext (3),
jpayne@68: .BR dcgettext (3)