logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

runtrap.8 (2700B)

    

  1. .\" runtrap.8
  2. .\" wcm, 2009.12.11 - 2011.02.01
  3. .\" ===
  4. .TH runtrap 8 "January 2013" "runtools-2.07" "runtools"
  5. .SH NAME
  6. runtrap \- run a program with a signal trapper
  7. .SH SYNOPSIS
  8. .B runtrap [\-hV]
  9. .I id trapper program
  10. .B [
  11. .I args ...
  12. .B ]
  13. .SH DESCRIPTION
  14. .B runtrap
  15. starts
  16. .I program
  17. with any
  18. .I args
  19. and monitors it as a long-running process.
  20. If
  21. .B runtrap
  22. notices that
  23. .I program
  24. terminates,
  25. it restarts it.
  26. .PP
  27. Whenever
  28. .B runtrap
  29. itself receives any signal it can catch,
  30. it invokes the argument given by
  31. .I trapper
  32. in this form:
  33. .PP
  34. .RS
  35. .BR trapper " ``" trap ''
  36. .I id pid signum signame
  37. .RE
  38. .PP
  39. Where:
  40. .PP
  41. .RS
  42. .B trapper
  43. .PP
  44. .RS
  45. The name of an executable specified in the
  46. .I trapper
  47. argument on the command-line.
  48. .RE
  49. .PP
  50. .RB `` trap ''
  51. .PP
  52. .RS
  53. The verbatim string ``trap''. 
  54. .RE
  55. .PP
  56. .I id
  57. .PP
  58. .RS
  59. A simple string specified in the
  60. .I id
  61. argument on the command-line.
  62. .RE
  63. .PP
  64. .I pid
  65. .PP
  66. .RS
  67. The process ID of the
  68. .I program
  69. that
  70. .B runtrap
  71. is monitoring.
  72. .RE
  73. .PP
  74. .I signum
  75. .PP
  76. .RS
  77. The numeric decimal representation of the signal
  78. received by
  79. .BR runtrap .
  80. .RE
  81. .PP
  82. .I signame
  83. .PP
  84. .RS
  85. The symbolic name for the signal received by
  86. .BR runtrap .
  87. .RE
  88. .RE
  89. .PP
  90. Presumably
  91. .I trapper
  92. is a short-running program
  93. designed to perform some special handling of signals destined for
  94. .IR program .
  95. After invoking
  96. .IR trapper ,
  97. .B runtrap
  98. waits for
  99. it to complete and then resumes monitoring
  100. .IR program .
  101. .PP
  102. If
  103. .B runtrap
  104. receives a SIGTERM,
  105. it flags itself to terminate.
  106. It then invokes
  107. .I trapper
  108. as above with SIGTERM arguments.
  109. When
  110. .I program
  111. terminates,
  112. .B runtrap
  113. itself then exits normally.
  114. .SH OPTIONS
  115. .TP
  116. .B \-h
  117. Help.
  118. Print a brief usage message to stderr and exit.
  119. .TP
  120. .B \-V
  121. Version.
  122. Print the version number to stderr and exit.
  123. .SH EXAMPLES
  124. .B runtrap
  125. is designed for use in
  126. .BR perpetrate (5)
  127. runscripts for services that need special signal handling.
  128. The example below shows how an
  129. .I rc.main
  130. runscript may be multiplexed to handle ``trap'' targets:
  131. .PP
  132. .RS
  133. .nf
  134. #!/bin/sh
  135. exec 2>&1
  137. TARGET=${1}
  138. SVNAME=${2}
  140. start() {
  141.   echo "starting ${SVNAME} ..."
  142.   exec runtrap ${SVNAME} ./rc.main /usr/sbin/foo -f
  143. }
  145. reset() {
  146.   echo "resetting ${SVNAME} ..."
  147.   #...
  148. }
  150. trap() {
  151.   SVPID=${3}
  152.   SIGNUM=${4}
  153.   SIGNAME=${5}
  154.   echo "trapping ${SVNAME} for signal ${SIGNAME} ..."
  155.   kill -${SIGNUM} ${SVPID}
  156. } 
  158. eval ${TARGET} "$@"
  160. ### EOF
  161. .fi
  162. .RE
  163. .SH AUTHOR
  164. Wayne Marshall, http://b0llix.net/perp/
  165. .SH SEE ALSO
  166. .nh
  167. .BR runtools_intro (8),
  168. .BR runargs (8),
  169. .BR runargv0 (8),
  170. .BR runchoom (8),
  171. .BR rundetach (8),
  172. .BR rundeux (8),
  173. .BR runenv (8),
  174. .BR runfile (8),
  175. .BR runlimit (8),
  176. .BR runlock (8),
  177. .BR runpause (8),
  178. .BR runsession (8),
  179. .BR runtool (8),
  180. .BR runuid (8),
  181. .BR perpd (8),
  182. .BR perpetrate (5)
  183. .\" EOF