diff options
Diffstat (limited to 'man/man3/nl_langinfo.3')
| -rw-r--r-- | man/man3/nl_langinfo.3 | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/man/man3/nl_langinfo.3 b/man/man3/nl_langinfo.3 new file mode 100644 index 000000000..24cdfe88e --- /dev/null +++ b/man/man3/nl_langinfo.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 2001 Markus Kuhn <mkuhn@acm.org> +.\" and Copyright (c) 2015 Sam Varshavchik <mrsam@courier-mta.com> +.\" and Copyright (c) 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 manual +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Corrected prototype, 2002-10-18, aeb +.\" +.TH nl_langinfo 3 (date) "Linux man-pages (unreleased)" +.SH NAME +nl_langinfo, nl_langinfo_l \- query language and locale information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <langinfo.h> +.P +.BI "char *nl_langinfo(nl_item " item ); +.BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nl_langinfo_l (): +.nf + Since glibc 2.24: + _POSIX_C_SOURCE >= 200809L + glibc 2.23 and earlier: + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR nl_langinfo () +and +.BR nl_langinfo_l () +functions provide access to locale information +in a more flexible way than +.BR localeconv (3). +.BR nl_langinfo () +returns a string which is the value corresponding to +\fIitem\fP in the program's current global +locale. +.BR nl_langinfo_l () +returns a string which is the value corresponding to \fIitem\fP +for the locale identified by the locale object \fIlocale\fP, +which was previously created by +.BR newlocale (3). +Individual and additional elements of the locale categories can +be queried. +.P +Examples for the locale elements that can be specified in \fIitem\fP +using the constants defined in \fI<langinfo.h>\fP are: +.TP +.BR CODESET \ (LC_CTYPE) +Return a string with the name of the character encoding used in the +selected locale, such as "UTF\-8", "ISO\-8859\-1", or "ANSI_X3.4\-1968" +(better known as US-ASCII). +This is the same string that you get with +"locale charmap". +For a list of character encoding names, +try "locale \-m" (see +.BR locale (1)). +.TP +.BR D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent time and date in a locale-specific way +.RB ( %c +conversion specification). +.TP +.BR D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a date in a locale-specific way +.RB ( %x +conversion specification). +.TP +.BR T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a locale-specific way +.RB ( %X +conversion specification). +.TP +.BR AM_STR \ (LC_TIME) +Return a string that represents affix for ante meridiem (before noon, "AM") +time. +(Used in +.B %p +.BR strftime (3) +conversion specification.) +.TP +.BR PM_STR \ (LC_TIME) +Return a string that represents affix for post meridiem (before midnight, "PM") +time. +(Used in +.B %p +.BR strftime (3) +conversion specification.) +.TP +.BR T_FMT_AMPM \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a.m. or p.m. notation in a locale-specific way +.RB ( %r +conversion specification). +.TP +.BR ERA \ (LC_TIME) +Return era description, which contains information about how years are counted +and displayed for each era in a locale. +Each era description segment shall have the format: +.RS +.IP +.IR direction : offset : start_date : end_date : era_name : era_format +.RE +.IP +according to the definitions below: +.RS +.TP 12 +.I direction +Either a +.RB \[dq] + "\[dq] or a \[dq]" - \[dq] +character. +The +.RB \[dq] + \[dq] +means that years increase from the +.I start_date +towards the +.IR end_date , +.RB \[dq] - \[dq] +means the opposite. +.TP +.I offset +The epoch year of the +.IR start_date . +.TP +.I start_date +A date in the form +.IR yyyy / mm / dd , +where +.IR yyyy ", " mm ", and " dd +are the year, month, and day numbers respectively of the start of the era. +.TP +.I end_date +The ending date of the era, in the same format as the +.IR start_date , +or one of the two special values +.RB \[dq] -* \[dq] +(minus infinity) or +.RB \[dq] +* \[dq] +(plus infinity). +.TP +.I era_name +The name of the era, corresponding to the +.B %EC +.BR strftime (3) +conversion specification. +.TP +.I era_format +The format of the year in the era, corresponding to the +.B %EY +.BR strftime (3) +conversion specification. +.RE +.IP +Era description segments are separated by semicolons. +Most locales do not define this value. +Examples of locales that do define this value are the Japanese and Thai +locales. +.TP +.BR ERA_D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of time and date in a locale-specific way +.RB ( %Ec +conversion specification). +.TP +.BR ERA_D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of a date in a locale-specific way +.RB ( %Ex +conversion specification). +.TP +.BR ERA_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of a time in a locale-specific way +.RB ( %EX +conversion specification). +.TP +.BR DAY_ "{1\[en]7} (LC_TIME)" +Return name of the \fIn\fP-th day of the week. +[Warning: this follows +the US convention DAY_1 = Sunday, not the international convention +(ISO\~8601) that Monday is the first day of the week.] +(Used in +.B %A +.BR strftime (3) +conversion specification.) +.TP +.BR ABDAY_ "{1\[en]7} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th day of the week. +(Used in +.B %a +.BR strftime (3) +conversion specification.) +.TP +.BR MON_ "{1\[en]12} (LC_TIME)" +Return name of the \fIn\fP-th month. +(Used in +.B %B +.BR strftime (3) +conversion specification.) +.TP +.BR ABMON_ "{1\[en]12} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th month. +(Used in +.B %b +.BR strftime (3) +conversion specification.) +.TP +.BR RADIXCHAR \ (LC_NUMERIC) +Return radix character (decimal dot, decimal comma, etc.). +.TP +.BR THOUSEP \ (LC_NUMERIC) +Return separator character for thousands (groups of three digits). +.TP +.BR YESEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a positive response to a yes/no question. +.TP +.BR NOEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a negative response to a yes/no question. +.TP +.BR CRNCYSTR \ (LC_MONETARY) +Return the currency symbol, preceded by "\-" if the symbol should +appear before the value, "+" if the symbol should appear after the +value, or "." if the symbol should replace the radix character. +.P +The above list covers just some examples of items that can be requested. +For a more detailed list, consult +.IR "The GNU C Library Reference Manual" . +.SH RETURN VALUE +On success, these functions return a pointer to a string which +is the value corresponding to +.I item +in the specified locale. +.P +If no locale has been selected by +.BR setlocale (3) +for the appropriate category, +.BR nl_langinfo () +return a pointer to the corresponding string in the "C" locale. +The same is true of +.BR nl_langinfo_l () +if +.I locale +specifies a locale where +.I langinfo +data is not defined. +.P +If \fIitem\fP is not valid, a pointer to an empty string is returned. +.P +The pointer returned by these functions may point to static data that +may be overwritten, or the pointer itself may be invalidated, +by a subsequent call to +.BR nl_langinfo (), +.BR nl_langinfo_l (), +or +.BR setlocale (3). +The same statements apply to +.BR nl_langinfo_l () +if the locale object referred to by +.I locale +is freed or modified by +.BR freelocale (3) +or +.BR newlocale (3). +.P +POSIX specifies that the application may not modify +the string returned by these functions. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nl_langinfo () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SUSv2. +.SH NOTES +The behavior of +.BR nl_langinfo_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +or is not a valid locale object handle. +.SH EXAMPLES +The following program sets the character type and the numeric locale +according to the environment and queries the terminal character set and +the radix character. +.P +.\" SRC BEGIN (nl_langinfo.c) +.EX +#include <langinfo.h> +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +\& +int +main(void) +{ + setlocale(LC_CTYPE, ""); + setlocale(LC_NUMERIC, ""); +\& + printf("%s\en", nl_langinfo(CODESET)); + printf("%s\en", nl_langinfo(RADIXCHAR)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR locale (1), +.BR localeconv (3), +.BR setlocale (3), +.BR charsets (7), +.BR locale (7) +.P +The GNU C Library Reference Manual |