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