1.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved 2.\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved 3.\" Portions Copyright 2013 DEY Storage Systems, Inc. 4.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 5.\" permission to reproduce portions of its copyrighted documentation. 6.\" Original documentation from The Open Group can be obtained online at 7.\" http://www.opengroup.org/bookstore/. 8.\" The Institute of Electrical and Electronics Engineers and The Open Group, 9.\" have given us permission to reprint portions of their documentation. In 10.\" the following statement, the phrase "this text" refers to portions of the 11.\" system documentation. Portions of this text are reprinted and reproduced 12.\" in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 13.\" 2004 Edition, Standard for Information Technology -- Portable Operating 14.\" System Interface (POSIX), The Open Group Base Specifications Issue 6, 15.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 16.\" Engineers, Inc and The Open Group. In the event of any discrepancy between 17.\" these versions and the original IEEE and The Open Group Standard, the 18.\" original IEEE and The Open Group Standard is the referee document. The 19.\" original Standard can be obtained online at 20.\" http://www.opengroup.org/unix/online.html. 21.\" This notice shall appear on any product containing this material. 22.\" The contents of this file are subject to the terms of the Common 23.\" Development and Distribution License (the "License"). You may not use 24.\" this file except in compliance with the License. 25.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or 26.\" http://www.opensolaris.org/os/licensing. See the License for the specific 27.\" language governing permissions and limitations under the License. 28.\" When distributing Covered Code, include this CDDL HEADER in each file and 29.\" include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, 30.\" add the following below this CDDL HEADER, with the fields enclosed by 31.\" brackets "[]" replaced with your own identifying information: 32.\" Portions Copyright [yyyy] [name of copyright owner] 33.\" 34.Dd June 29, 2023 35.Dt LOCALEDEF 1 36.Os 37.Sh NAME 38.Nm localedef 39.Nd define locale environment 40.Sh SYNOPSIS 41.Nm 42.Op Fl bcDlUv 43.Op Fl f Ar charmap 44.Op Fl i Ar sourcefile 45.Op Fl u Ar codeset 46.Op Fl w Ar widthfile 47.Ar localename 48.Sh DESCRIPTION 49The 50.Nm 51utility converts source definitions for locale categories 52into a format usable by the functions and utilities whose operational behavior 53is determined by the setting of the locale environment variables; see 54.Xr environ 7 . 55.Pp 56The utility reads source definitions for one or more locale categories 57belonging to the same locale from the file named in the 58.Fl i 59option (if specified) or from standard input. 60.Pp 61Each category source definition is identified by the corresponding environment 62variable name and terminated by an 63.Sy END 64.Em category-name 65statement. 66The following categories are supported: 67.Bl -tag -width ".Ev LC_MONETARY" 68.It Ev LC_CTYPE 69Defines character classification and case conversion. 70.It Ev LC_COLLATE 71Defines collation rules. 72.It Ev LC_MONETARY 73Defines the format and symbols used in formatting of monetary information. 74.It Ev LC_NUMERIC 75Defines the decimal delimiter, grouping and grouping symbol for non-monetary 76numeric editing. 77.It Ev LC_TIME 78Defines the format and content of date and time information. 79.It Ev LC_MESSAGES 80Defines the format and values of affirmative and negative responses. 81.El 82.Pp 83The following options are supported: 84.Bl -tag -width indent 85.It Fl b 86Use big-endian byte order for output. 87.It Fl c 88Creates permanent output even if warning messages have been issued. 89.It Fl D 90BSD-style 91output. 92Rather than the default of creating the 93.Ar localename 94directory and creating files like 95.Pa LC_CTYPE , 96.Pa LC_COLLATE , 97etc.\& in that directory, 98the output file names have the format 99.Dq <localename>.<category> 100and are dumped to the current directory. 101.It Fl f Ar charmap 102Specifies the pathname of a file containing a mapping of character symbols and 103collating element symbols to actual character encodings. 104This option must be specified if symbolic names (other than collating symbols 105defined in a 106.Sy collating-symbol 107keyword) are used. 108If the 109.Fl f 110option is not present, the default character mapping will be used. 111.It Fl i Ar sourcefile 112The path name of a file containing the source definitions. 113If this option is not present, source definitions will be read from 114standard input. 115.It Fl l 116Use little-endian byte order for output. 117.It Fl u Ar codeset 118Specifies the name of a codeset used as the target mapping of character symbols 119and collating element symbols whose encoding values are defined in terms of the 120ISO/IEC 10646-1:2000 standard position constant values. 121See 122.Sx NOTES . 123.It Fl U 124Ignore the presence of character symbols that have no matching character 125definition. 126This facilitates the use of a common locale definition file to be used across multiple 127encodings, even when some symbols are not present in a given encoding. 128.It Fl v 129Emit verbose debugging output on standard output. 130.It Fl w Ar widthfile 131The path name of the file containing character screen width definitions. 132If not supplied, then default screen widths will be assumed, which will 133generally not account for East Asian encodings requiring more than a single 134character cell to display, nor for combining or accent marks that occupy 135no additional screen width. 136.It Fl V Ar version 137Specifies a version string describing the version of the locale definition. 138This string can be retrieved with 139.Xr querylocale 3 , 140and is intended to allow applications to detect locale definition changes. 141Currently it is stored only for the 142.Sy LC_COLLATE 143category. 144.El 145.Pp 146The following operands are required: 147.Bl -tag -width ".Ar localename" 148.It Ar localename 149Identifies the locale. 150If the name contains one or more slash characters, 151.Ar localename 152will be interpreted as a path name where the created locale 153definitions will be stored. 154This capability may be restricted to users with appropriate privileges. 155(As a consequence of specifying one 156.Ar localename , 157although several categories can be processed in one execution, only categories 158belonging to the same locale can be processed.) 159.El 160.Sh OUTPUT 161.Nm 162creates a directory of files that represents the locale's data, 163unless instructed otherwise by the 164.Fl D ( 165BSD 166output) option. 167The contants of this directory should generally be copied into the 168appropriate subdirectory of 169.Pa /usr/share/locale 170in order the definitions to be visible to programs linked with libc. 171.Sh ENVIRONMENT 172See 173.Xr environ 7 174for definitions of the following environment variables that affect the 175execution of 176.Nm : 177.Ev LANG , 178.Ev LC_ALL , 179.Ev LC_COLLATE , 180.Ev LC_CTYPE , 181.Ev LC_MESSAGES , 182.Ev LC_MONETARY , 183.Ev LC_MUMERIC , 184.Ev LC_TIME , 185and 186.Ev NLSPATH . 187.Sh EXIT STATUS 188The following exit values are returned: 189.Bl -tag -width XX 190.It 0 191No errors occurred and the locales were successfully created. 192.It 1 193Warnings occurred and the locales were successfully created. 194.It 2 195The locale specification exceeded implementation limits or the coded character 196set or sets used were not supported by the implementation, and no locale was 197created. 198.It >3 199Warnings or errors occurred and no output was created. 200.El 201.Pp 202If an error is detected, no permanent output will be created. 203.Sh SEE ALSO 204.Xr locale 1 , 205.Xr iconv_open 3 , 206.Xr nl_langinfo 3 , 207.Xr querylocale 3 , 208.Xr strftime 3 , 209.Xr environ 7 210.Sh WARNINGS 211If warnings occur, permanent output will be created if the 212.Fl c 213option was specified. 214The following conditions will cause warning messages to be issued: 215.Bl -bullet 216.It 217If a symbolic name not found in the 218.Pa charmap 219file is used for the descriptions of the 220.Sy LC_CTYPE 221or 222.Sy LC_COLLATE 223categories (for other categories, this will be an error condition). 224.It 225If optional keywords not supported by the implementation are present in the 226source. 227.El 228.Sh NOTES 229When the 230.Fl u 231option is used, the 232.Ar codeset 233option-argument is interpreted as a name of a codeset to which the 234ISO/IEC 10646-1:2000 standard position constant values are converted. 235Both the ISO/IEC 10646-1:2000 standard position constant values and 236other formats (decimal, hexadecimal, or octal) are valid as encoding 237values within the charmap file. 238The 239.Ar codeset 240can be any codeset that is supported by the 241.Fn iconv_open 3 242function. 243.Pp 244When conflicts occur between the charmap specification of 245.Ar codeset , 246.Em mb_cur_max , 247or 248.Em mb_cur_min 249and the corresponding value for the codeset represented by the 250.Fl u 251option-argument 252.Ar codeset , 253the 254.Nm 255utility fails with an error. 256.Pp 257When conflicts occur between the charmap encoding values specified for symbolic 258names of characters of the portable character set and the character encoding 259values defined by the US-ASCII, the result is unspecified. 260.Sh HISTORY 261.Nm 262first appeared in 263.Fx 11 . 264.Pp 265It was written by 266.An Garrett D'Amore 267.Aq Mt garrett@nexenta.com 268for illumos. 269.An John Marino 270.Aq Mt draco@marino.st 271provided the alternations necessary to compile cleanly on 272.Dx . 273.An Baptiste Daroussin 274.Aq Mt bapt@FreeBSD.org 275ported it to 276.Fx 277and converted it to 278.Xr tree 3 . 279