logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

newlocale.3p (6486B)


  1. '\" et
  2. .TH NEWLOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. newlocale
  12. \(em create or modify a locale object
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <locale.h>
  17. .P
  18. locale_t newlocale(int \fIcategory_mask\fP, const char *\fIlocale\fP,
  19. locale_t \fIbase\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fInewlocale\fR()
  24. function shall create a new locale object or modify an existing one.
  25. If the
  26. .IR base
  27. argument is (\c
  28. .BR locale_t )0,
  29. a new locale object shall be created. It is unspecified whether the
  30. locale object pointed to by
  31. .IR base
  32. shall be modified, or freed and a new locale object created.
  33. .P
  34. The
  35. .IR category_mask
  36. argument specifies the locale categories to be set or modified.
  37. Values for
  38. .IR category_mask
  39. shall be constructed by a bitwise-inclusive OR of the symbolic
  40. constants
  41. .IR LC_CTYPE_MASK ,
  42. .IR LC_NUMERIC_MASK ,
  43. .IR LC_TIME_MASK ,
  44. .IR LC_COLLATE_MASK ,
  45. .IR LC_MONETARY_MASK ,
  46. and
  47. .IR LC_MESSAGES_MASK ,
  48. or any of the implementation-defined mask values defined in
  49. .IR <locale.h> .
  50. .P
  51. For each category with the corresponding bit set in
  52. .IR category_mask
  53. the data from the locale named by
  54. .IR locale
  55. shall be used. In the case of modifying an existing locale object, the
  56. data from the locale named by
  57. .IR locale
  58. shall replace the existing data within the locale object. If a completely
  59. new locale object is created, the data for all sections not requested by
  60. .IR category_mask
  61. shall be taken from the default locale.
  62. .P
  63. The following preset values of
  64. .IR locale
  65. are defined for all settings of
  66. .IR category_mask :
  67. .IP "\&\(dqPOSIX\(dq" 12
  68. Specifies the minimal environment for C-language translation called
  69. the POSIX locale.
  70. .IP "\&\(dqC\(dq" 12
  71. Equivalent to
  72. .BR \(dqPOSIX\(dq .
  73. .IP "\&\(dq\|\(dq" 12
  74. Specifies an implementation-defined native environment. This corresponds
  75. to the value of the associated environment variables,
  76. .IR LC_*
  77. and
  78. .IR LANG ;
  79. see the Base Definitions volume of POSIX.1\(hy2017,
  80. .IR "Chapter 7" ", " "Locale"
  81. and
  82. .IR "Chapter 8" ", " "Environment Variables".
  83. .P
  84. If the
  85. .IR base
  86. argument is not (\c
  87. .BR locale_t )0
  88. and the
  89. \fInewlocale\fR()
  90. function call succeeds, the contents of
  91. .IR base
  92. are unspecified. Applications shall ensure that they stop using
  93. .IR base
  94. as a locale object before calling
  95. \fInewlocale\fR().
  96. If the function call fails and the
  97. .IR base
  98. argument is not (\c
  99. .BR locale_t )0,
  100. the contents of
  101. .IR base
  102. shall remain valid and unchanged.
  103. .P
  104. The behavior is undefined if the
  105. .IR base
  106. argument is the special locale object LC_GLOBAL_LOCALE, or is not a
  107. valid locale object handle and is not (\c
  108. .BR locale_t )0.
  109. .SH "RETURN VALUE"
  110. Upon successful completion, the
  111. \fInewlocale\fR()
  112. function shall return a handle which the caller may use on subsequent
  113. calls to
  114. \fIduplocale\fR(),
  115. \fIfreelocale\fR(),
  116. and other functions taking a
  117. .BR locale_t
  118. argument.
  119. .P
  120. Upon failure, the
  121. \fInewlocale\fR()
  122. function shall return (\c
  123. .BR locale_t )0
  124. and set
  125. .IR errno
  126. to indicate the error.
  127. .SH ERRORS
  128. The
  129. \fInewlocale\fR()
  130. function shall fail if:
  131. .TP
  132. .BR ENOMEM
  133. There is not enough memory available to create the locale object or
  134. load the locale data.
  135. .TP
  136. .BR EINVAL
  137. The
  138. .IR category_mask
  139. contains a bit that does not correspond to a valid category.
  140. .TP
  141. .BR ENOENT
  142. For any of the categories in
  143. .IR category_mask ,
  144. the locale data is not available.
  145. .P
  146. The
  147. \fInewlocale\fR()
  148. function may fail if:
  149. .TP
  150. .BR EINVAL
  151. The
  152. .IR locale
  153. argument is not a valid string pointer.
  154. .LP
  155. .IR "The following sections are informative."
  156. .SH EXAMPLES
  157. .SS "Constructing a Locale Object from Different Locales"
  158. .P
  159. The following example shows the construction of a locale where the
  160. .IR LC_CTYPE
  161. category data comes from a locale
  162. .IR loc1
  163. and the
  164. .IR LC_TIME
  165. category data from a locale
  166. .IR loc2 :
  167. .sp
  168. .RS 4
  169. .nf
  170. #include <locale.h>
  171. \&...
  172. locale_t loc, new_loc;
  173. .P
  174. /* Get the "loc1" data. */
  175. .P
  176. loc = newlocale (LC_CTYPE_MASK, "loc1", (locale_t)0);
  177. if (loc == (locale_t) 0)
  178. abort ();
  179. .P
  180. /* Get the "loc2" data. */
  181. .P
  182. new_loc = newlocale (LC_TIME_MASK, "loc2", loc);
  183. if (new_loc != (locale_t) 0)
  184. /* We don t abort if this fails. In this case this
  185. simply used to unchanged locale object. */
  186. loc = new_loc;
  187. .P
  188. \&...
  189. .fi
  190. .P
  191. .RE
  192. .SS "Freeing up a Locale Object"
  193. .P
  194. The following example shows a code fragment to free a locale object
  195. created by
  196. \fInewlocale\fR():
  197. .sp
  198. .RS 4
  199. .nf
  200. #include <locale.h>
  201. \&...
  202. .P
  203. /* Every locale object allocated with newlocale() should be
  204. * freed using freelocale():
  205. */
  206. .P
  207. locale_t loc;
  208. .P
  209. /* Get the locale. */
  210. .P
  211. loc = newlocale (LC_CTYPE_MASK | LC_TIME_MASK, "locname", (locale_t)0);
  212. .P
  213. /* ... Use the locale object ... */
  214. \&...
  215. .P
  216. /* Free the locale object resources. */
  217. freelocale (loc);
  218. .fi
  219. .P
  220. .RE
  221. .SH "APPLICATION USAGE"
  222. Handles for locale objects created by the
  223. \fInewlocale\fR()
  224. function should either be released by a corresponding call to
  225. \fIfreelocale\fR(),
  226. or be used as a base locale to another
  227. \fInewlocale\fR()
  228. call.
  229. .P
  230. The special locale object LC_GLOBAL_LOCALE must not be passed for the
  231. .IR base
  232. argument, even when returned by the
  233. \fIuselocale\fR()
  234. function.
  235. .SH RATIONALE
  236. None.
  237. .SH "FUTURE DIRECTIONS"
  238. None.
  239. .SH "SEE ALSO"
  240. .IR "\fIduplocale\fR\^(\|)",
  241. .IR "\fIfreelocale\fR\^(\|)",
  242. .IR "\fIuselocale\fR\^(\|)"
  243. .P
  244. The Base Definitions volume of POSIX.1\(hy2017,
  245. .IR "Chapter 7" ", " "Locale",
  246. .IR "Chapter 8" ", " "Environment Variables",
  247. .IR "\fB<locale.h>\fP"
  248. .\"
  249. .SH COPYRIGHT
  250. Portions of this text are reprinted and reproduced in electronic form
  251. from IEEE Std 1003.1-2017, Standard for Information Technology
  252. -- Portable Operating System Interface (POSIX), The Open Group Base
  253. Specifications Issue 7, 2018 Edition,
  254. Copyright (C) 2018 by the Institute of
  255. Electrical and Electronics Engineers, Inc and The Open Group.
  256. In the event of any discrepancy between this version and the original IEEE and
  257. The Open Group Standard, the original IEEE and The Open Group Standard
  258. is the referee document. The original Standard can be obtained online at
  259. http://www.opengroup.org/unix/online.html .
  260. .PP
  261. Any typographical or formatting errors that appear
  262. in this page are most likely
  263. to have been introduced during the conversion of the source files to
  264. man page format. To report such errors, see
  265. https://www.kernel.org/doc/man-pages/reporting_bugs.html .