-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpunycode.3
92 lines (92 loc) · 2.72 KB
/
punycode.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
.\" $OpenBSD: mdoc.template,v 1.15 2014/03/31 00:09:54 dlg Exp $
.\"
.\" Copyright (c) 2023 Guilherme Janczak <[email protected]>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: January 9 2023 $
.Dt PUNYENC 3
.Os
.Sh NAME
.Nm punycode, punyenc
.Nd punycode encoder
.Sh SYNOPSIS
.In punycode.h
.Ft size_t
.Fn punyenc "char *restrict dst" "const char src[restrict static 1]" "size_t dstsize"
.Sh DESCRIPTION
The
.Fn punyenc
function encodes the case-folded UTF-8 string in
.Fa src
to US-ASCII punycode,
and stores it in the buffer
.Fa dst
of size
.Fa dstsize .
.Pp
.Fn punyenc
guarantees '\\0' termination if
.Fa dstsize
isn't 0, and truncates the resulting string to fit into
.Fa dstsize
bytes if necessary.
.Pp
This interface is modeled after
.Fn strlcpy
and has the same type and almost the same usage,
it differs only by having an error return value.
.Sh RETURN VALUES
If there is an irrecoverable encoding error,
(size_t)-1 is returned.
Otherwise,
the function returns the string length of the resulting punycode.
.Pp
If the return value is >=
.Fa dstsize ,
the output string has been truncated.
.Pp
If a given
.Fa src
string hasn't caused
.Fn punyenc
to return (size_t)-1 once,
the same string will never return error.
This is useful when retrying on truncation.
.Sh EXAMPLES
Proper usage of the function involves growing
.Fa dst
on truncation and only hard-erroring in case of irrecoverable failure.
.Bd -literal -offset indent
if ((ret = punyenc(dst, src, dstsize)) == (size_t)-1) {
errx(1, "punyenc: irrecoverable encoding error");
} else if (ret >= dstsize) {
dstsize = ret+1; /* Space for the '\\0' terminator. */
if ((tmp = realloc(dst, dstsize)) == NULL)
err(1, "realloc");
dst = tmp;
(void)punyenc(dst, src, dstsize); /* Can't fail. */
}
.Ed
.Sh SEE ALSO
.Xr strlcpy 3
.\" punydec 3
.Sh STANDARDS
RFC 3492: Punycode: A Bootstring encoding of Unicode
.Sh AUTHORS
.An -nosplit
.An Guilherme Janczak Aq Mt [email protected] .
.Pp
This punycode implementation features code from punycode-sample.c 2.0.0
written by
.An Adam M. Costello .