Date: Fri, 2 Dec 2011 11:55:10 +0000 (UTC) From: "David E. O'Brien" <obrien@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r228199 - head/lib/libc/locale Message-ID: <201112021155.pB2BtA2W091372@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: obrien Date: Fri Dec 2 11:55:09 2011 New Revision: 228199 URL: http://svn.freebsd.org/changeset/base/228199 Log: Split sentences at period boundaries. Modified: head/lib/libc/locale/duplocale.3 head/lib/libc/locale/freelocale.3 head/lib/libc/locale/localeconv.3 head/lib/libc/locale/newlocale.3 head/lib/libc/locale/querylocale.3 head/lib/libc/locale/uselocale.3 head/lib/libc/locale/xlocale.3 Modified: head/lib/libc/locale/duplocale.3 ============================================================================== --- head/lib/libc/locale/duplocale.3 Fri Dec 2 10:02:49 2011 (r228198) +++ head/lib/libc/locale/duplocale.3 Fri Dec 2 11:55:09 2011 (r228199) @@ -36,25 +36,26 @@ .Sh LIBRARY .Lb libc .Sh SYNOPSIS -.In xlocale.h -.Ft locale_t +.In xlocale.h +.Ft locale_t .Fn duplocale "locale_t locale" .Sh DESCRIPTION Duplicates an existing .Fa locale_t -returning a new +returning a new .Fa locale_t that refers to the same locale values but has independent internal state. Various functions, such as .Xr mblen 3 -require presistent state. These functions formerly used static variables and -calls to them from multiple threads had undefined behavior. They now use -fields in the +require presistent state. +These functions formerly used static variables and calls to them from multiple +threads had undefined behavior. +They now use fields in the .Fa locale_t associated with the current thread by .Xr uselocale 3 . These calls are therefore only thread safe on threads with a unique per-thread -locale. +locale. .Pt The locale returned by this call must be freed with .Xr freelocale 3 . @@ -63,8 +64,9 @@ Ideally, .Xr uselocale 3 should make a copy of the .Fa locale_t -implicitly to ensure thread safety, and a copy of the global locale should be -installed lazily on each thread. The FreeBSD implementation does not do this, +implicitly to ensure thread safety, +and a copy of the global locale should be installed lazily on each thread. +The FreeBSD implementation does not do this, for compatibility with Darwin. .Sh SEE ALSO .Xr freelocale 3 , Modified: head/lib/libc/locale/freelocale.3 ============================================================================== --- head/lib/libc/locale/freelocale.3 Fri Dec 2 10:02:49 2011 (r228198) +++ head/lib/libc/locale/freelocale.3 Fri Dec 2 11:55:09 2011 (r228199) @@ -33,22 +33,22 @@ .Nm freelocale .Nd Frees a locale created with .Xr duplocale 3 -or +or .Xr newlocale 3 . .Sh LIBRARY .Lb libc .Sh SYNOPSIS -.In xlocale.h +.In xlocale.h .Ft int .Fn freelocale "locale_t locale" .Sh DESCRIPTION Frees a .Fa locale_t . -This relinquishes any resources held exclusively by this locale. Note that -locales share reference-counted components, so a call to this function is not -guaranteed to free all of the components. +This relinquishes any resources held exclusively by this locale. +Note that locales share reference-counted components, +so a call to this function is not guaranteed to free all of the components. .Sh RETURN VALUES -Returns 0 on success or -1 on error. +Returns 0 on success or -1 on error. .Sh SEE ALSO .Xr duplocale 3 , .Xr localeconv 3 , Modified: head/lib/libc/locale/localeconv.3 ============================================================================== --- head/lib/libc/locale/localeconv.3 Fri Dec 2 10:02:49 2011 (r228198) +++ head/lib/libc/locale/localeconv.3 Fri Dec 2 11:55:09 2011 (r228199) @@ -203,7 +203,7 @@ result similarly denotes an unavailable The .Fn localeconv_l function takes an explicit locale parameter. For more information, see -.Xr xlocale 3 . +.Xr xlocale 3 . .Sh RETURN VALUES The .Fn localeconv @@ -212,9 +212,10 @@ which may be altered by later calls to .Xr setlocale 3 or .Fn localeconv . -The return value for +The return value for .Fn localeconv_l -is stored with the locale. It will remain valid until a subsequent call to +is stored with the locale. +It will remain valid until a subsequent call to .Xr freelocale 3 . If a thread-local locale is in effect then the return value from .Fn localeconv Modified: head/lib/libc/locale/newlocale.3 ============================================================================== --- head/lib/libc/locale/newlocale.3 Fri Dec 2 10:02:49 2011 (r228198) +++ head/lib/libc/locale/newlocale.3 Fri Dec 2 11:55:09 2011 (r228199) @@ -31,40 +31,44 @@ .Os .Sh NAME .Nm newlocale -.Nd Creates a new locale +.Nd Creates a new locale .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In xlocale -.Ft +.Ft .Fn newlocale "int mask" "const char * locale" "locale_t base" .Sh DESCRIPTION -Creates a new locale, inheriting some properties from an existing locale. The -.Fa mask +Creates a new locale, inheriting some properties from an existing locale. +The +.Fa mask defines the components that the new locale will have set to the locale with the -name specified in the +name specified in the .Fa locale -parameter. Any other components will be inherited from +parameter. +Any other components will be inherited from .Fa base . .Pt The .Fa mask is either .Fa LC_ALL_MASK, -indicating all possible locale components, or the logical OR of some -combination of the following: +indicating all possible locale components, +or the logical OR of some combination of the following: .Bl -tag -width "LC_MESSAGES_MASK" -offset indent .It LC_COLLATE_MASK -The locale for string collation routines. This controls alphabetic ordering in +The locale for string collation routines. +This controls alphabetic ordering in .Xr strcoll 3 - and + and .Xr strxfrm 3 . .It LC_CTYPE_MASK The locale for the .Xr ctype 3 and .Xr multibyte 3 -functions. This controls recognition of upper and lower case, alpha- betic or +functions. +This controls recognition of upper and lower case, alphabetic or non-alphabetic characters, and so on. .It LC_MESSAGES_MASK Set a locale for message catalogs, see @@ -76,8 +80,8 @@ the .Xr localeconv 3 function. .It LC_NUMERIC_MASK -Set a locale for formatting numbers. This controls the for- -matting of decimal points in input and output of floating +Set a locale for formatting numbers. +This controls the formatting of decimal points in input and output of floating point numbers in functions such as .Xr printf 3 and @@ -95,7 +99,8 @@ This function uses the same rules for lo .Sh RETURN VALUES Returns a new, valid, .Fa locale_t -or NULL if an error occurs. You must free the returned locale with +or NULL if an error occurs. +You must free the returned locale with .Xr freelocale 3 . .Sh SEE ALSO .Xr duplocale 3 , Modified: head/lib/libc/locale/querylocale.3 ============================================================================== --- head/lib/libc/locale/querylocale.3 Fri Dec 2 10:02:49 2011 (r228198) +++ head/lib/libc/locale/querylocale.3 Fri Dec 2 11:55:09 2011 (r228199) @@ -36,15 +36,15 @@ .Sh LIBRARY .Lb libc .Sh SYNOPSIS -.In xlocale.h +.In xlocale.h .Ft const char * .Fn querylocale "int mask" "locale_t locale" .Sh DESCRIPTION Returns the name of the locale for the category specified by .Fa mask. This possible values for the mask are the same as those in -.Xr newlocale 3 . If more than one bit in the mask is set, the returned value -is undefined. +.Xr newlocale 3 . +If more than one bit in the mask is set, the returned value is undefined. .Sh SEE ALSO .Xr duplocale 3 , .Xr freelocale 3 , Modified: head/lib/libc/locale/uselocale.3 ============================================================================== --- head/lib/libc/locale/uselocale.3 Fri Dec 2 10:02:49 2011 (r228198) +++ head/lib/libc/locale/uselocale.3 Fri Dec 2 11:55:09 2011 (r228199) @@ -36,17 +36,18 @@ .Sh LIBRARY .Lb libc .Sh SYNOPSIS -.In xlocale.h +.In xlocale.h .Ft locale_t .Fn uselocale "locale_t locale" .Sh DESCRIPTION -Specifies the locale for this thread to use. Specifying +Specifies the locale for this thread to use. +Specifying .Fa LC_GLOBAL_LOCALE -disables the per-thread locale, while NULL returns the current locale without -setting a new one. +disables the per-thread locale, +while NULL returns the current locale without setting a new one. .Sh RETURN VALUES -Returns the previous locale, or LC_GLOBAL_LOCALE if this thread has no locale -associated with it. +Returns the previous locale, +or LC_GLOBAL_LOCALE if this thread has no locale associated with it. .Sh SEE ALSO .Xr duplocale 3 , .Xr freelocale 3 , @@ -55,5 +56,5 @@ associated with it. .Xr querylocale 3 , .Xr xlocale 3 .Sh STANDARDS -This function, conforms to +This function conforms to .St -p1003.1-2008 Modified: head/lib/libc/locale/xlocale.3 ============================================================================== --- head/lib/libc/locale/xlocale.3 Fri Dec 2 10:02:49 2011 (r228198) +++ head/lib/libc/locale/xlocale.3 Fri Dec 2 11:55:09 2011 (r228199) @@ -39,39 +39,45 @@ .In xlocale.h .Sh DESCRIPTION The extended locale support includes a set of functions for setting -thread-local locales, as well convenience functions for performing locale-aware +thread-local locales, +as well convenience functions for performing locale-aware calls with a specified locale. .Pp The core of the xlocale API is the .Fa locale_t -type. This is an opaque type encapsulating a locale. Instances of this can be -either set as the locale for a specific thread or passed directly to the +type. +This is an opaque type encapsulating a locale. +Instances of this can be either set as the locale for a specific thread or +passed directly to the .Fa _l -suffixed variants of various standard C functions. Two special +suffixed variants of various standard C functions. +Two special .Fa locale_t values are available: -.Bl -bullet -offset indent +.Bl -bullet -offset indent .It -NULL refers to the current locale for the thread, or to the global locale if no -locale has been set for this thread. +NULL refers to the current locale for the thread, +or to the global locale if no locale has been set for this thread. .It LC_GLOBAL_LOCALE refers to the global locale. .El .Pp -The global locale is the locale set with the +The global locale is the locale set with the .Xr setlocale 3 function. .Sh CAVEATS -The +The .Xr setlocale 3 -function, and others in the family, refer to the global locale. Other -functions that depend on the locale, however, will take the thread-local locale -if one has been set. This means that the idiom of setting the locale using +function, and others in the family, refer to the global locale. +Other functions that depend on the locale, however, +will take the thread-local locale if one has been set. +This means that the idiom of setting the locale using .Xr setlocale 3 , -calling a locale-dependent function, and then restoring the locale will not +calling a locale-dependent function, +and then restoring the locale will not have the expected behavior if the current thread has had a locale set using .Xr uselocale 3 . -You should avoid this idiom and prefer to use the +You should avoid this idiom and prefer to use the .Fa _l suffixed versions instead. .Sh SEE ALSO @@ -84,29 +90,34 @@ suffixed versions instead. .Sh CONVENIENCE FUNCTIONS The xlocale API includes a number of .Fa _l -suffixed convenience functions. These are variants of standard C functions -that have been modified to take an explicit +suffixed convenience functions. +These are variants of standard C functions +that have been modified to take an explicit .Fa locale_t -parameter as the final argument or, in the case of variadic functions, as an -additional argument directly before the format string. Each of these functions -accepts either NULL or LC_GLOBAL_LOCALE. In these functions, NULL refers to -the C locale, rather than the thread's current locale. If you wish to use the -thread's current locale, then use the unsuffixed version of the function. +parameter as the final argument or, in the case of variadic functions, +as an additional argument directly before the format string. +Each of these functions accepts either NULL or LC_GLOBAL_LOCALE. +In these functions, NULL refers to the C locale, +rather than the thread's current locale. +If you wish to use the thread's current locale, +then use the unsuffixed version of the function. .Pp -These functions are exposed by including +These functions are exposed by including .In xlocale.h .Em after -including the relevant headers for the standard variant. For example, the +including the relevant headers for the standard variant. +For example, the .Xr strtol_l 3 -function is exposed by including +function is exposed by including .In xlocale.h -after +after .In stdlib.h , which defines .Xr strtol 3 . .Pp -For reference, a complete list of the locale-aware functions that are available -in this form, along with the headers that expose them, is provided here: +For reference, +a complete list of the locale-aware functions that are available in this form, +along with the headers that expose them, is provided here: .Pp .Bl -tag -width "<monetary.h> " .It In wctype.h @@ -117,7 +128,7 @@ in this form, along with the headers tha .Xr iswdigit_l 3 , .Xr iswgraph_l 3 , .Xr iswlower_l 3 , -.Xr iswprint_l 3 , +.Xr iswprint_l 3 , .Xr iswpunct_l 3 , .Xr iswspace_l 3 , .Xr iswupper_l 3 , @@ -264,7 +275,7 @@ The functions conform to .St -p1003.1-2008 . .Sh HISTORY -The xlocale APIs first appeared in Darwin 8.0. This implementation was -written by David Chisnall, under sponsorship from the FreeBSD Foundation and -first appeared in +The xlocale APIs first appeared in Darwin 8.0. +This implementation was written by David Chisnall, +under sponsorship from the FreeBSD Foundation and first appeared in .Fx 9.1 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201112021155.pB2BtA2W091372>