9pcmdbuf 2.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118
  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. .I tokenize
  44. (see
  45. .IR getfields (2)).
  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 ( /sys/src/9/*/dev*.c )
  112. is a good example.
  113. .SH SOURCE
  114. .B /sys/src/lib9p/parse.c
  115. .SH SEE ALSO
  116. .IR 9p (2)