Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1989, 1991 The Regents of the University of California. |
56df4199 MT |
2 | .\" All rights reserved. |
3 | .\" | |
947d15f7 | 4 | .\" %sccs.include.redist.man% |
56df4199 | 5 | .\" |
ae59e04c | 6 | .\" @(#)unvis.3 1.3 (Berkeley) %G% |
56df4199 | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt UNVIS 3 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm unvis , | |
13 | .Nm strunvis | |
14 | .Nd decode a visual representation of characters | |
15 | .Sh SYNOPSIS | |
16 | .Fd #include <vis.h> | |
17 | .Ft int | |
18 | .Fn unvis "u_char *cp" "u_char c" "int *astate" "int flag" | |
19 | .Ft int | |
20 | .Fn strunvis "char *dst" "char *src" | |
21 | .Sh DESCRIPTION | |
22 | The | |
23 | .Fn unvis | |
947d15f7 | 24 | and |
ae59e04c CL |
25 | .Fn strunvis |
26 | functions | |
947d15f7 | 27 | are used to decode a visual representation of characters, as produced |
ae59e04c CL |
28 | by the |
29 | .Xr vis 3 | |
30 | function, back into | |
31 | the original form. Unvis is called with successive characters in | |
32 | .Ar c | |
947d15f7 MT |
33 | until a valid |
34 | sequence is recognized, at which time the decoded character is | |
ae59e04c CL |
35 | available at the character pointed to by |
36 | .Ar cp . | |
37 | Strunvis decodes the | |
38 | characters pointed to by | |
39 | .Ar src | |
40 | into the buffer pointed to by | |
41 | .Ar dst . | |
42 | .Pp | |
43 | The | |
44 | .Fn strunvis | |
45 | function | |
46 | simply copies | |
47 | .Ar src | |
48 | to | |
49 | .Ar dst , | |
50 | decoding any escape sequences along the way, | |
51 | and returns the number of characters placed into | |
52 | .Ar dst , | |
53 | or \-1 if an | |
54 | invalid escape sequence was detected. The size of | |
55 | .Ar dst | |
56 | should be | |
57 | equal to the size of | |
58 | .Ar src | |
59 | (that is, no expansion takes place during | |
947d15f7 | 60 | decoding). |
ae59e04c CL |
61 | .Pp |
62 | The | |
63 | .Fn unvis | |
64 | function | |
947d15f7 MT |
65 | implements a state machine that can be used to decode an arbitrary |
66 | stream of bytes. All state associated with the bytes being decoded | |
67 | is stored outside the | |
ae59e04c | 68 | .Fn unvis |
947d15f7 MT |
69 | function (that is, a pointer to the state is passed in), so |
70 | calls decoding different streams can be freely intermixed. To | |
71 | start decoding a stream of bytes, first initialize an integer | |
ae59e04c CL |
72 | to zero. Call |
73 | .Fn unvis | |
74 | with each successive byte, along with a pointer | |
947d15f7 | 75 | to this integer, and a pointer to an destination character. |
ae59e04c CL |
76 | The |
77 | .Xr unvis | |
78 | function | |
947d15f7 | 79 | has several return codes that must be handled properly. They are: |
ae59e04c CL |
80 | .Bl -tag -width UNVIS_VALIDPUSH |
81 | .It Li \&0 (zero) | |
947d15f7 | 82 | Another character is necessary; nothing has been recognized yet. |
ae59e04c | 83 | .It Dv UNVIS_VALID |
947d15f7 MT |
84 | A valid character has been recognized and is available at the location |
85 | pointed to by cp. | |
ae59e04c | 86 | .It Dv UNVIS_VALIDPUSH |
947d15f7 MT |
87 | A valid character has been recognized and is available at the location |
88 | pointed to by cp; however, the character currently passed in should | |
89 | be passed in again. | |
ae59e04c | 90 | .It Dv UNVIS_NOCHAR |
947d15f7 MT |
91 | A valid sequence was detected, but no character was produced. This |
92 | return code is necessary to indicate a logical break between characters. | |
ae59e04c | 93 | .It Dv UNVIS_SYNBAD |
947d15f7 MT |
94 | An invalid esacpe sequence was detected, or the decoder is in an |
95 | unknown state. The decoder is placed into the starting state. | |
ae59e04c CL |
96 | .El |
97 | .Pp | |
947d15f7 | 98 | When all bytes in the stream have been processed, call |
ae59e04c | 99 | .Fn unvis |
947d15f7 | 100 | one more time with flag set to |
ae59e04c | 101 | .Dv UNVIS_END |
947d15f7 | 102 | to extract any remaining character (the character passed in is ignored). |
ae59e04c | 103 | .Pp |
947d15f7 | 104 | The following code fragment illustrates a proper use of |
ae59e04c CL |
105 | .Fn unvis . |
106 | .Bd -literal -offset indent | |
947d15f7 MT |
107 | int state = 0; |
108 | char out; | |
56df4199 MT |
109 | |
110 | while ((ch = getchar()) != EOF) { | |
111 | again: | |
947d15f7 MT |
112 | switch(unvis(&out, ch, &state, 0)) { |
113 | case 0: | |
114 | case UNVIS_NOCHAR: | |
56df4199 | 115 | break; |
947d15f7 MT |
116 | case UNVIS_VALID: |
117 | (void) putchar(out); | |
56df4199 | 118 | break; |
947d15f7 MT |
119 | case UNVIS_VALIDPUSH: |
120 | (void) putchar(out); | |
56df4199 | 121 | goto again; |
947d15f7 | 122 | case UNVIS_SYNBAD: |
56df4199 | 123 | (void)fprintf(stderr, "bad sequence!\n"); |
ae59e04c | 124 | exit(1); |
56df4199 MT |
125 | } |
126 | } | |
947d15f7 MT |
127 | if (unvis(&out, (char)0, &state, UNVIS_END) == UNVIS_VALID) |
128 | (void) putchar(out); | |
ae59e04c CL |
129 | .Ed |
130 | .Sh SEE ALSO | |
131 | .Xr vis 1 | |
132 | .Sh HISTORY | |
133 | The | |
134 | .Fn unvis | |
135 | function is | |
136 | .Ud . |