unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



proc(4)								      proc(4)



NAME

  proc - Process file system

SYNOPSIS

  /proc

DESCRIPTION

  The /proc file system	enables	running	processes to be	accessed as files by
  the system calls open, close,	read, write, lseek, poll/select, and ioctl.
  While	the /proc file system is most useful for debuggers, the	/proc file
  system enables any process with the correct permissions to control another
  running process.  Thus, a parent/child relationship does not have to exist
  between a debugger and the process that is being debugged.

  For each active or zombie process, there is an entry in the system process
  table, which appears as a file name in the /proc directory.  The file	name
  is the decimal representation	of the process id.  File names are padded
  with leading zeros (0) so that each file name	is a minimum of	5 decimal
  digits.  For example,	if a process has a process id of 123, its file name
  would	be specified as	00123.	You do not have	to specify the leading zeros
  when specifying the file name.  For example, specifying ls -l	/proc/123 is
  acceptable.

  The only files that appear to	exist in the /proc directory correspond	to
  valid	(active	or zombie) processes in	the system proc	table.	Other than
  creating or terminating a process, you cannot	create or remove files in the
  /proc	directory.  The	permissions for	a file in the /proc directory are
  0600,	which indicates	read and write permissions for the owner only.	The
  uid and gid for a file in the	/proc directory	are the	uid and	gid of the
  user who is running the process.

  Setting Up the /proc Filesystem


  The /proc file system	is layered beneath the Virtual File System (VFS).  It
  is a pseudo-file system that occupies	no actual disk space.  The /proc
  pseudo-file system appears to	contain	files (which are actually running
  processes).  You can use the mount and umount	commands to manually mount
  and dismount the file	system,	or you can define an entry for the /proc file
  system in your /etc/fstab file.

  To mount the /proc file system using the mount command, enter	the follow-
  ing:

       mount -t	procfs /proc /proc

  To dismount the file system, use the umount command as follows:

       umount /proc

  You can add the following entry to your /etc/fstab file to let the /proc
  file system be mounted automatically at startup:

       /proc /proc procfs rw 0 0


  Security Considerations


  All auditing requirements for	the /proc file system are handled at the Vir-
  tual File System (VFS).  root	or the superuser can open all processes	using
  the /proc file system.  A nonprivileged user can open	an active process
  only if the following	conditions are met:

    +  Both the	uid and	gid of the user	match those of the running process.

    +  The user	has read permission for	the executable file from which the
       active process was created.

    +  The executable file from	which the active process was created must not
       have setuid or setgid permission	unless the user	has root or SEC_DEBUG
       privilege established or	is the owner (for setuid) or a group member
       (for setgid).

  If a debugging process opens an active process and the active	process	calls
  exec(2) to start another image that has suid or sgid permissions, or if the
  debugging process does not have read permission for the image	that the
  active process invokes, the debugging	process	is denied access to the	pro-
  cess information for the new image with the exception	of a close operation.
  This is also true for	root or	users with superuser privileges.

  Manipulating Processes: System Calls and ioctls


  Files	are manipulated	using the open,	close, read write, poll/select,	and
  ioctl	system calls.  Once a process has been opened, its user	virtual
  address space	can be examined	or written using the lseek system call fol-
  lowed	by the read or write system calls.  Likewise, as long as a process is
  opened for both read and write, the ioctl system calls can be	used to	con-
  trol,	trace, or get status for a process that	has been opened.  The close
  system call should be	used when interaction with a process is	complete.

				     Note

       Any number of opens for read and	write are allowed; however, to
       prevent confusion, if several processes are trying to control
       another process,	an exclusive open for write can	be requested.
       An open for write that includes the O_EXCL specifier only
       succeeds	if the process is not already open for a write.	 An open
       for write that does not specify O_EXCL always succeeds for root
       or an otherwise privileged user.	 There can be any number of
       read-only opens,	even when an exclusive write open is in	effect
       on the file.


  When a file is closed, any tracing flags that	were set are left on, unless
  the Run on Last Close	(RLC) flag was set by an ioctl call.  If RLC is	set,
  and the last writable	file descriptor	pertaining to the process is closed,
  all tracing flags are	cleared	and the	process	is set to run (if it was
  stopped).  Breakpoints are not affected by RLC because breakpoints are
  written into the text	area of	a running process by a debugger; the debugger
  is therefore always responsible for replacing	the original instructions.

  Information and control operations are provided through ioctl.  The opera-
  tions	have the form:

  #include <&lt;sys/types.h>&gt;
  #include <&lt;sys/signal.h>&gt;
  #include <&lt;sys/fault.h>&gt;
  #include <&lt;sys/syscall.h>&gt;
  #include <&lt;sys/procfs.h>&gt;
  ioctl(fd, COMMAND, p);

  The p	argument is a generic pointer whose use	depends	on a specific ioctl
  code.	 Where not mentioned in	the description	of the ioctl calls, the	value
  should be zero.  <&lt;sys/procfs.h>&gt; contains definitions of ioctl	codes and
  data structures used by the operations.  Certain operations can be per-
  formed only if the process file is open for writing; these include all
  operations that affect process control.

  Process and control operations involve the use of a set of flags.  The set
  types	sigset_t, fltset_t, and	sysset_t are masks.  The values	used to	set
  these	masks correspond respectively to the signal, fault, and	system call
  numbers defined in <&lt;sys/signal.h>&gt;, <&lt;sys/fault.h>&gt;, and	<&lt;sys/syscall.h>&gt;.
  Each set type	is large enough	to hold	the masks bits for all legal values
  of the related action.  Although they	are of different sizes,	they have a
  common structure and can be manipulated by the following macros:

  prfillset(&&amp;set);		  /*  turns on all flags
				   * in	set */
  premptyset(&&amp;set);		  /* turns off all flags
				   * in	set */
  praddset(&&amp;set,flag);		  /* turns on a	specified
				   * flag */
  prdelset(&&amp;set,flag);		  /* turns off a specified
				   * flag */
  r = prismember(&&amp;set,flag);	  /* returns true if flag
				   * is	on */

  Either prfillset or premptyset must be used to initialize set	before it is
  used in any operation.  The argument flag must be a member of	the enumera-
  tion corresponding to	the set.

  Ioctl	Codes


  The ioctl codes are divided into eight groups: process requests, signal
  interaction, fault trap interaction, system call interaction,	traced pro-
  cess control,	general	registers, miscellaneous mapping control, and Tru64
  UNIX specific	requests.  The following subsections describe these ioctl
  codes.

  Process Requests


  The following	ioctls specify process requests:

  PIOCSTATUS
  Returns status information for the process.  The argument p points to	the
  prstatus structure containing	following members:


      long pr_flags;	  /* specifies process flags */
      short pr_why;	  /* reason process is stopped */
      long pr_what;	  /* specifies detailed	reasons	*/
      struct siginfo pr_info;	  /* data related to signal
				   * or	fault */
      short pr_cursig;		  /* specifies current
				   * signal */
      sigset_t pr_sigpend;	  /* set of other pending
				   * signals */
      sigset_t pr_sighold;	  /* set of held signals */
      struct sigaltstack pr_altstack;	  /* alternate
					   * signal stack
					   * data */
      struct sigaction pr_action; /* signal action of
				   * current signal */
      pid_t pr_pid;	  /* specifies process id */
      pid_t pr_ppid;	  /* specifies parent process id */
      pid_t pr_pgrp;	  /* specifies group process id	*/
      pid_t pr_sid	  /* specifies session id */
      timestruc_t pr_utime;	  /* specifies process
				   * user cpu time */
      timestruc_t pr_stime;	  /* specifies process
				   * system cpu	time */
      timestruc_t pr_cutime;	  /* sum child processes
				   * user time */
      timestruc_t pr_cstime;	  /* sum child processes
				   * system time */
      char pr_clname[8];  /* scheduling	class name */
      gregset_t	pr_reg;	  /* specifies general registers */
      long pr_nthreads;	  /* number of threads */
      tid_t pr_tid;	 /* thread id output by
			  * PIOCSTATUS */


  The following	list describes each member of the structure pr_flags.

  The pr_flags bit-mask	has the	following flags:

    +  PR_STOPPED specifies that the process is	stopped.

    +  PR_ISTOP	specifies that the process stopped on an event of interest
       (see PIOCSTOP)

    +  PR_DSTOP	specifies that the process will	stop before entering user
       code (see PIOCSTOP).

    +  PR_ASLEEP specifies that	a process is in	an interruptible sleep within
       a system	call.

    +  PR_RLC specifies	that  a	process	has its	run-on-last-close flag set.

    +  PR_PTRACE specifies that	a process is being traced using	ptrace.

    +  PR_PCINVAL specifies that a process program counter refers to an
       invalid address.

    +  PR_ISSYS	specifies that a process is a system process (see the
       PIOCSTOP	ioctl).

  pr_why and pr_what

  The pr_why and pr_what fields	describe why a process is stopped and what
  stopped it.  The possible values for pr_why follow.  Included	in the
  description of the pr_why values is an explanation of	what pr_what holds.
  The pr_why values are:

    +  PR_REQUESTED indicates that PIOCSTOP was	specified, hence the process
       was stopped.  In	this instance, the pr_what field is not	used.

    +  PR_SIGNALLED indicates that a process stopped upon receiving a signal
       (see PIOCSTRACE).  The pr_what field holds the signal number that
       caused the stop.	 If this is a newly stopped process, the signal
       number is placed	in pr_cursig.

    +  PR_FAULTED specifies that a process stopped upon	encountering a fault
       (see PIOCSFAULT).  The pr_what field holds the number of	the fault
       that stopped the	process.

    +  PR_SYSENTRY and PR_SYSEXIT specify that a stop is to occur on an	entry
       to or an	exit from a system call	(see PIOCSENTRY	and PIOCSEXIT).	 The
       pr_what field holds the number of the system call, including the	habi-
       tat number, if any.

    +  PR_JOBCONTROL specifies that a process stopped because of the default
       action specified	by a job control stop signal (see sigaction).  The
       pr_what field holds the stopping	signal number.

    +  PR_DEAD specifies that a	process	has terminated.	 At this point,	the
       process and memory context are considered invalid.  The pr_what field
       holds the exist status of the process.  This function provides the
       debugger	with the ability to determine that the process being debugged
       has terminated, and to see its exit status.  ioctl.

  pr_info

  Contains additional information specific to a	signal or fault	when a pro-
  cess has been	stopped	by either PR_SIGNALLED or PR_FAULTED (see
  <&lt;sys/siginfo.h>&gt;).

  pr_cursig

  Identifies the number	of the next signal to be delivered to a	process.

  pr_sigpend

  Is a mask of pending signals that are	to be sent to a	process.

  pr_sighold

  Is a mask of those signals whose delivery will be delayed if sent to a pro-
  cess.	 Note that this	mask is	0 to (N-1), as opposed to pr_sigpend, which
  is 1 to N, where N is	the max	signal number.

  pr_altstack

  Provides alternate signal stack information for a process (see
  sigaltstack).

  pr_action

  Contains any signal action related to	the current signal (see	sigaction).
  The signal action is not defined if pr_cursig	is zero.

  pr_pid

  Contains the process identification number.

  pr_ppid

  Contains the process identification number of	the parent process.

  pr_pgrp

  Contains the group identification number of the process.

  pr_sid

  Contains the session identification number of	the process.

  pr_utime and pr_stmine


  Contain the user and system time (in seconds and nanoseconds)	used by	the
  process.

  pr_cutime and	pr_cstime


  Contain the cumulative user and system time (in seconds and nanoseconds)
  used by the process's	children.

  pr_clname

  Contains the name of the scheduling class that a process is using.

  pr_reg

  An array that	contains the contents of the general registers for the thread
  specified by pr_tid.	For a single-threaded process, this is the first
  thread.

  pr_nthreads

  Contains the number of threads currently in the process (task).

  pr_tid

  If the process is stopped on an event	of interest, pr_tid contains the
  thread ID of the thread that hit the process (task) trace event.  NOTE:  In
  a multithreaded task,	the PIOCSTOP ioctl sets	pr_tid to the thread ID	of
  the first thread and sets the	registers in pr_reg accordingly.

  PIOCSTOP and PIOCWSTOP

  The PIOCSTOP ioctl requires write access.  This ioctl	code requests that a
  process stop on an event of interest and remains in effect until the pro-
  cess does stop.  The PIOCWSTOP ioctl waits for a process to stop on an
  event	of interest.  For both ioctls, if the p	argument is of a nonzero
  value, it points to prstatus_t structure that	holds status information on a
  stopped process.

  If PIOCSTOP is specified with	a process that is stopped, but not stopped on
  an event of interest,	the stop directive only	takes affect when the process
  is restarted by the competing	mechanism, and before executing	any user
  level	code.

  An event of interest occurs when either a PR_REQUESTED stop has been speci-
  fied or when a stop has been specified in tracing flag of a process that
  can be set by	PIOCSTRACE, PIOCSFAULT,	PIOCSENTRY, or PIOCSEXIT. A
  PR_JOBCONTROL	flag is	not considered an event	of interest.

  A system process (indicated by the PR_ISSYS flag) never executes at user
  level, does not have a user level address space visible through /proc, and
  cannot be stopped.  Applying PIOCSTOP	or PIOCWSTOP to	a system process
  returns the error EBUSY.

  PIOCRUN

  Starts a traced process again	after it has been stopped.  This ioctl
  requires write access.  PIOCRUN fails	with an	EBUSY error if it is applied
  to a process that is not stopped on an event of interest, even when it is
  stopped due to a competing mechanism.	 The p argument	points to a prrun
  structure that provides additional directives	or actions that	can be per-
  formed:

  typedef struct prrun {
      long pr_flags;	  /* specifies process flags */
      sigset_t pr_trace;  /* specifies set of signals to
			   * trace */
      sigset_t pr_sighold;	  /* specifies set of
				   * signals to	hold */
      fltset_t pr_fault;  /* specifies set of faults to
			   * trace */
      caddr_t pr_vaddr;	  /* specifies virtual address
			   * at	which to resume	*/
      long pr_filler[8];  /* filler area for future
			   * expansion */
      tid_t pr_tid;	  /* Thread to resume for PIOCTRUN,
			   * ignored by	PIOCRUN	 */
  }  prrun_t;

  The fields in	the prrun structure are	only meaningful	if the appropriate
  flags	are set	in pr_flags bit-mask.  The pr_flags bit-mask has the follow-
  ing flags:

    +  PRCSIG specifies	that the current signal, if any, be cleared (see the
       PIOCSSIG	ioctl).

    +  PRCFAULT	specifies that the current fault, if any, be cleared (see the
       PIOCCFAULT ioctl).

    +  PRSTRACE	specifies that the traced signal set is	set to pr_trace	(see
       the PIOCSTRACE ioctl).

    +  PRSHOLD specifies that the held signal set is set to pr_sighold (see
       the PIOCSHOLD ioctl).

    +  PRSFAULT	specifies that the traced fault	set is set to pr_fault (see
       the PIOCSFAULT ioctl).

    +  PRSVADDR	specifies the address at which execution resumes to pr_vaddr.

    +  PRSTEP tells the	process	to run and execute a single machine instruc-
       tion.  When execution has completed, a hardware trace trap occurs.  If
       FLTTRACE	is being traced, the process stops on the fault, otherwise, a
       SIGTRAP is posted.  If SIGTRAP is being traced and not held, the	pro-
       cess stops on the signal.  This operation requires hardware and
       operating system	support	and might not be implemented on	all systems.

    +  PRSABORT	specifies that the process is to abort execution of current
       system call if the process is in	a PR_SYSENTRY stop or it is marked
       PR_ASLEEP (see PIOCSENTRY and PIOCEXIT).

    +  PRSTOP specifies	that a process stop again soon after it	has resumed
       execution (see PIOCSTOP).  Specifically,	when a process is stopped on
       PR_SIGNALLED or PR_FAULTED, the next stop displays PR_REQUESTED,	no
       other stop can intervene, and the process will not have executed	any
       user-level code.

  PIOCSRLC

  This ioctl sets the run-on-last-close	flag in	the traced process.  When the
  last writable	/proc file descriptor referring	to the traced process is
  closed, all of the process's tracing flags are cleared, any outstanding
  stop directive is canceled, and if the process is stopped, it	is set run-
  ning as though PIOCRUN had been applied to it.  This ioctl requires write
  access.  The flag run-on-last-close is off by	default.

  PIOCRRLC

  This ioctl turns the run-on-last-close flag off.  The	tracing	flags of a
  process are retained and the process is not restarted	when the process file
  is closed.  This ioctl requires write	access.

  PIOCNICE

  The traced process's nice(3) priority	is incremented by the amount con-
  tained in the	int addressed by the p argument.  Only the superuser can
  better the priority of a process in this manner, but any user	can make the
  priority worse.

  Signal Interaction


  The following	ioctls specify signal interaction.

  PIOCSTRACE

  This defines a set of	signals	to be traced and the receipt of	one of these
  signals causes the traced process to stop.  The set of signals is defined
  through the sigset_t structure that is pointed to by the argument p.
  Receipt of SIGKILL cannot be traced.	This ioctl requires write access.

  If a signal that is included in the held signal set is sent to the traced
  process, the signal is not received and does not cause a process stop	until
  it is	removed	from the held signal set, either by the	process	itself or by
  setting the held signal set with the PIOCSHOLD ioctl or using	the PRSHOLD
  option defined by the	PIOCRUN	ioctl.

  PIOCGTRACE

  The current traced signal set	is returned in an instance of sigset_t struc-
  ture pointed to by the p argument.

  PIOCSSIG

  The current signal and its associated	signal information are set according
  to the contents of the siginfo structure addressed by	p (see
  <sys/siginfo.h>).  If	the specified signal number is zero or if p is zero,
  the current signal is	cleared.  This ioctl requires write access.

  An error (EBUSY) is returned if the process is not stopped on	an event of
  interest.  The semantics of this ioctl are different from those of kill or
  PIOCKILL in that the signal is delivered to the process immediately after
  execution is resumed (even if	it is being held) and an additional
  PR_SIGNALLED stop does not intervene even if the signal is traced.  Setting
  the current signal to	SIGKILL	terminates the process immediately, even if
  it is	stopped.

  PIOCKILL

  A signal is sent to the process with semantics identical to those of
  kill(2); p points to an int naming the signal.  Sending SIGKILL terminates
  the process immediately.  This ioctl requires	write access.

  PIOCUNKILL

  A signal is deleted (removed from the	set of pending signals); the current
  signal, if any, is unaffected.  The p	argument points	to an int naming the
  signal.  It is an error to attempt to	delete SIGKILL.	The current signal is
  unaffected.  This ioctl requires write access.

  PIOCGHOLD

  This ioctl returns the set of	held signals (signals whose delivery is
  delayed if sent to the process) in an	instance of sigset_t addressed by the
  p argument.  Signal number 0 is always returned if not held.

  PIOCSHOLD

  This ioctl sets the held signal set.	SIGKILL	or stop	signals	can not	be
  held.	 If specified, they will be ignored silently.  It requires write
  access.  See PIOCGHOLD.  Signal number 0 cannot be held; it is ignored if
  specified.


  PIOCMAXSIG

  This ioctl, with the PIOCACTION ioctl, provides information about the	sig-
  nal actions associated with the traced process (see sigaction).  In the int
  returned by the p argument, this ioctl returns the  maximum signal number
  understood by	the system. This must be used to allocate storage for use
  with the PIOCACTION ioctl.

  PIOCACTION

  This ioctl, with the PIOMAXSIG ioctl,	provides information about the signal
  actions associated with the traced process.  This ioctl returns the traced
  process's signal actions in an array of sigaction structures addressed by
  the p	argument.  Signal numbers are displaced	by 1 from array	indices, so
  that the action for signal number n appears in position n-1 of the array.
  Note that PIOCMAXSIG should be called	before invoking	the PIOCACTION ioctl.

  See sigaction(2) for the definition of the sigaction structure.

  Fault	Trap Interaction


  The following	ioctls specify fault trap interaction.

  PIOCSFAULT

  This defines a set of	hardware faults	to be traced.  When incurring one of
  these	faults the traced process stops.  This ioctl requires write access.
  The set is defined via an instance of	fltset_t addressed by p.  Supported
  fault	names are defined in <sys/fault.h> and include the following.  Some
  of these may be identical on some processors;	some of	these may not occur
  on all processors; there may be processor-specific faults in addition	to
  the following:

    +  FTTILL specifies	an illegal instruction

    +  FLTPRIV specifies a privileged instruction

    +  FLTBPT specifies	a breakpoint trap

    +  FLTTRACE	specifies a trace trap

    +  FLTACCESS specifies a memory access fault

    +  FLTBOUNDS specifies a memory bounds violation

    +  FLTIOVF specifies an integer overflow

    +  FLTIZDIV	specifies  an integer zero divide

    +  FLTFPE specifies	a floating-point exception

    +  FLTSTACK	specifies an unrecoverable stack fault

    +  FLTPAGE specifies a recoverable page fault

    +  FLTALIGN	specifies an unaligned access fault

  When not traced, a fault normally results in the posting of a	signal to the
  process that incurred	the fault.  If the process stops on a fault, the
  signal is posted to the process when execution is resumed unless the fault
  is cleared by	PIOCCFAULT or by the PRCFAULT option of	PIOCRUN.  FLTPAGE and
  FLTALIGN are exceptions; no signal is	posted after FLTPAGE fault.  A signal
  may or may not be posted  after FLTALIGN depending on	operating system sup-
  port.	 There may be additional processor-specific faults like	this.  The
  pr_info structure member in the prstatus structure identifies	the signal to
  be sent and contains machine-specific	information about the fault.

  typedef struct {
	 unsigned long word[FLTSET_SZ];
  } fltset_t;

  PIOCGFAULT

  The current traced fault set is returned in the fltset_t structure that is
  pointed to by	the p argument.

  PIOCCFAULT

  The current fault (if	any) is	cleared; the associated	signal is not sent to
  the process.	This ioctl requires write access.

  System Call Interaction


  The following	ioctls specify system call interaction.

  PIOCSENTRY

  This ioctl instructs the process to stop on entry to the specified system
  calls.  The set of syscalls to be traced is defined in the sysset_t struc-
  ture addressed by the	p argument.  See the PIOCEXIT ioctl for	a description
  of the sysset_t structure.  This ioctl requires write	access.

  When an entry	to a system call is being traced, the traced process stops at
  beginning of the call	to the system.

  PIOCSEXIT

  This ioctl instructs the process to stop on exit from	the specified system
  calls.  The set of syscalls to be traced is defined in the sysset_t struc-
  ture addressed by the	p argument.  This ioctl	requires write access.

  When exit from a system call is being	traced,	the traced process stops on
  completion of	the system call	after return values are	stored into the
  traced process's saved registers.

  If the traced	process	is stopped on an entry to a system call	by
  PR_SYSENTRY, or if it	is in an interruptible system call with	PR_ASLEEP
  set, it may be instructed to go directly to system call exit by specifying
  the PRSABORT flag in a PIOCRUN request.  Unless exit from the	system call
  is being traced, the process returns to the user level with the EINTR
  error.

  typedef struct {
	  unsigned long	   word[SYSSET_SZ];
  } sysset_t;

				     Note

       An exec system call can fail after a new	image has been loaded
       partially, and the old memory context has been destroyed. When
       that happens, the traced	process	will exit without stopping on
       exit from the exec system call.

  PIOCGENTRY

  This ioctl returns the entry of the currently	traced system call in the
  sysset_t structure pointed to	by the p argument.

  PIOCGEXIT

  This ioctl returns the exit set of the currently traced system call in the
  sysset_t structure pointed to	by the p argument.

  Traced Process Control


  The following	ioctls specify traced process control.

  PIOCSFORK

  This ioctl sets the inherit-on-fork-flag in the traced process.  The trac-
  ing flag of a	process	are inherited by the child of a	fork(2)	or vfork(2).
  This ioctl requires write access.

  PIOCRFORK

  This ioctl turns the inherit-on-fork flag off.  Each child process starts
  with all tracing flags cleared.  This	ioctl requires write access.

  General Registers


  The following	ioctls are the general registers.

  PIOCGREG

  This ioctl retrieves the registers of	the saved process from the gregset_t
  structure that is pointed by the p argument.	The register contents are
  accessible using a set of predefined indices as described under the
  PIOCSTATUS ioctl.

  In a multithreaded process, if the task is not stopped on an event of
  interest (a trace event), the	registers are returned for the first thread.
  If the task is stopped on an event of	interest, the registers	for the
  thread that hit the event are	returned.  (See	the pr_tid field as returned
  by PIOCSTATUS.)

  The gregset_t	structure is described under the PIOCSREG ioctl.

  PIOCSREG

  This ioctl sets the registers	of the saved process in	the gregset_t struc-
  ture pointed to by the  argument.  It	requires write access.	The register
  contents are accessible using	a set of predefined indices as described
  under	the PIOCSTATUS ioctl.  This ioctl fails	with an	EBUSY error if
  applied to a process that is not stopped on an event of interest.

  struct gregset {
	  long regs[PRC_NREGS];
  }; typedef struct gregset gregset_t; PIOCGFPREG

  This ioctl retrieves the floating-point registers of a saved process from
  the fpregset_t structure pointed to by the p argument.  The EINVAL error is
  returned if floating-point hardware is not present on	the machine.

  The fpregset_t structure is displayed	under the PIOCSFPREG ioctl.  Note
  that this ioctl is architecture dependent.

  PIOCSFPREG

  This ioctl sets the floating-point registers of a saved process in a
  fpregset_t structure pointed to by the p argument. It	requires write
  access.  The EINVAL error is returned	if floating-point hardware is not
  present on the machine.  This	ioctl fails with an EBUSY error	if it is
  applied to a process that is not stopped on an event of interest.

  struct fpregset {
	  long regs[PRC_NREGS];
  };
  typedef struct fpregset fpregset_t;

  Note that this ioctl is architecture dependent.

				     Note

       The PIOCSREG, PIOCGFPREG, and PIOCSFPREG	ioctls can be used only
       if the task is stopped on an event of interest.	In a mul-
       tithreaded task,	the register set that is manipulated is	the set
       associated with the task	that hit the trace event.  (See	the
       pr_tid field as returned	by PIOCSTATUS.)	 If the	task stopped
       because of a PIOCSTOP ioctl, the	registers are those of the first
       thread.


  Miscellaneous	Requests


  The following	ioctls perform a variety of requests.

  PIOCPSINFO

  This ioctl returns miscellaneous information about a process similar to the
  information returned by the ps command.  The p argument is a pointer to a
  prpsinfo structure containing	at least the following fields:


      char pr_state:	  /* numeric process state
			   * (see pr_sname) */
      char pr_sname;	  /* printable char representing
			   * pr_state */
      char pr_zomb;	  /* !=0: process terminated
			   * but not waited for	*/
      char pr_nice;	  /* nice for cpu usage	*/
      u_long pr_flag;	  /* process flags */
      uid_t pr_uid;	  /* real user id */
      gid_t pr_gid;	  /* real group	id */
      pid_t pr_pid;	  /* unique process id */
      pid_t pr_ppid;	  /* process id	of parent*/
      pid_t pr_pgrp:	  /* process id	of process group
			   * leader */
      pid_t pr_sid;	  /* session id	*/
      long pr_size;	  /* size of process image in
			   * pages */
      long pr_rssize;	  /* resident set size in pages	*/
      caddr_t pr_wchan;	  /* wait addr for sleeping
			   * process */
      timestruc_t pr_start;	  /* process start time,
				   * sec+nsec since the
				   * epoch */
      timestruc_t pr_time;	  /* usr+sys time for
				   * this process */
      long pr_pri;	  /* priority, high value =
			   * high priority */
      char pr_oldpri;	  /* old style priority,
			   * low value is high
			   * priority */
      char pr_cpu;	   * cpu usage for scheduling */
      dev_t pr_ttydev;	  /* controlling tty device
			   * (PRNODEV if none) */
      char pr_clname[8];  / *Scheduling	class name */
      char pr_fname[16];  /* last component of exec'd
			   * pathname */
      char pr_psargs[PSARGS_SZ];   /* initial characters
				   * of	arg list */


  Some fields in the prpsinfo structure, such as the pr_state and the pr_flag
  fields, are system-specific and may not have the same	meaning	on each	ver-
  sion of the operating	system.

  PIOCPSINFO can be applied to a process that has become a zombie, but not
  all fields are filled	in.

  PIOCUSAGE

  This ioctl returns resource usage information	about a	process.  The p	argu-
  ment is a pointer to a prusage_t structure containing	at least the follow-
  ing fields:

	     timestruc_t pr_tstamp;    /* current time stamp */
	     timestruc_t pr_create;    /* process creation time	stamp */
	     timestruc_t pr_rtime;     /* total	real (elapsed) time */
	     timestruc_t pr_utime;     /* user CPU time	*/
	     timestruc_t pr_stime;     /* system CPU time */
	     timestruc_t pr_wtime;     /* wait-cpu (latency) time */
	     u_long	 pr_minf;      /* minor	page faults */
	     u_long	 pr_majf;      /* major	page faults */
	     u_long	 pr_nswap;     /* swaps	*/
	     u_long	 pr_inblk;     /* input	blocks */
	     u_long	 pr_oublk;     /* output blocks	*/
	     u_long	 pr_msnd;      /* messages sent	*/
	     u_long	 pr_mrcv;      /* messages received */
	     u_long	 pr_vctx;      /* voluntary context switches */
	     u_long	 pr_ictx;      /* involuntary context switches */
	     u_long	 pr_ioch;      /* chars	read and written */

  PIOCNMAP

  This operation, like the PIOCMAP ioctl, provides information about the
  memory mappings (virtual address ranges) associated with the traced pro-
  cess.	 In the	int returned by	the p argument,	this ioctl returns the number
  of mappings that are currently active.  This information can be used to
  allocate storage that	can be used with the PIOCMAP ioctl.  You must allo-
  cate space for p+1 mappings; see PIOCMAP.

  PIOCMAP

  This memory mapping operation	returns	the list of currently active map-
  pings.  For PIOCMAP, the p argument addresses	an array of elements of	type
  prmap_t; one array element (structure) is returned for each mapping with an
  additional all-zeroes	element	to mark	the end	of the list.  (See PIOCNMAP.)

  typedef struct prmap	{
      caddr_t pr_vaddr;	  /* Virtual address base */
      u_long pr_size;	  /* Size of mapping in	bytes */
      off_t pr_off;	  /* Offset into mapped	object,
			   * if	any */
      long pr_mflags;	  /* Protection	and attribute
			   * flags */
      long pr_filler[4];  /* Filler for	future expansion */
  }  prmap_t;

  The following	list describes structure members:

    +  The pr_vaddr contains the virtual address base (the lower limit)	of
       the mapping within the traced process and the pr_size field contains
       its size	in bytes.  The pr_off field specifies the offset within	the
       mapped object (if any) to which the address base	is mapped.

    +  The pr_mflags field is a	bit-mask of protection and attribute flags as
       follows:

       MA_READ specifies that mapping is readable by traced process

       MA_WRITE	specifies that mapping is writable by the traced process

       MA_EXEC specifies that mapping is executable by the traced process

				     Note

       The PIOCNMAP ioctl must be called immediately before the	PIOCMAP
       ioctl.

  PIOCOPENM

  If this ioctl	is called with a NULL value for	p, it returns a	read-only
  file descriptor to the disk file from	which the process was created.

  new_fd = ioctl(fd, PIOCOPENM,	NULL)

  PIOCCRED

  This operation obtains the set of credentials	associated with	the process.
  The p	argument points	to the prcred_t	structure where	the information	from
  this operation is placed.  The pr_ngroups value determines the size of the
  field	that the user must allocate and	pass to	the PIOCGROUPS ioctl.

  typedef struct prcred	{
      uid_t  pr_euid;	  /* contains effective	user id	*/
      uid_t  pr_ruid;	  /* contains real user	id */
      uid_t  pr_suid;	  /* contains saved user id
			   * (from exec) */
      uid_t  pr_egid;	  /* contains effective	group id */
      uid_t  pr_rgid;	  /* contains real group id */
      uid_t  pr_sgid;	  /* contains saved group id
			   * (from exec) */
      u_int  pr_ngroups;  /* number of supplementary groups */
  }  prcred_t;

  PIOCGROUPS

  Fetch	the set	of supplementary group IDs that	are associated with the	pro-
  cess.	 The p argument	points to an array of elements of type uid_t that are
  to be	filled by the operation.  Note that the	PIOCCRED ioctl must be
  applied beforehand to	determine the number of	groups (pr_ngroups) that are
  returned and the amount of storage that should be allocated to hold them.

  PIOCSSPCACT

  This ioctl is	referred to as "set special action" and	requires write
  access.  It is used to enable	or disable tracing of certain process control
  functions.  The p argument contains a	mask that consists of the following
  values (note that a zero value disables all tracing).	 The pr_why and
  pr_what values are the same as those described under the PIOCSTATUS ioctl.

       PRFS_STOPTCR sets a condition called stop-on-thread-create.  This will
       cause the task in which a new thread is created by a user level call
       to thread_create() to stop on an	event of interest before the new
       thread has executed any user level code.	 Setting this flag will	not
       cause a task stop when a	fork() system call creates a new thread.
       pr_why is set to	PR_TCRSTOP, and	pr_what	is set to the thread ID	of
       the newly created thread.  The PIOCRUN ioctl should be used to restart
       the task.

       PRFS_STOPTTERM sets a condition called stop-on-thread-terminate.	 This
       will cause a task stop whenever any of its threads enters the kernel
       thread_terminate() routine because of a user level call to
       thread_terminate().  pr_why is set to PR_TTSTOP,	and pr_what is set to
       the thread ID of	the terminating	thread.	 The PIOCRUN ioctl should be
       used to restart the task.  (The last thread of an exiting process does
       not cause a task	stop if	stop-on-thread-terminate is set.

       PRFS_KOLC sets the kill-on-last-close flag in the traced	process.
       This flag is off	by default.  If	the flag is set, the traced process
       is terminated by	a SIGKILL signal when the last /proc file descriptor
       referring to the	traced process is closed.  This	action occurs even if
       the traced process is stopped on	a trace	event.	All further tracing
       is disabled.  If	set, PRFS_KOLC overrides the run-on-last-close flag;
       see the description of the PIOCSRLC ioctl.

  PIOCGSPCACT

  This ioctl is	referred to as "get special actions".  It is used to return,
  in the address pointed to by the p argument, the latest mask value that was
  set by the PIOCSSPCACT ioctl.	 User code can invoke this ioctl to get	the
  current mask setting.	 It can	then OR	in bits	to be set, and/or AND out
  bits to be cleared; the PIOCSSPCACT can then be called with the modified
  mask to affect the desired change in tracing.

  PIOCNTHR, PIOCTLIST

  These	ioctls are used	to list	the thread IDs of all the threads in a task.
  PIOCNTHR must	be called first; it lets the user know how large a buffer it
  must pass to the PIOCTLIST ioctl, and	tells the kernel code the max number
  of thread IDs	to return via the PIOCTLIST ioctl.  If PIOCNTHR	is not
  invoked first, PIOCTLIST returns error EINVAL.  PIOCNTHR takes a pointer to
  an int, and PIOCTLIST	expects	a pointer to an	array of tid_t (pointers to
  struct thread).  Note	that if	the task is not	stopped, the actual number of
  threads in the task may change in the	time between the invocation of
  PIOCNTHR and PIOCTLIST.  The actual list of threads returned by PIOCTLIST
  will be less than or equal to	the value returned by PIOCNTHR.	 To get
  around this, the task	could be stopped (by PIOCSTOP for example) before
  PIOCNTHR is invoked, and restarted by	PIOCRUN	after PIOCTLISL	has com-
  pleted.

  Usage:

  ioctl(fd, PIOCNTHR, p) where p is (int *p)
  ioctl(fd, PIOCTLIST, p) where	p is (tid_t p)

  PIOCVTOP

  This ioctl takes a user virtual address for a	given PID and returns the
  associated physical address and RAD id if the	page is	both in	the user map
  and is resident.

	 */
	struct prvtop {
	      caddr_t pr_vaddr;		      /* user virtual address */
	      caddr_t pr_paddr;		      /* physical address */
	      int     pr_radid;		      /* RAD id	where pr_vaddr resides */
	      int     pad1;
	      long    pad2[5];
	};

	typedef	struct prvtop prvtop_t;

  The following	program	fragment shows the use of this ioctl:


       int
       main(int	argc, char *argv[])
       {
	       prvtop_t	radinfo;
	       char fname[80];
	       caddr_t vaddr;
	       int i;
	       int fd;

	       if (argc	!= 3) {
		       fprintf(stderr, "Usage: %s pid vaddr0, argv[0]);
		       exit(1);
	       }
	sprintf(fname, "/proc/%s", argv[1]);
	       sscanf(argv[2], "%lx", &vaddr);
	       printf("fname=%s	vaddr=%p0, fname, vaddr);
	       fd = open(fname,	O_RDONLY);
	       if (fd == -1) {
		       perror("open");
		       return 1;
	       }
	       radinfo.pr_vaddr	= vaddr;
	       radinfo.pr_radid	= -1;
	       radinfo.pr_paddr	= NULL;
	       if (ioctl(fd, PIOCVTOP, &radinfo) < 0) {
		       perror("ioctl(PIOCVTOP)");
		       exit(1);
	       }
	       printf("0x%016lx	(physaddr = 0x%016lx) is in RAD	%d0,
		      radinfo.pr_vaddr,	radinfo.pr_paddr, radinfo.pr_radid);
       }


  Thread-Specific ioctls

  In a multithreaded program, user code	must be	able to	identify which thread
  or threads to	examine	or manipulate.	Each user process is composed of a
  task,	which contains one or more threads;  For each thread in	a task,	a
  thread ID is returned	to the user via	/proc ioctls.  This ID is also passed
  to the kernel	by user	ioctls to identify which thread	in a task to manipu-
  late.

  With the exception of	PIOCTLIST, the thread specific ioctls (PIOCTxxx) can
  operate on one or more threads.  These ioctls	are invoked in the context of
  a process, just like the "base" ioctls.  For example,	if process 123 is
  opened via /proc - fd=open("/proc/123", O_RDWR), then
  ioctl(fd, PIOCTSTATUS, p) could be used to return status for 1 or more of
  its threads.

  However, unlike the "base" ioctls, which take	the address of a fixed length
  entity for parameter p, the PIOCTxxx ioctls use p to specify the address of
  a buffer that	varies in length, depending on the number of threads that are
  to be	operated on.  Also, the	PIOCTxxx ioctls	always require a valid p
  parameter - because, the p parameter contains	the number of threads to
  operate on, and their	IDs (even if the number	is 1).

  The structure, struct	prthreads, which is defined in <&lt;sys/procfs.h>&gt;, is
  used as a common "header" for	each of	the PIOCTxxx ioctls.


       struct prthreads	{
	   long	 pr_count;	   /* number of	threads	to operate on
				    * written by user, read by kernel
				    */
	   tid_t pr_error_thread;  /* if error,	the ID of the thread
				    * causing the error	is written here
				    * by the kernel
				    */
	   char	 pr_data[1];	   /* this is a	place holder, its
				    * address is used as the start of
				    * the list of ioctl	specific data
				    * structures
				    */
       };

				     Note

       If a thread-specific ioctl() call returns error status, the ID of
       the thread on which the error was detected is returned in
       pr_error_thread.	 When the kernel code detects an error,	ioctl
       processing stops.  This means that the ioctl actions succeeded
       for each	thread in the specified	list that proceeded the	thread
       for which the error was reported.  No ioctl action is attempted
       for any remaining threads in the	list after an error is detected.
       If a failure is encountered that	is not related to a specific
       thread the pr_error_thread value	will be	returned as 0.

  If a specified thread	is not found in	the task->thread_list, error EBADF is
  returned.  This is common to all of the PIOCTxxx ioctls.

PIOCTSTOP, PIOCTSTATUS

  PIOCTSTOP stops the specified	thread(s) and returns status in	the specified
  prstatus structure(s); PIOCTSTATUS just returns status.  The PIOCTSTOP
  ioctl	requires write access.

  These	ioctls use the same status structure, prstatus,	that is	used by	the
  "base" PIOCSTOP and PIOCSTATUS ioctls.

  Unlike PIOCSTOP, a prstatus structure	must always be specified for
  PIOCTSTOP.  A	thread is selected by filling in the pr_tid field of the
  prstatus structure.  (See the	comment	for the	thread_1 entry below.)

  Usage:

  ioctl(fd, PIOCTSTOP, p)
  ioctl(fd, PIOCTSTATUS, p)

  The buffer pointed to	by p for both these ioctls is as follows:

       long pr_count;	       /* number of threads in list
				*/
       tid_t pr_error_thread;  /* thread ID if error
				*/
       struct prstatus thread_1; /* "selected" thread is in
				  * thread_1.pr_tid
				  */
       .
       .
       .
       struct prstatus thread_N; /* thread_N.pr_tid contains ID	of last
				  *  thread to stop (PIOCTSTOP)	or return
				  *  status for	(PIOCTSTATUS)
				  */


  PIOCTRUN

  This ioctl is	used to	run one	or more	threads	that are stopped via
  PIOCTSTOP.  This ioctl provides the same functionality for the specified
  thread(s) as the "base" PIOCRUN ioctl	provides for the process/task, except
  that the PRCSIG, PRCFAULT and	PRSHOLD	flags of prrun.pr_flags	are not
  recognized.  This ioctl requires write access.

  Unlike PIOCRUN, a prrun structure must always	be specified for PIOCTRUN.  A
  thread is selected by	filling	in the pr_tid field of the prrun structure.
  The PIOCTRUN ioctl does provide the same functionality as the	PIOCRUN	ioctl
  with a NULL p	pointer	if the prrun.pr_flags field is set to 0.

  If a specified thread	is not stopped via PIOCTSTOP, error EBUSY  is
  returned.  If	any error is detected while attempting to run a	thread,	the
  ioctl	code returns; any threads in the list before the error will have been
  started, any threads in the list after the thread in error will not have
  been started.

  Note that in Tru64 UNIX running on an	Alpha system, the PIOCRUN and PIOC-
  TRUN ioctl commands, when used with the PRSTEP flag, can cause the traced
  program to execute an	indefinite number of instructions if the current
  instruction is a branch instruction.

  Usage:

  ioctl(fd, PIOCTRUN, p)

  The buffer pointed to	by p has the following format:

       long pr_count;	       /* number of threads to run
				*/
       tid_t pr_error_thread;  /* set by kernel	if error is detected
				*/
       struct prrun thread_1;  /* prrun	struct,	containing thread ID of
				* 1st thread to	run in thread_1.pr_tid
				*/
       .
       .
       .
       struct prrun thread_N;  /* prrun.pr_tid contains	ID of last
				* thread to run	in thread_N.pr_tid
				*/

  PIOCTSSIG

  This ioctl allows the	"current signal" to be cleared or changed to some
  other	signal,	only if	the specified thread(s)	is stopped on an event of
  interest.  This ioctl	requires write access.

  Usage:

  ioctl(fd, PIOCTSSIG, p)

  The buffer pointed to	by p has the following format:

       long pr_count;	       /* number of threads specified
				*/
       tid_t pr_error_thread;  /* thread ID if error
				*/
       tsiginfo_t thread_1;    /* first	thread to act on
				*/



       tsiginfo_t thread_N;    /* last thread to act on
				*/

  tsiginfo_t is	defined	in <&lt;sys/procfs.h>&gt; and has the following	format:

       typedef struct tsiginfo {
	       siginfo_t pr_siginfo;   /* the actual siginfo structure
					*/
	       tid_t pr_tid;	       /* the thread ID	to act upon
					*/
       } tsiginfo_t;		       /* note,	this is	not a pointer
					*/

  PIOCTKILL

  This ioctl allows a signal to	be sent	to a specified thread.	Multiple
  threads can be specified, and	a different signal can be sent to each speci-
  fied thread. Sending SIGKILL kill a thread immediately.  This	ioctl
  requires write access.

  Usage:

  ioctl(fd, PIOCTKILL, p)

  The buffer pointed to	by p has the following format:

       long pr_count;	       /* number of threads specified
				*/
       tid_t pr_error_thread;  /* thread ID if error
				*/
       tsignal_t thread_1;     /* first	thread to act on
				*/



       tsignal_t thread_N;     /* last thread to act on
	*/

  tsignal_t is defined in <&lt;sys/procfs.h>&gt; and has the following format:

       typedef struct tsignal {
	       int pr_signal;	       /* the signal to	send
					*/
	       tid_t pr_tid;	       /* the thread ID	to act upon
					*/
       } tsignal_t;		       /* note,	this is	not a pointer
					*/

  PIOCTUNKILL

  This ioctl allows a thread-specific signal that is pending for a specified
  thread to be deleted from the	list of	pending	signals.  Multiple threads
  can be specified, and	a different signal can be removed from each specified
  thread. The current signals for those	specified threads are unaffected.
  This ioctl requires write access.

  Usage:

  ioctl(fd, PIOCTUNKILL, p)

  The buffer pointed to	by p has the following format:

       long pr_count;	       /* number of threads specified
				*/
       tid_t pr_error_thread;  /* thread ID if error
				*/
       tsignal_t thread_1;     /* first	thread to act on
				*/



       tsignal_t thread_N;     /* last thread to act on
				*/

  tsignal_t is defined in <&lt;sys/procfs.h>&gt; and has the following format:

       typedef struct tsignal {
	       int pr_signal;	       /* the signal to	remove
					*/
	       tid_t pr_tid;	       /* the thread ID	to act upon
					*/
       } tsignal_t;		       /* note,	this is	not a pointer
					*/

  PIOCTUSAGE

  This ioctl returns resource usage information	about a	specific thread	in a
  process.  The	p argument is a	pointer	to a prusage_t structure as described
  in PIOCUSAGE.	Additionally, the following field must be filled in with the
  desired thread ID (from PIOCTLIST) before calling:

	     tid_t	 tid;	       /* Thread ID to get info	on */

  PIOCTGFPREG, PIOCTSFPREG*

  These	ioctls are used	to get and set the Floating Point registers for	the
  specified thread(s); they perform the	same type of functions as the "base"
  ioctls PIOCGFPREG and	PIOCSFPREG.  The PIOCTSFPREG* ioctl requires write
  access.

  For PIOCTGFPREG, if the FP hardware had not been in use (pcb_ownedfp is
  NULL)	all NULLs are returned.	 If a specified	thread is not stopped on an
  event	of interest, error EBUSY is returned.

  For PIOCTSFPREG, if a	specified thread is not	stopped	on an event of
  interest, error EBUSY	is returned.  No check is made to see if the FP
  hardware had been in use.

  Usage:

  ioctl(fd, PIOCTGFPREG, p)
  ioctl(fd, PIOCTSFPREG, p)

  The buffer pointed to	by p has the following format:

       long pr_count;	       /* number of threads specified
				*/
       tid_t pr_error_thread;  /* thread ID if error
				*/
       tfpregset_t thread_1;   /* first	thread to act on
				*/



       tfpregset_t thread_N;   /* last thread to act on
				*/

  tfpregset_t is defined in <&lt;sys/procfs.h>&gt; and has the following format:

       struct tfpregset	{
	       fpregset_t pr_fpregs;   /* floating point registers
					*/
	       tid_t pr_tid;	       /* the thread ID	to act upon
					*/
       };
       typedef struct tfpregset	tfpregset_t;




  PIOCTGREG, PIOCTSREG

  These	ioctls are used	to get and set the general registers for the speci-
  fied thread(s); they perform the same	type of	functions as the "base"
  ioctls PIOCGREG and PIOCSREG.	 The PIOCTSREG ioctl requires write access.

  For PIOCTSREG, if a specified	thread is not stopped on an event of
  interest, error EBUSY	is returned.

  Usage:

  ioctl(fd, PIOCTGREG, p)
  ioctl(fd, PIOCTSREG, p)

  The buffer pointed to	by p has the following format:

       long pr_count;	       /* number of threads specified
				*/
       tid_t pr_error_thread;  /* thread ID if error
				*/
       tgregset_t thread_1;    /* first	thread to act on
				*/



       tgregset_t thread_N;    /* last thread to act on
				*/

  tgregset_t is	defined	in <&lt;sys/procfs.h>&gt; and has the following	format:

       struct tgregset {
	       gregset_t pr_regs;      /* general registers
					*/
	       tid_t pr_tid;	       /* the thread ID	to act upon
					*/
       };
       typedef struct tgregset tgregset_t;

  PIOCTGRAD

  This ioctl returns per-thread	NUMA and processor scheduling locality infor-
  mation for a specified process.

	typedef	struct tradid {
	     int      pr_radid;	    /* Home RAD	for thread */
	     int      pr_rad_bound; /* Thread bound to RAD? */
	     int      pr_cpuid;	    /* CPU thread last ran on */
	     int      pr_cpu_bound; /* Thread bound to CPU? */
	     long     pad[5];	    /* Reserved	for future use */
	     tid_t    pr_tid;	    /* Thread ID */
	} tradid_t;

  The following	program	fragment shows an implementation of this ioctl:

       int
       main(int	argc, char *argv[])
       {
	       prthreads_t *hdr;
	       pid_t pid;
	       tid_t *tidlist;
	       int nthreads;
	       char fname[80];
	       int i;
	       int fd;
	       int status = 0;
	       tradid_t	*radp;

	       if (argc	!= 2) {
		       fprintf(stderr, "Usage: %s pid0,	argv[0]);
		       exit(1);
	       }

  NOTICES


  To wait for one or more processes to stop, /proc file	descriptors can	be
  used in a poll(2) system call. POLLPRI event is used to specify waiting for
  a process or one of its thread to stop on an event of	interest.  When
  requested and	returned, the polling event POLLPRI indicates that the	pro-
  cess or one of its thread has	stopped	on an event of interest. The polling
  events POLLHUP, POLLERR and POLLNVAL may be returned as well.	POLLHUP	indi-
  cates	that the process has terminated. POLLERR indicates that	the file
  descriptor has become	invalid.  POLLNVAL is returned immediately if POLLPRI
  is requested on a file descriptor referring to a system process. select(2)
  system call can be used in a similar way. When used in a select(2) system
  call,	the exceptfds parameter	(see select(2))	is used	to specify which file
  descriptors are to be	checked.  A positive indication	is returned if the
  process, corresponding to the	open file descriptor, has stopped on an	event
  of interest.

  If PIOCTSTOP is invoked for a	thread,	and the	thread is successfully
  stopped, the thread can be restarted only via	PIOCTRUN; PIOCRUN will have
  no effect on it. All other stops on events of	interest must restarted	via
  PIOCRUN.

  Descriptions of structures in	the document include only interesting struc-
  ture elements, and may show elements out of order for	descriptive clarity.
  The actual structure definitions are contained in <&lt;sys/procfs.h>&gt;.

ERRORS

  Errors that can be set in addition to	the errors normally associated with
  file system access:

  [ENOENT]  The	file does not exist, or	its corresponding process has ter-
	    minated after being	opened.

  [EBADF]   An I/O or ioctl operation requiring	write access was attempted on
	    a file descriptor not open for writing.

  [EBUSY]   PIOCRUN, PIOCTRUN, PIOCSREG, PIOCTSREG or PIOCSFPREG, PIOCTSFPREG
	    was	applied	to a process or	one of its threads not stopped on an
	    event of interest; an exclusive open(2) was	attempted on a pro-
	    cess file already open for writing;	an open(2) for writing was
	    attempted and an exclusive open is in effect on the	 process
	    file; an attempt was made to mount /proc file system when it is
	    already mounted.

  [EPERM]   The	calling	process	does not have appropriate privilege.

  [ENOSYS]  An attempt was made	to perform an unsupported operation by /proc
	    file system

  [EINVAL]  Invalid argument was supplied to a system call. A non-exhaustive
	    list of conditions can cause the error includes: an	ioctl
	    operation was issued on a file descriptor referring	to the /proc
	    directory; the  ioctl command is undefined.

  [EAGAIN]  The	operation failed because the traced process has	performed an
	    exec(2) of a setuid/setgid object file or of an object file	that
	    it cannot read; all	further	operations (except close(2)) on	the
	    file descriptor will fail with this	error.

  [EINTR]   A signal was received by the controlling process while waiting
	    for	the traced process to stop.

  [EFAULT]  An I/O or ioctl request referred to	an invalid address in the
	    controlling	process.

  [EIO]	    An I/O or ioctl request referred to	an invalid address in the
	    traced process.

FILES

  /proc	     Contains the directory listing of active processes

  /proc/nnnnn
	     Contains the process image

RELATED	INFORMATION

  Functions: intro(2), open(2),	close(2), ioctl(2), poll(2), read(2),
  write(2), sigaction(2), signal(2), siginfo(5).