1 files changed, 50 insertions, 8 deletions
diff --git a/lib/libc/gen/vis.3 b/lib/libc/gen/vis.3
index 6ca6afd7c1d..96b6996c290 100644
--- a/lib/libc/gen/vis.3
+++ b/lib/libc/gen/vis.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: vis.3,v 1.12 2000/09/14 17:47:09 aaron Exp $
+.\"	$OpenBSD: vis.3,v 1.13 2000/11/21 00:47:28 millert Exp $
 .\"
 .\" Copyright (c) 1989, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -37,6 +37,7 @@
 .Sh NAME
 .Nm vis ,
 .Nm strvis ,
+.Nm strnvis ,
 .Nm strvisx
 .Nd visually encode characters
 .Sh SYNOPSIS
@@ -46,7 +47,9 @@
 .Ft int
 .Fn strvis "char *dst" "char *src" "int flag"
 .Ft int
-.Fn strvisx "char *dst" "char *src" "int len" "int flag"
+.Fn strnvis "char *dst" "char *src" "size_t size" "int flag"
+.Ft int
+.Fn strvisx "char *dst" "char *src" "size_t len" "int flag"
 .Sh DESCRIPTION
 The
 .Fn vis
@@ -78,7 +81,8 @@ is only used when selecting the
 encoding format (explained below).
 .Pp
 The
-.Fn strvis
+.Fn strvis ,
+.Fn strnvis
 and
 .Fn strvisx
 functions copy into
@@ -92,6 +96,14 @@ function encodes characters from
 .Fa src
 up to the first NUL.
 The
+.Fn strnvis
+function encodes characters from
+.Fa src
+up to the first NUL or the end of
+.Fa dst ,
+as indicated by
+.Fa siz .
+The
 .Fn strvisx
 function encodes exactly
 .Fa len
@@ -99,18 +111,36 @@ characters from
 .Fa src
 (this
 is useful for encoding a block of data that may contain NULs).
-Both forms null terminate
+All three forms NUL terminate
 .Fa dst .
-The size of
+For
+.Fn strvis
+and
+.Fn strvisx ,
+the size of
 .Fa dst
 must be four times the number
 of characters encoded from
 .Fa src
 (plus one for the NUL).
-Both
-forms return the number of characters in
+.Fn strvis
+and
+.Fn strvisx
+return the number of characters in
 .Fa dst
 (not including the trailing NUL).
+.Fn strnvis
+returns the length that
+.Fa dst
+would become if it were of unlimited size (similar to
+.Xr snprintf 3
+or
+.Xr strlcpy 3 ) .
+This can be used to detect truncation but it also means that
+the return value of
+.Fn strnvis
+must not be used without checking it against
+.Fa siz .
 .Pp
 The encoding is a unique, invertible representation composed entirely of
 graphic characters; it can be decoded back into the original form using
@@ -259,7 +289,19 @@ ambiguous and non-invertible.
 .Sh SEE ALSO
 .Xr unvis 1 ,
 .Xr vis 1 ,
+.Xr snprintf 3 ,
+.Xr strlcpy 3 ,
 .Xr unvis 3
 .Sh HISTORY
-These functions first appeared in
+The
+.Fn vis ,
+.Fn strvis
+and
+.Fn strvisx
+functions first appeared in
 .Bx 4.4 .
+.br
+The
+.Fn strnvis
+function first appeared in
+.Ox 2.9 .