Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LOCALE(1P)		   POSIX Programmer's Manual		    LOCALE(1P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface	may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

NAME
       locale -	get locale-specific information

SYNOPSIS
       locale [-a| -m]

       locale [-ck] name...

DESCRIPTION
       The locale utility shall	write information about	the current locale en-
       vironment,  or all public locales, to the standard output. For the pur-
       poses of	this section, a	public locale is one provided by the implemen-
       tation that is accessible to the	application.

       When  locale  is	 invoked without any arguments,	it shall summarize the
       current locale environment for each locale category  as	determined  by
       the  settings  of the environment variables defined in the Base Defini-
       tions volume of IEEE Std	1003.1-2001, Chapter 7,	Locale.

       When invoked with operands, it shall write values that  have  been  as-
       signed to the keywords in the locale categories,	as follows:

	* Specifying  a	 keyword  name	shall select the named keyword and the
	  category containing that keyword.

	* Specifying a category	name shall select the named category  and  all
	  keywords in that category.

OPTIONS
       The  locale  utility  shall  conform  to	the Base Definitions volume of
       IEEE Std	1003.1-2001, Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported:

       -a     Write information	about all available public locales. The	avail-
	      able locales shall include POSIX,	representing the POSIX locale.
	      The manner in which the implementation determines	what other lo-
	      cales are	available is implementation-defined.

       -c     Write  the  names	 of selected locale categories;	see the	STDOUT
	      section.	The -c option increases	readability when more than one
	      category	is  selected  (for  example, via more than one keyword
	      name or via a category name). It is valid	both with and  without
	      the -k option.

       -k     Write the	names and values of selected keywords. The implementa-
	      tion may omit values for some keywords; see  the	OPERANDS  sec-
	      tion.

       -m     Write names of available charmaps; see the Base Definitions vol-
	      ume of IEEE Std 1003.1-2001,  Section  6.1,  Portable  Character
	      Set.

OPERANDS
       The following operand shall be supported:

       name   The name of a locale category as defined in the Base Definitions
	      volume of	IEEE Std 1003.1-2001, Chapter 7, Locale, the name of a
	      keyword  in a locale category, or	the reserved name charmap. The
	      named category or	keyword	shall be selected  for	output.	 If  a
	      single name represents both a locale category name and a keyword
	      name in the current locale, the results are unspecified.	Other-
	      wise,  both  category and	keyword	names can be specified as name
	      operands,	in any sequence. It is implementation-defined  whether
	      any  keyword  values are written for the categories LC_CTYPE and
	      LC_COLLATE.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect	the execution  of  lo-
       cale:

       LANG   Provide  a  default value	for the	internationalization variables
	      that are unset or	null. (See  the	 Base  Definitions  volume  of
	      IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari-
	      ables for	the precedence of internationalization variables  used
	      to determine the values of locale	categories.)

       LC_ALL If  set  to a non-empty string value, override the values	of all
	      the other	internationalization variables.

       LC_CTYPE
	      Determine	the locale for	the  interpretation  of	 sequences  of
	      bytes  of	 text  data as characters (for example,	single-byte as
	      opposed to multi-byte characters in arguments and	input files).

       LC_MESSAGES
	      Determine	the locale that	should be used to  affect  the	format
	      and contents of diagnostic messages written to standard error.

       NLSPATH
	      Determine	the location of	message	catalogs for the processing of
	      LC_MESSAGES .

       The application shall ensure that the LANG,  LC_*,  and	NLSPATH	 envi-
       ronment	variables specify the current locale environment to be written
       out; they shall be used if the -a option	is not specified.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       If locale is invoked without any	options	or  operands,  the  names  and
       values  of  the	LANG  and LC_* environment variables described in this
       volume of IEEE Std 1003.1-2001 shall be written to the standard output,
       one variable per	line, with LANG	first, and each	line using the follow-
       ing format.  Only those variables set in	the environment	and not	 over-
       ridden by LC_ALL	shall be written using this format:

	      "%s=%s\n", <variable_name>, <value>

       The names of those LC_* variables associated with locale	categories de-
       fined in	this volume of IEEE Std	1003.1-2001 that are not  set  in  the
       environment or are overridden by	LC_ALL shall be	written	in the follow-
       ing format:

	      "%s=\"%s\"\n", <variable_name>, <implied value>

       The <implied value> shall be the	name of	the locale that	has  been  se-
       lected  for that	category by the	implementation,	based on the values in
       LANG and	LC_ALL,	 as  described	in  the	 Base  Definitions  volume  of
       IEEE Std	1003.1-2001, Chapter 8,	Environment Variables.

       The  <value>  and  <implied value> shown	above shall be properly	quoted
       for possible later reentry to the  shell.  The  <value>	shall  not  be
       quoted using double-quotes (so that it can be distinguished by the user
       from the	<implied value>	case, which always requires double-quotes).

       The LC_ALL variable shall be written last, using	the first format shown
       above. If it is not set,	it shall be written as:

	      "LC_ALL=\n"

       If any arguments	are specified:

	1. If  the -a option is	specified, the names of	all the	public locales
	   shall be written, each in the following format:

	   "%s\n", <locale name>

	2. If the -c option is specified, the names of all selected categories
	   shall be written, each in the following format:

	   "%s\n", <category name>

       If  keywords  are  also selected	for writing (see following items), the
       category	name output shall precede the keyword output  for  that	 cate-
       gory.

       If  the	-c  option is not specified, the names of the categories shall
       not be written; only the	keywords, as selected by the  <name>  operand,
       shall be	written.

	3. If  the  -k	option	is specified, the names	and values of selected
	   keywords shall be written. If a value is non-numeric, it  shall  be
	   written in the following format:

	   "%s=\"%s\"\n", <keyword name>, <keyword value>

       If  the	keyword	was charmap, the name of the charmap (if any) that was
       specified via the localedef -f option when the locale was created shall
       be written, with	the word charmap as <keyword name>.

       If a value is numeric, it shall be written in one of the	following for-
       mats:

	      "%s=%d\n", <keyword name>, <keyword value>

	      "%s=%c%o\n", <keyword name>, <escape character>, <keyword	value>

	      "%s=%cx%x\n", <keyword name>, <escape character>,	<keyword value>

       where the <escape character> is that identified by the escape_char key-
       word  in	 the  current  locale;	see  the  Base	Definitions  volume of
       IEEE Std	1003.1-2001, Section 7.3, Locale Definition.

       Compound	keyword	values (list entries) shall be separated in the	output
       by semicolons. When included in keyword values, the semicolon, the dou-
       ble-quote, the backslash, and any control character shall  be  preceded
       (escaped) with the escape character.

	4. If the -k option is not specified, selected keyword values shall be
	   written, each in the	following format:

	   "%s\n", <keyword value>

       If the keyword was charmap, the name of the charmap (if any)  that  was
       specified via the localedef -f option when the locale was created shall
       be written.

	5. If the -m option  is	 specified,  then  a  list  of	all  available
	   charmaps shall be written, each in the format:

	   "%s\n", <charmap>

       where  <charmap>	is in a	format suitable	for use	as the option-argument
       to the localedef	-f option.

