1 .TH 9PCMDBUF 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 .IR tokenize (3).
46 It returns a
47 .B Cmdbuf
48 structure holding pointers to each field in the message.
49 .PP
50 .I Lookupcmd
51 walks through the array
52 .IR ctab ,
53 which has
54 .I ntab
55 entries,
56 looking for the first
57 .B Cmdtab
58 that matches the parsed command.
59 (If the parsed command is empty,
60 .I lookupcmd
61 returns nil immediately.)
62 A
63 .B Cmdtab
64 matches the command if
65 .I cmd
66 is equal to
67 .IB cb -> f [0]
68 or if
69 .I cmd
70 is 
71 .LR * .
72 Once a matching
73 .B Cmdtab
74 has been found, if
75 .I narg
76 is not zero, then the parsed command
77 must have exactly
78 .I narg
79 fields (including the command string itself).
80 If the command has the wrong number of arguments,
81 .I lookupcmd
82 returns nil.
83 Otherwise, it returns a pointer to the
84 .B Cmdtab
85 entry.
86 If
87 .I lookupcmd
88 does not find a matching command at all,
89 it returns nil.
90 Whenever
91 .I lookupcmd
92 returns nil, it sets the system error string.
93 .PP
94 .I Respondcmderror
95 resoponds to request
96 .I r
97 with an error of the form
98 `\fIfmt\fB:\fI cmd\fR,'
99 where
100 .I fmt
101 is the formatted string and
102 .I cmd
103 is a reconstruction of the parsed command.
104 Fmt
105 is often simply
106 .B "%r" .
107 .SH EXAMPLES
108 This interface is not used in any distributed 9P servers.
109 It was lifted from the Plan 9 kernel.
110 Almost any kernel driver
111 .RB ( /usr/local/plan9/src/9/*/dev*.c )
112 is a good example.
113 .SH SOURCE
114 .B /usr/local/plan9/src/lib9p/parse.c
115 .SH SEE ALSO
116 .IR 9p (3)