1
0

plumber 2.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126
  1. .TH PLUMBER 4
  2. .SH NAME
  3. plumber \- file system for interprocess messaging
  4. .SH SYNOPSIS
  5. .B plumber
  6. [
  7. .B -p
  8. .I plumbing
  9. ]
  10. .SH DESCRIPTION
  11. The
  12. .I plumber
  13. is a user-level file server that receives, examines, rewrites, and dispatches
  14. .IR plumb (6)
  15. messages between programs.
  16. Its behavior is programmed by a
  17. .I plumbing
  18. file (default
  19. .BR /usr/$user/lib/plumbing )
  20. in the format of
  21. .IR plumb (6).
  22. .PP
  23. Its services are mounted on the directory
  24. .B /mnt/plumb
  25. .RB ( /mnt/term/mnt/plumb
  26. on the CPU server) and consist of two
  27. pre-defined files,
  28. .B send
  29. and
  30. .BR rules ,
  31. and a set of output
  32. .I ports
  33. for dispatching messages to applications.
  34. The service is also published as a
  35. .IR srv (4)
  36. file, named in
  37. .BR $plumbsrv ,
  38. for mounting elsewhere.
  39. .PP
  40. Programs use
  41. .B write
  42. (see
  43. .IR read (2))
  44. to deliver messages to the
  45. .B send
  46. file, and
  47. .IR read (2)
  48. to receive them from the corresponding port.
  49. For example,
  50. .IR sam (1)'s
  51. .B plumb
  52. menu item or the
  53. .B B
  54. command cause a message to be sent to
  55. .BR /mnt/plumb/send ;
  56. .B sam
  57. in turn reads from, by convention,
  58. .B /mnt/plumb/edit
  59. to receive messages about files to open.
  60. .PP
  61. A copy of each message is sent to each client that has the corresponding port open.
  62. If none has it open, and the rule has a
  63. .B plumb
  64. .B client
  65. or
  66. .B plumb
  67. .B start
  68. rule, that rule is applied.
  69. A
  70. .B plumb
  71. .B client
  72. rule causes the specified command to be run
  73. and the message to be held for delivery when the port is opened.
  74. A
  75. .B plumb
  76. .B start
  77. rule runs the command but discards the message.
  78. If neither
  79. .B start
  80. or
  81. .B client
  82. is specified and the port is not open,
  83. the message is discarded and a write error is returned to the sender.
  84. .PP
  85. The set of output ports is determined dynamically by the
  86. specification in the plumbing rules file: a port is created for each unique
  87. destination of a
  88. .B plumb
  89. .B to
  90. rule.
  91. .PP
  92. The set of rules currently active may be examined by reading the file
  93. .BR /mnt/plumb/rules ;
  94. appending to this file adds new rules to the set, while
  95. creating it (opening it with
  96. .BR OTRUNC )
  97. clears the rule set.
  98. Thus the rule set may be edited dynamically with a traditional text editor.
  99. However, ports are never deleted dynamically; if a new set of rules does not
  100. include a port that was defined in earlier rules, that port will still exist (although
  101. no new messages will be delivered there).
  102. .SH FILES
  103. .TF /usr/$user/lib/plumbing
  104. .TP
  105. .B /usr/$user/lib/plumbing
  106. default rules file
  107. .TP
  108. .B /sys/lib/plumb
  109. directory to search for files in
  110. .B include
  111. statements
  112. .TP
  113. .B /mnt/plumb
  114. mount point for
  115. .IR plumber (4).
  116. .SH SOURCE
  117. .B /sys/src/cmd/plumb
  118. .SH "SEE ALSO"
  119. .IR plumb (1),
  120. .IR plumb (2),
  121. .IR plumb (6)
  122. .SH BUGS
  123. .IR Plumber 's
  124. file name space is fixed, so it is difficult to plumb
  125. messages that involve files in newly mounted services.