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