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.\" $FreeBSD$ 35.\" 36.Dd June 29, 2023 37.Dt LOCALEDEF 1 38.Os 39.Sh NAME 40.Nm localedef 41.Nd define locale environment 42.Sh SYNOPSIS 43.Nm 44.Op Fl bcDlUv 45.Op Fl f Ar charmap 46.Op Fl i Ar sourcefile 47.Op Fl u Ar codeset 48.Op Fl w Ar widthfile 49.Ar localename 50.Sh DESCRIPTION 51The 52.Nm 53utility converts source definitions for locale categories 54into a format usable by the functions and utilities whose operational behavior 55is determined by the setting of the locale environment variables; see 56.Xr environ 7 . 57.Pp 58The utility reads source definitions for one or more locale categories 59belonging to the same locale from the file named in the 60.Fl i 61option (if specified) or from standard input. 62.Pp 63Each category source definition is identified by the corresponding environment 64variable name and terminated by an 65.Sy END 66.Em category-name 67statement. 68The following categories are supported: 69.Bl -tag -width ".Ev LC_MONETARY" 70.It Ev LC_CTYPE 71Defines character classification and case conversion. 72.It Ev LC_COLLATE 73Defines collation rules. 74.It Ev LC_MONETARY 75Defines the format and symbols used in formatting of monetary information. 76.It Ev LC_NUMERIC 77Defines the decimal delimiter, grouping and grouping symbol for non-monetary 78numeric editing. 79.It Ev LC_TIME 80Defines the format and content of date and time information. 81.It Ev LC_MESSAGES 82Defines the format and values of affirmative and negative responses. 83.El 84.Pp 85The following options are supported: 86.Bl -tag -width indent 87.It Fl b 88Use big-endian byte order for output. 89.It Fl c 90Creates permanent output even if warning messages have been issued. 91.It Fl D 92BSD-style 93output. 94Rather than the default of creating the 95.Ar localename 96directory and creating files like 97.Pa LC_CTYPE , 98.Pa LC_COLLATE , 99etc.\& in that directory, 100the output file names have the format 101.Dq <localename>.<category> 102and are dumped to the current directory. 103.It Fl f Ar charmap 104Specifies the pathname of a file containing a mapping of character symbols and 105collating element symbols to actual character encodings. 106This option must be specified if symbolic names (other than collating symbols 107defined in a 108.Sy collating-symbol 109keyword) are used. 110If the 111.Fl f 112option is not present, the default character mapping will be used. 113.It Fl i Ar sourcefile 114The path name of a file containing the source definitions. 115If this option is not present, source definitions will be read from 116standard input. 117.It Fl l 118Use little-endian byte order for output. 119.It Fl u Ar codeset 120Specifies the name of a codeset used as the target mapping of character symbols 121and collating element symbols whose encoding values are defined in terms of the 122ISO/IEC 10646-1:2000 standard position constant values. 123See 124.Sx NOTES . 125.It Fl U 126Ignore the presence of character symbols that have no matching character 127definition. 128This facilitates the use of a common locale definition file to be used across multiple 129encodings, even when some symbols are not present in a given encoding. 130.It Fl v 131Emit verbose debugging output on standard output. 132.It Fl w Ar widthfile 133The path name of the file containing character screen width definitions. 134If not supplied, then default screen widths will be assumed, which will 135generally not account for East Asian encodings requiring more than a single 136character cell to display, nor for combining or accent marks that occupy 137no additional screen width. 138.It Fl V Ar version 139Specifies a version string describing the version of the locale definition. 140This string can be retrieved with 141.Xr querylocale 3 , 142and is intended to allow applications to detect locale definition changes. 143Currently it is stored only for the 144.Sy LC_COLLATE 145category. 146.El 147.Pp 148The following operands are required: 149.Bl -tag -width ".Ar localename" 150.It Ar localename 151Identifies the locale. 152If the name contains one or more slash characters, 153.Ar localename 154will be interpreted as a path name where the created locale 155definitions will be stored. 156This capability may be restricted to users with appropriate privileges. 157(As a consequence of specifying one 158.Ar localename , 159although several categories can be processed in one execution, only categories 160belonging to the same locale can be processed.) 161.El 162.Sh OUTPUT 163.Nm 164creates a directory of files that represents the locale's data, 165unless instructed otherwise by the 166.Fl D ( 167BSD 168output) option. 169The contants of this directory should generally be copied into the 170appropriate subdirectory of 171.Pa /usr/share/locale 172in order the definitions to be visible to programs linked with libc. 173.Sh ENVIRONMENT 174See 175.Xr environ 7 176for definitions of the following environment variables that affect the 177execution of 178.Nm : 179.Ev LANG , 180.Ev LC_ALL , 181.Ev LC_COLLATE , 182.Ev LC_CTYPE , 183.Ev LC_MESSAGES , 184.Ev LC_MONETARY , 185.Ev LC_MUMERIC , 186.Ev LC_TIME , 187and 188.Ev NLSPATH . 189.Sh EXIT STATUS 190The following exit values are returned: 191.Bl -tag -width XX 192.It 0 193No errors occurred and the locales were successfully created. 194.It 1 195Warnings occurred and the locales were successfully created. 196.It 2 197The locale specification exceeded implementation limits or the coded character 198set or sets used were not supported by the implementation, and no locale was 199created. 200.It >3 201Warnings or errors occurred and no output was created. 202.El 203.Pp 204If an error is detected, no permanent output will be created. 205.Sh SEE ALSO 206.Xr locale 1 , 207.Xr iconv_open 3 , 208.Xr nl_langinfo 3 , 209.Xr querylocale 3 , 210.Xr strftime 3 , 211.Xr environ 7 212.Sh WARNINGS 213If warnings occur, permanent output will be created if the 214.Fl c 215option was specified. 216The following conditions will cause warning messages to be issued: 217.Bl -bullet 218.It 219If a symbolic name not found in the 220.Pa charmap 221file is used for the descriptions of the 222.Sy LC_CTYPE 223or 224.Sy LC_COLLATE 225categories (for other categories, this will be an error condition). 226.It 227If optional keywords not supported by the implementation are present in the 228source. 229.El 230.Sh NOTES 231When the 232.Fl u 233option is used, the 234.Ar codeset 235option-argument is interpreted as a name of a codeset to which the 236ISO/IEC 10646-1:2000 standard position constant values are converted. 237Both the ISO/IEC 10646-1:2000 standard position constant values and 238other formats (decimal, hexadecimal, or octal) are valid as encoding 239values within the charmap file. 240The 241.Ar codeset 242can be any codeset that is supported by the 243.Fn iconv_open 3 244function. 245.Pp 246When conflicts occur between the charmap specification of 247.Ar codeset , 248.Em mb_cur_max , 249or 250.Em mb_cur_min 251and the corresponding value for the codeset represented by the 252.Fl u 253option-argument 254.Ar codeset , 255the 256.Nm 257utility fails with an error. 258.Pp 259When conflicts occur between the charmap encoding values specified for symbolic 260names of characters of the portable character set and the character encoding 261values defined by the US-ASCII, the result is unspecified. 262.Sh HISTORY 263.Nm 264first appeared in 265.Fx 11 . 266.Pp 267It was written by 268.An Garrett D'Amore 269.Aq Mt garrett@nexenta.com 270for illumos. 271.An John Marino 272.Aq Mt draco@marino.st 273provided the alternations necessary to compile cleanly on 274.Dx . 275.An Baptiste Daroussin 276.Aq Mt bapt@FreeBSD.org 277ported it to 278.Fx 279and converted it to 280.Xr tree 3 . 281