sys/man/2/9pcmdbuf

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