9pcmdbuf 2.0 KB

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