glenda.party
term% ls -F
term% cat index.txt
PROC(3)                    Library Functions Manual                    PROC(3)



NAME
       proc - running processes

SYNOPSIS
       bind #p /proc
       /proc/trace
       /proc/n/args
       /proc/n/ctl
       /proc/n/fd
       /proc/n/fpregs
       /proc/n/kregs
       /proc/n/mem
       /proc/n/note
       /proc/n/noteid
       /proc/n/notepg
       /proc/n/ns
       /proc/n/proc
       /proc/n/profile
       /proc/n/regs
       /proc/n/segment
       /proc/n/status
       /proc/n/text
       /proc/n/wait
       ...

DESCRIPTION
       The  proc  device  serves  a  two-level directory structure.  The first
       level contains the trace file (see below) and numbered directories cor‐
       responding  to  pids  of live processes; each such directory contains a
       set of files representing the corresponding process.

       The mem file contains the current memory image of the process.  A  read
       or  write  at offset o, which must be a valid virtual address, accesses
       bytes from address o up to the end of the memory segment containing  o.
       Kernel  virtual  memory, including the kernel stack for the process and
       saved user registers (whose addresses are  machine-dependent),  can  be
       accessed  through  mem.  Writes are permitted only while the process is
       in the Stopped state and only to user addresses or registers.

       The read-only proc file contains the kernel per-process structure.  Its
       main  use is to recover the kernel stack and program counter for kernel
       debugging.

       The files regs, fpregs, and kregs hold  representations  of  the  user-
       level  registers, floating-point registers, and kernel registers in ma‐
       chine-dependent form.  The kregs file is read-only.

       The read-only fd file lists the open file descriptors of  the  process.
       The  first  line of the file is its current directory; subsequent lines
       list, one per line, the open files, giving the decimal file  descriptor
       number;  whether  the  file  is  open for read (r), write, (w), or both
       (rw); the type, device number, and qid of the file; its I/O  unit  (the
       amount  of  data  that  may  be transferred on the file as a contiguous
       piece; see iounit(2)), its I/O offset; and its name at the time it  was
       opened.

       The  read-only  ns  file  contains  a  textual  representation  of  the
       process's file name space, in the format of  namespace(6)  accepted  by
       newns  (see auth(2)).  The last line of the file identifies the current
       working directory of the process, in the form  of  a  cd  command  (see
       rc(1)).   The  information in this file is based on the names files had
       when the name space was assembled, so the names it contains may be  in‐
       accessible if the files have been subsequently renamed or rearranged.

       The  read-only  segment  file  contains a textual display of the memory
       segments attached to the process.  Each line has multiple  fields:  the
       type  of  segment (Stack, Text, Data, Bss, etc.); one-letter flags such
       as R for read-only, if any; starting virtual address,  in  hexadecimal;
       ending virtual address, and reference count.

       The  read-only  status  file contains a string with twelve fields, each
       followed by a space.  The fields are:

       -      the process name and user name, each 27 characters  left  justi‐
              fied

       -      the process state, 11 characters left justified (see ps(1))

       -      the   six  11-character  numbers  also  held  in  the  process's
              #c/cputime file

       -      the amount of memory used by the process, except its  stack,  in
              units of 1024 bytes

       -      the base and current scheduling priority, each 11 character num‐
              bers

       The read-only args file contains the arguments of the program  when  it
       was  created  by exec(2).  If the program was not created by exec, such
       as by fork(2), its args file will be empty.  The format of the file  is
       a list of quoted strings suitable for tokenize; see getfields(2).

       The  text  file  is a pseudonym for the file from which the process was
       executed; its main use is to recover the symbol table of the process.

       The wait file may be read to recover records from the exiting  children
       of  the  process  in the format of await (see wait(2)).  If the process
       has no extant children, living or exited, a read of  wait  will  block.
       If  the  file's length is non-zero (see stat(2)), there is at least one
       wait record to read.  It is an error for a process to attempt  to  read
       its  own wait file when it has no children.  When a process's wait file
       is being read, the process will draw an error if it attempts  an  await
       system  call;  similarly,  if a process is in an await system call, its
       wait file cannot be read by any process.

       The read-only profile file contains the instruction frequency count in‐
       formation  used  for multiprocess profiling; see tprof in prof(1).  The
       information is gleaned by sampling  the  program's  user-level  program
       counter at interrupt time.

       Strings  written  to  the  note  file  will  be posted as a note to the
       process (see notify(2)).  The note should be less than ERRLEN-1 charac‐
       ters long; the last character is reserved for a terminating NUL charac‐
       ter.  A read of at least ERRLEN characters  will  retrieve  the  oldest
       note  posted  to  the  process and prevent its delivery to the process.
       The notepg file is similar, but the note will be delivered to  all  the
       processes  in  the target process's note group (see fork(2)).  However,
       if the process doing the write is in the group, it will not receive the
       note.  The notepg file is write-only.

       The  textual  noteid file may be read to recover an integer identifying
       the note group of the process (see RFNOTEG in fork(2)).  The  file  may
       be  written  to cause the process to change to another note group, pro‐
       vided the group exists and is owned by the same user.

       The file /proc/trace can be opened once and read to  see  trace  events
       from  processes  that  have  had  the string trace written to their ctl
       file.  Each event produces, in native machine format, the pid, a  type,
       and a time stamp (see /sys/include/trace.h and /sys/src/cmd/trace.c).

   Control messages
       Textual  messages  written to the ctl file control the execution of the
       process.  Some require that the process is in a  particular  state  and
       return an error if it is not.

       stop      Suspend  execution  of the process, putting it in the Stopped
                 state.

       start     Resume execution of a Stopped process.

       waitstop  Do not affect the process directly but, like all  other  mes‐
                 sages  ending  with  stop,  block the process writing the ctl
                 file until the target process is in the Stopped state or  ex‐
                 its.   Also  like  other stop control messages, if the target
                 process would receive a note while the message is pending, it
                 is instead stopped and the debugging process is resumed.

       startstop Allow a Stopped process to resume, and then do a waitstop ac‐
                 tion.

       hang      Set a bit in the  process  so  that,  when  it  completes  an
                 exec(2)  system  call, it will enter the Stopped state before
                 returning to user mode.  This bit is inherited across fork(2)
                 and exec(2).

       close n   Close file descriptor n in the process.

       closefiles
                 Close all open file descriptors in the process.

       nohang    Clear the hang bit.

       noswap    Don't  allow  this process to be swapped out.  This should be
                 used carefully and sparingly or the system could run  out  of
                 memory.   It  is  meant  for processes that can't be swapped,
                 like the ones implementing the swap device and for  processes
                 containing sensitive data.

       kill      Kill  the  process  the  next time it crosses the user/kernel
                 boundary.

       private   Make it impossible to read the process's user  memory.   This
                 property is inherited on fork, cleared on exec(2), and is not
                 otherwise resettable.

       pri n     Set the base priority for the process to the integer n.

       wired n   Wire the process to processor n.

       trace     Without an argument, toggle trace event generation  for  this
                 process  into /proc/trace (see below).  With a zero argument,
                 tracing for the proc is turned off, with a  non-zero  numeric
                 argument, it is turned on.

       period nu Set  the  real-time  scheduling  period of the process to nu,
                 where n is an optionally signed number containing an optional
                 decimal  point  and u is one of s, ms, us, µs, ns, or empty.
                 The time is interpreted, respectively, as seconds,  millisec‐
                 onds,  microseconds,  microseconds,  nanoseconds,  or, in the
                 case of an absent units specifier, as  nanoseconds.   If  the
                 time  specifier  is signed, it is interpreted as an increment
                 or decrement from a previously set value.  See also the admit
                 command below.

       deadline nu
                 Set  the  real-time  deadline  interval of the process to nu,
                 where n and u are interpreted as for period above.

       cost nu   Set the real-time cost (maximum CPU time per period)  of  the
                 process  to  nu,  where n and u are interpreted as for period
                 above.

       sporadic  Use sporadic scheduling for the real-time process.   The  de‐
                 scription  of  the  admit  command below contains further de‐
                 tails.

       yieldonblock
                 Make the real-time process yield on blocking  I/O.   The  de‐
                 scription  of  the  admit  command below contains further de‐
                 tails.

       admit     Given real-time period, deadline and cost are set  (an  unset
                 deadline will set deadline to period), perform a schedulabil‐
                 ity test and start scheduling  the  process  as  a  real-time
                 process  if  the test succeeds.  If the test fails, the write
                 will fail with error set to the reason for failure.

       event     Add a user event to the /proc/trace file.

   Real-time scheduling
       Real-time processes are periodically released,  giving  them  a  higher
       priority  than  non-real-time  processes  until they either give up the
       processor voluntarily, they exhaust their CPU allocation, or they reach
       their  deadline.   The  moment of release is dictated by the period and
       whether the process is sporadic or  not.   Non-sporadic  processes  are
       called  periodic  and they are released precisely at intervals of their
       period (but periods can be skipped if the process blocks on I/O).  Spo‐
       radic processes are released whenever they become runnable (after being
       blocked by sleep() or I/O), but always at least an interval  of  period
       after the previous release.

       The  deadline  of  a  real-time process specifies that the process must
       complete within the first deadline seconds of its period.  The  dealine
       must  be  less than or equal to the period.  If it is not specified, it
       is set to the period.

       The cost of a real-time process describes  the  maximum  CPU  time  the
       process may use per period.

       A  real-time process can give up the CPU before its deadline is reached
       or its allocation is exhausted.  It does this by calling sleep(0).   If
       yieldonblock  is  specified,  it also does it by executing any blocking
       system call.  Yieldonblock is assumed for sporadic processes.

       Of the released processes, the one with the earliest deadline  has  the
       highest  priority.  Care should be taken using spin locks (see lock(2))
       because a real-time process spinning on a lock will  not  give  up  the
       processor until its CPU allocation is exhausted; this is unlikely to be
       the desired behavior.

       When a real-time process reaches its deadline or exhausts its CPU allo‐
       cation, it remains schedulable, but at a very low priority.

       The  priority  is interpreted by Plan 9's multilevel process scheduler.
       Priorities run from 0 to 19, with higher  numbers  representing  higher
       priorities.  A process has a base priority and a running priority which
       is less than or equal to the base priority.  As a process uses up  more
       of its allocated time, its priority is lowered.  Unless explicitly set,
       user processes have base priority 10, kernel  processes  13.   Children
       inherit the parent's base priority.

FILES
       /sys/src/9/*/mem.h
       /sys/src/9/*/dat.h
       /sys/include/trace.h

SEE ALSO
       trace(1), debugger(2), mach(2), cons(3)

SOURCE
       /sys/src/9/port/devproc.c



                                                                       PROC(3)