sys/man/9/parsecmd

   1 .TH PARSECMD 9
   2 .SH NAME
   3 parsecmd, cmderror, lookupcmd
   4 \- parse device commands
   5 .SH SYNOPSIS
   6 .ta \w'\fLCmdbuf* 'u
   7 .B
   8 Cmdbuf* parsecmd(char *a, int n)
   9 .PP
  10 .B
  11 void            cmderror(Cmdbuf *cb, char *s)
  12 .PP
  13 .B
  14 Cmdtab*         lookupcmd(Cmdbuf *cb, Cmdtab *ctab, int nctab)
  15 .SH DESCRIPTION
  16 .I Parsecmd
  17 is an interface to
  18 .I tokenize
  19 (see
  20 .IR getfields (2)),
  21 that safely parses a command, with blank-separated fields, as might be
  22 written to a device's
  23 .B ctl
  24 file.
  25 The buffer
  26 .I a
  27 and count
  28 .I n
  29 can be those passed to the driver's
  30 .I write
  31 function.
  32 .I Parsecmd
  33 converts the byte array (which might not be null-terminated) to a null-terminated string,
  34 trimming any trailing new line,
  35 before invoking
  36 .I tokenize
  37 to break the string into arguments, interpreting blank and tab as field separators
  38 when they are not quoted
  39 (in the style of
  40 .IR rc (1)).
  41 It returns a pointer to a dynamically-allocated
  42 .B Cmdbuf
  43 structure,
  44 which holds a copy of the string and the resulting fields; it is
  45 defined as follows:
  46 .IP
  47 .EX
  48 .ta 6n +\w'char* 'u
  49 typedef
  50 struct Cmdbuf
  51 {
  52         char    *buf;
  53         char    **f;
  54         int     nf;
  55 } Cmdbuf;
  56 .EE
  57 .PP
  58 The array
  59 .B f
  60 holds the field pointers;
  61 .B nf
  62 gives the number of fields.
  63 .B Cmdbuf
  64 is allocated by
  65 .I smalloc
  66 (see
  67 .IR malloc (9)),
  68 and the caller is responsible for freeing it using
  69 .IR free .
  70 .I Cmderror
  71 prepends the given format with the original command,
  72 then calls
  73 .IR error (9).
  74 .PP
  75 Command strings may be turned into a (typically enumerated)
  76 integer with
  77 .IR lookupcmd .
  78 The catchall
  79 .L *
  80 matches any text.  Unrecognized commands, or commands
  81 given an unacceptable number of arguments generate a
  82 call to
  83 .IR error .
  84 The definition is as follows
  85 .IP
  86 .EX
  87 .ta 6n +\w'char* 'u
  88 typedef
  89 struct Cmdtab
  90 {
  91         int     index;  /* used by client to switch on result */
  92         char    *cmd;   /* command name */
  93         int     narg;   /* expected #args; 0 ==> variadic */
  94 } Cmdtab;
  95 .EE
  96 .PP
  97 The integer
  98 .B index
  99 is the number returned on command match.
 100 The string
 101 .B cmd
 102 is the command name, and
 103 .B narg
 104 is 0 (indicating a variadic function) or the
 105 number of arguments.
 106 .SH SOURCE
 107 .B /sys/src/9/port/parse.c