new: newlocale.3

[walter harms <wharms-fPG8STNUNVg@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 218 bytes --]

note: This is a resend, the first version vanished somewhere.

hi list,
i noticed that some locale(7) functions missing am propper man page.
that page describes the functions:
newlocale, duplocale, freelocale

re,
 wh

[-- Attachment #2: newlocale.3 --]
[-- Type: text/plain, Size: 4302 bytes --]

.\" Copyright (C) 2013 Walter Harms (david@prism.demon.co.uk)
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" References consulted:
.\"     Linux libc source code
.\" POSIX-Page http://pubs.opengroup.org/onlinepubs/9699919799/functions/newlocale.html
.\"

.TH NEWLOCALE  3 2013-09-19 "" "Linux Programmer's Manual"
.SH NAME
newlocale, duplocale, freelocale \- modify, create and free a locale object

.SH SYNOPSIS
.nf
.B #include <locale.h>
.sp
.BI "locale_t newlocale(int " mask ", const char * " locale ", locale_t " base );
.sp
.BI "locale_t duplocale(locale_t " loc );
.sp
.BI "void freelocale(locale_t " loc ); 
.fi

.SH DESCRIPTION
These function allow a more fine grained handling of several functions. An already
specified global locale environment is not modified.

.SS newlocale
The first argument 
.I mask 
will select what part of the locale objecte i will create.
The functions correspondens to the category element of the
.BR setlocale (3)
function. Any combination of the following values is possible:
.TP 
.BR LC_ALL_MASK            
for all of the locale
.TP 
.B LC_CTYPE_MASK  
for regular expression matching, character classification,  con-
version,  case-sensitive  comparison,  and  wide character func-
tions.
.TP 
.B LC_NUMERIC_MASK
for number formatting (such as the decimal point and  the  thousands separator).
.TP 
.B LC_TIME_MASK
for time and date formatting
.TP 
.B LC_COLLATE_MASK
for regular expression matching (it determines  the  meaning  of
range expressions and equivalence classes) and string collation.
.TP 
.B LC_MONETARY_MASK 
for monetary formatting      
.TP 
.B LC_MESSAGES_MASK
for localizable natural-language messages
.br
.p
These are GNU-Extensions:
.TP 
.B LC_PAPER_MASK
to specify the paper format
.TP 
.B LC_NAME_MASK
to specify the name format
.TP 
.B LC_ADDRESS_MASK
for specification of adressformat     
.TP 
.B LC_TELEPHONE_MASK
for telephone numbers  
.TP 
.B LC_MEASUREMENT_MASK    
for measurement unit (metric or not)
.TP 
.B LC_IDENTIFICATION_MASK 
for metadata 

.P
The seconde argument 
.I locale
define the set of predefined value.
.TP 
.BR POSIX " or " C
Specifies the minimal environment for C-language translation called the POSIX locale
.TP 
.B \(dq\(dq 
Use the native environment

.P
The third arument
.I base
dictates the behavier of the function.
If this argument is NULL a new locale will be created.
Otherwise the specified locale will be modified.
.sp
.SS duplocale
The function
.I duplocale ()
is used to duplicate the specified locale. To get a copy of the current locale
specify LC_GLOBAL_LOCALE.
.sp
.SS freelocale
After use the user must free the allocated memory by using 
.BR freelocale().
.SH "Return Value"
The newlocale() and duplocale() function shall return 0 on error and set 
.B errno 
to indicate the error.
.SH EXAMPLE
The example will use the "C" locale to determinate the locale specific error 13.
.sp
.nf
#include <stdio.h>
#include <string.h>
#include <locale.h>

int main()
{
  locale_t loc,loc2; 
  loc = newlocale (LC_ALL_MASK, "C", NULL);
  puts(strerror_l(13,loc));
  loc2=duplocale(loc);
  puts(strerror_l(13,loc2));
  freelocale (loc);
  freelocale (loc2);
  return 0; 
}
.nf
.SH "SEE ALSO"
.BR setlocale (3),
.BR xlocale (5),
.BR uselocale (3)