STDERR
       The standard error shall	be used	only for diagnostic messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

	0     All the requested	information was	found and output successfully.

       >0     An error occurred.

CONSEQUENCES OF	ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       If the LANG environment variable	is not set or set to an	 empty	value,
       or  one	of  the	 LC_*  environment variables is	set to an unrecognized
       value, the actual locales assumed (if any)  are	implementation-defined
       as  described  in  the Base Definitions volume of IEEE Std 1003.1-2001,
       Chapter 8, Environment Variables.

       Implementations are not required	to write out  the  actual  values  for
       keywords	in the categories LC_CTYPE and LC_COLLATE ; however, they must
       write out the categories	(allowing an application to determine, for ex-
       ample, which character classes are available).

EXAMPLES
       In  the	following  examples, the assumption is that locale environment
       variables are set as follows:

	      LANG=locale_x
	      LC_COLLATE=locale_y

       The command locale would	result in the following	output:

	      LANG=locale_x
	      LC_CTYPE="locale_x"
	      LC_COLLATE=locale_y
	      LC_TIME="locale_x"
	      LC_NUMERIC="locale_x"
	      LC_MONETARY="locale_x"
	      LC_MESSAGES="locale_x"
	      LC_ALL=

       The order of presentation of the	categories is not  specified  by  this
       volume of IEEE Std 1003.1-2001.

       The command:

	      LC_ALL=POSIX locale -ck decimal_point

       would produce:

	      LC_NUMERIC
	      decimal_point="."

       The  following  command	shows  an  application	of locale to determine
       whether a user-supplied response	is affirmative:

	      if printf	"%s\n" "$response" | grep -Eq "$(locale	yesexpr)"
	      then
		  affirmative processing goes here
	      else
		  non-affirmative processing goes here
	      fi

RATIONALE
       The output for categories LC_CTYPE and LC_COLLATE has been made	imple-
       mentation-defined  because  there  is  a	questionable value in having a
       shell script receive an entire array of characters. It is  also	diffi-
       cult  to	 return	 a logical collation description, short	of returning a
       complete	localedef source.

       The -m option was included to allow applications	to query for the exis-
       tence  of  charmaps.  The output	is a list of the charmaps (implementa-
       tion-supplied and user-supplied,	if any)	on the system.

       The -c option was included for readability when more than one  category
       is selected (for	example, via more than one keyword name	or via a cate-
       gory name). It is valid both with and without the -k option.

       The charmap keyword, which returns the name of  the  charmap  (if  any)
       that  was used when the current locale was created, was included	to al-
       low applications	needing	the information	to retrieve it.

FUTURE DIRECTIONS
       None.

SEE ALSO
       localedef, the Base Definitions volume of IEEE Std 1003.1-2001, Section
       7.3, Locale Definition

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for	Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003	by  the	 Institute  of
       Electrical  and	Electronics  Engineers,	Inc and	The Open Group.	In the
       event of	any discrepancy	between	this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open	Group Standard
       is the referee document.	The original Standard can be  obtained	online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003			    LOCALE(1P)

PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=locale&sektion=1&manpath=CentOS+7.1>

home | help