proc man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

PROC(3)								       PROC(3)

       proc - running processes

       bind #p /proc

       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

       The files regs, fpregs, and kregs hold  representations	of  the	 user-
       level  registers,  floating-point  registers,  and  kernel registers in
       machine-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

       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
       inaccessible 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‐

       -      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‐

       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
       information 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

       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
		 exits.	  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

       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.

		 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

       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

       sporadic	 Use sporadic  scheduling  for	the  real-time	process.   The
		 description  of  the  admit  command  below  contains further

		 Make the  real-time  process  yield  on  blocking  I/O.   The
		 description  of  the  admit  command  below  contains further

       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.


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


                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net