1 .TH 9P-CMDBUF 3
2 .SH NAME
3 Cmdbuf, parsecmd, respondcmderror, lookupcmd \- control message parsing
4 .SH SYNOPSIS
5 .ft L
6 .nf
7 #include <u.h>
8 #include <libc.h>
9 #include <fcall.h>
10 #include <thread.h>
11 #include <9p.h>
12 .fi
13 .PP
14 .ft L
15 .nf
16 .ta \w'\fL1234'u +\w'\fL12345678'u
17 typedef struct Cmdbuf
18 {
19 	char	*buf;
20 	char	**f;
21 	int	nf;
22 } Cmdbuf;
23 
24 typedef struct Cmdtab
25 {
26 	int	index;
27 	char	*cmd;
28 	int	narg;
29 };
30 
31 Cmdbuf	*parsecmd(char *p, int n)
32 Cmdtab	*lookupcmd(Cmdbuf *cb, Cmdtab *tab, int ntab)
33 void	respondcmderror(Req *r, Cmdbuf *cb, char *fmt, ...)
34 .fi
35 .SH DESCRIPTION
36 These data structures and functions provide parsing of textual control messages.
37 .PP
38 .I Parsecmd
39 treats the
40 .I n
41 bytes at
42 .I p
43 (which need not be NUL-terminated) as a UTF string and splits it
44 using
45 .I tokenize
46 (see
47 .MR getfields (3) ).
48 It returns a
49 .B Cmdbuf
50 structure holding pointers to each field in the message.
51 .PP
52 .I Lookupcmd
53 walks through the array
54 .IR ctab ,
55 which has
56 .I ntab
57 entries,
58 looking for the first
59 .B Cmdtab
60 that matches the parsed command.
61 (If the parsed command is empty,
62 .I lookupcmd
63 returns nil immediately.)
64 A
65 .B Cmdtab
66 matches the command if
67 .I cmd
68 is equal to
69 .IB cb -> f [0]
70 or if
71 .I cmd
72 is 
73 .LR * .
74 Once a matching
75 .B Cmdtab
76 has been found, if
77 .I narg
78 is not zero, then the parsed command
79 must have exactly
80 .I narg
81 fields (including the command string itself).
82 If the command has the wrong number of arguments,
83 .I lookupcmd
84 returns nil.
85 Otherwise, it returns a pointer to the
86 .B Cmdtab
87 entry.
88 If
89 .I lookupcmd
90 does not find a matching command at all,
91 it returns nil.
92 Whenever
93 .I lookupcmd
94 returns nil, it sets the system error string.
95 .PP
96 .I Respondcmderror
97 resoponds to request
98 .I r
99 with an error of the form
100 `\fIfmt\fB:\fI cmd\fR,'
101 where
102 .I fmt
103 is the formatted string and
104 .I cmd
105 is a reconstruction of the parsed command.
106 Fmt
107 is often simply
108 .B "%r" .
109 .SH EXAMPLES
110 This interface is not used in any distributed 9P servers.
111 It was lifted from the Plan 9 kernel.
112 Almost any Plan 9 kernel driver
113 .RB ( /sys/src/9/*/dev*.c
114 on Plan 9)
115 is a good example.
116 .SH SOURCE
117 .B \*9/src/lib9p/parse.c
118 .SH SEE ALSO
119 .MR 9p (3)