'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH g3c.setlocale @(#)setlocale	40.16 of 11/16/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} setlocale 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} setlocale 3C "C Programming Language Utilities"
.if \nX=2 .ds x} setlocale 3C "" "\&"
.if \nX=3 .ds x} setlocale "" "" "\&"
.TH \*(x}
.SH NAME
\f4setlocale\f1 \- modify and query a program's locale
.SH SYNOPSIS
\f4#include <locale.h>\f1
.PP
\f4char \(**setlocale (int category, const char \(**locale);\f1
.SH DESCRIPTION
\f4setlocale\fP selects the appropriate piece of the program's
locale as specified by the \f2category\f1 and \f2locale\f1 arguments.
The \f2category\f1 argument may have the following values: 
\f4LC_CTYPE,\fP
\f4LC_NUMERIC,\fP
\f4LC_TIME,\fP
\f4LC_COLLATE,\fP
\f4LC_MONETARY,\fP
\f4LC_MESSAGES\fP
and \f4LC_ALL.\f1
These names are defined in the \f4locale.h\fP header file.
\f4LC_CTYPE\fP affects the behavior of the character handling functions (\f4isdigit\fP,
\f4tolower\f1, etc.) and the multibyte character functions (such as \f4mbtowc\fP and
\f4wctomb\fP).
\f4LC_NUMERIC\fP affects
the decimal-point character
for the formatted input/output functions and
the string conversion functions
as well as the non-monetary formatting information returned
by \f4localeconv\f1.
[See \f4localeconv\f1(3C).].
\f4LC_TIME\fP affects the behavior of 
\f4ascftime\fP, \f4cftime\fP, \f4getdate\f1 and \f4strftime\fP.
\f4LC_COLLATE\fP affects the behavior of \f4strcoll\fP and \f4strxfrm\fP.
\f4LC_MONETARY\fP affects the monetary formatted information returned by
\f4localeconv\fP.
\f4LC_MESSAGES\fP affects the behavior of \f4gettxt\fP,
\f4catopen\fP,
\f4catclose\fP,
and
\f4catgets\fP.
[See \f4catopen\f1(3C) and \f4catgets\f1(3C).]
\f4LC_ALL\fP names the program's entire locale.
.PP
Each category corresponds to a set of databases which contain the 
relevant information for each defined locale.
The location of a database is given by the following path,
\f4/usr/lib/locale/\f2locale\f1/\f2category\f1, where \f2locale\f1 and
\f2category\f1 are the names of locale and category, respectively.
For example, the
database for the \f4LC_CTYPE\fP category for the "german" locale would be found
in \f4/usr/lib/locale/german/LC_CTYPE\f1.
.PP
A value of "C" for \f2locale\f1 specifies the default environment.
.PP
A value of "" for \f2locale\f1 specifies that the locale should be taken
from environment variables.
The order in which the environment variables
are checked for the various categories is given below:
.RS 1i
.TS
l l l
lf4 lf4 lf4.
Category	1st Env. Var.	2nd Env. Var
_
LC_CTYPE:	LC_CTYPE	LANG
LC_COLLATE:	LC_COLLATE	LANG
LC_TIME:	LC_TIME	LANG
LC_NUMERIC:	LC_NUMERIC	LANG
LC_MONETARY:	LC_MONETARY	LANG
LC_MESSAGES:	LC_MESSAGES	LANG
.TE
.RE
.PP
At program startup, the equivalent of
.PP
.RS
\f4setlocale(LC_ALL, "C")\f1
.ft
.RE
.PP
is executed.
This has the effect of initializing each category to the
locale described by the environment "C".
.PP
If a pointer to a
string is given for \f2locale\f1,
\f4setlocale\fP attempts
to set the locale for the given category to
\f2locale\f1.
If \f4setlocale\fP succeeds, \f2locale\f1 is returned.
If \f4setlocale\fP fails, a null pointer is returned and the program's locale
is not changed.
.PP
For category \f4LC_ALL\f1, the behavior is slightly different.
If a pointer to a
string is given for \f2locale\f1
and \f4LC_ALL\f1 is given for
\f2category\f1, \f4setlocale\f1
attempts to set
the locale for all the categories to
\f2locale\f1.
The \f2locale\f1 may
be a simple
locale, consisting of a single locale, or a
composite locale.
A composite locale is a string beginning with a "/"
followed by the locale 
of each category separated by a "/".
If \%\f4setlocale\f1 fails to set the locale for any category,
a null pointer is returnedand the program's locale
for all categories is not changed.
Otherwise, locale is returned.
.PP
A null pointer for \f2locale\f1 causes \f4setlocale\fP to return the current locale
associated with the \f2category\f1.
The program's locale is not changed.
.SH FILES
\f4/usr/lib/locale/C/LC_CTYPE\fP \- \f4LC_CTYPE\fP database for the C locale.
.br
\f4/usr/lib/locale/C/LC_NUMERIC\fP \- \f4LC_NUMERIC\fP database for the C locale.
.br
\f4/usr/lib/locale/C/LC_TIME\fP \- \f4LC_TIME\fP database for the C locale.
.br
\f4/usr/lib/locale/C/LC_COLLATE\fP \- \f4LC_COLLATE\fP database for the C locale.
.br
\f4/usr/lib/locale/C/LC_MESSAGES\fP \- \f4LC_MESSAGES\fP database for 
the C locale.
.br
\f4/usr/lib/locale/\f2locale\f1/\f2category\f1 \- files containing the locale specific 
information for each locale and category.
.SH "SEE ALSO"
\f4ctime\fP(3C), \f4ctype\fP(3C), \f4getdate\fP(3C), \f4gettxt\fP(3G), \f4localeconv\fP(3C), 
\f4mbtowc\fP(3C), \f4printf\fP(3S), \f4strcoll\fP(3C), \f4strftime\fP(3C), \f4strtod\fP(3C), \f4strxfrm\fP(3C),
\f4wctomb\fP(3C),
\f4environ\fP(5).
.\"	@(#)setlocale.3c	
.Ee
