sys/man/9/kproc

   1 .TH KPROC 9
   2 .SH NAME
   3 kproc, pexit, postnote \- kernel process creation, termination and interruption
   4 .SH SYNOPSIS
   5 .ta \w'\fLvoid 'u
   6 .B
   7 void    kproc(char *name, void (*func)(void*), void *arg)
   8 .PP
   9 .B
  10 void    pexit(char *note, int freemem)
  11 .PP
  12 .B
  13 int     postnote(Proc *p, int dolock, char *n, int flag)
  14 .SH DESCRIPTION
  15 .I Kproc
  16 creates a new kernel process
  17 to run the function
  18 .IR func ,
  19 which is invoked as
  20 .BR "(*func)(arg)" .
  21 The string
  22 .I name
  23 is copied into the
  24 .B text
  25 field of the
  26 .B Proc
  27 structure of the new process; this value is the name of the kproc in
  28 the output of
  29 .IR ps (1).
  30 The process is made runnable; it
  31 will run when selected by the scheduler
  32 .IR sched (9).
  33 The process is created with base and current priorities set to
  34 .BR PriKproc .
  35 It shares the kernel process group and thus name space.
  36 .PP
  37 A kernel process terminates only when it calls
  38 .IR pexit ,
  39 thereby terminating itself.
  40 There is no mechanism for one process to force the termination of another,
  41 although it can send a software interrupt using
  42 .IR postnote .
  43 .I Note
  44 is a null string on normal termination, or
  45 the cause of
  46 If
  47 .I freemem
  48 is non-zero,
  49 any memory allocated by the process is discarded;
  50 it should normally be non-zero for any process created
  51 by
  52 .IR kproc .
  53 Use the following to terminate a kernel process normally:
  54 .IP
  55 .EX
  56 pexit("", 1);
  57 .EE
  58 .PP
  59 .I Postnote
  60 sends a software interrupt to process
  61 .IR p ,
  62 causing it, if necessary, to wake from
  63 .IR sleep (9)
  64 or break out of a
  65 .IR rendezvous (2)
  66 or an
  67 .IR eqlock(9),
  68 with an
  69 .IR error (9)
  70 `interrupted'.
  71 Up to
  72 .B NNOTE
  73 notes can be pending at once (currently 5);
  74 if more than that arrive, the process is forced
  75 out of
  76 .IR sleep ,
  77 .I rendezvous
  78 and
  79 .IR eqlock ,
  80 but the message itself is discarded.
  81 .I Postnote
  82 returns non-zero iff the note has been
  83 delivered successfully.
  84 If
  85 .I dolock
  86 is non-zero,
  87 .I postnote
  88 synchronises delivery of the note with the debugger
  89 and other operations of
  90 .IR proc (3).
  91 .I Flag
  92 is zero, or one of the following
  93 .TP
  94 .B NDebug
  95 Print the note message on the user's standard error.
  96 Furthermore, suspend the process in a
  97 .B Broken
  98 state, preserving its memory, for later debugging.
  99 .TP
 100 .B NExit
 101 Deliver the note quietly.
 102 .TP
 103 .B NUser
 104 The note comes from another process, not the system.
 105 .PP
 106 The kernel uses
 107 .I postnote
 108 to signal processes that commit grave faults,
 109 and to implement the note and kill functions of
 110 .IR proc (3).
 111 A device driver should use
 112 .I postnote
 113 only to tell a service process,
 114 previously started by the driver using
 115 .I kproc ,
 116 that it should stop;
 117 the note will cause that process to raise an
 118 .IR error (9).
 119 For example, a process started to read packets from a network device could
 120 be stopped as follows when the interface is unbound:
 121 .IP
 122 .EX
 123 postnote(readp, 1, "unbind", 0);
 124 .EE
 125 .PP
 126 where
 127 .I readp
 128 points to the appropriate
 129 .BR Proc .
 130 The text of the message is typically irrelevant.
 131 .SH SOURCE
 132 .B /sys/src/9/port/proc.c