[src/trunk]: src/lib/libc/gen multi-byte doc from J.R. Oldroyd

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/04a76513a4a8
branches:  trunk
changeset: 784899:04a76513a4a8
user:      christos <christos%NetBSD.org@localhost>
date:      Wed Feb 13 22:17:12 2013 +0000

description:
multi-byte doc from J.R. Oldroyd

diffstat:

 lib/libc/gen/vis.3 |  32 +++++++++++++++++++++++++++++---
 1 files changed, 29 insertions(+), 3 deletions(-)

diffs (57 lines):

diff -r 7a2718389780 -r 04a76513a4a8 lib/libc/gen/vis.3
--- a/lib/libc/gen/vis.3        Wed Feb 13 22:15:43 2013 +0000
+++ b/lib/libc/gen/vis.3        Wed Feb 13 22:17:12 2013 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: vis.3,v 1.34 2012/12/15 07:34:24 wiz Exp $
+.\"    $NetBSD: vis.3,v 1.35 2013/02/13 22:17:12 christos Exp $
 .\"
 .\" Copyright (c) 1989, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"     @(#)vis.3      8.1 (Berkeley) 6/9/93
 .\"
-.Dd December 14, 2012
+.Dd February 13, 2013
 .Dt VIS 3
 .Os
 .Sh NAME
@@ -394,6 +394,26 @@
 .Ql M-C ) .
 With this flag set, the encoding is
 ambiguous and non-invertible.
+.Sh MULTIBYTE CHARACTER SUPPORT
+These functions support multibyte character input.
+The encoding conversion is influenced by the setting of the
+LC_CTYPE environment variable which defines the set of characters
+that can be copied without encoding.
+.Pp
+When 8-bit data is present in the input, LC_CTYPE must be set to
+the correct locale or to the C locale.
+If the locales of the data and the conversion are mismatched,
+multibyte character recognition may fail and encoding will be performed
+byte-by-byte instead.
+The result of encoding using one of these functions followed by
+decoding using the corresponding
+.Xr unvis 3
+function is unlikely to return the same input data in this case.
+.Sh ENVIRONMENT
+.Bl -tag -width ".Ev LC_CTYPE"
+.It Ev LC_CTYPE
+Specify the locale of the input data.
+Set to C if the input data locale is unknown.
 .Sh ERRORS
 The functions
 .Fn nvis
@@ -455,4 +475,10 @@
 and
 .Fn strsnvisx Pc
 appeared in
-.Nx 6.0 .
+.Nx 6.0
+and
+.Fx 9.2 .
+Myltibyte character support was added in
+.Nx 7.0
+and
+.Fx 9.2 .