proc(4) Kernel Interfaces Manual 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 permis-
sions 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 mini-
mum 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 following:
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 Virtual File System (VFS). root or the superuser can open all pro-
cesses 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 permis-
sions, 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 process 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 followed 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 control, 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. 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 operations have the form:
#include <sys/types.h> #include <sys/signal.h> #include <sys/fault.h> #include <sys/syscall.h> #include <sys/procfs.h> 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. <sys/procfs.h> contains definitions of ioctl codes and data structures used by the operations. Certain opera-
tions can be performed 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 <sys/signal.h>, <sys/fault.h>, and
<sys/syscall.h>. 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(&set); /* turns on all flags
* in set */ premptyset(&set); /* turns off all flags
* in set */ praddset(&set,flag); /* turns on a specified
* flag */ prdelset(&set,flag); /* turns off a specified
* flag */ r = prismember(&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 enumeration 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 process 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 habitat 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 termi-
nated. 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 sta-
tus. ioctl.
pr_info
Contains additional information specific to a signal or fault when a process has been stopped by either PR_SIGNALLED or PR_FAULTED (see
<sys/siginfo.h>).
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 process. Note that this mask is 0 to (N-1), as opposed to pr_sig-
pend, 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 process 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 specified 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 performed:
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
following flags: PRCSIG specifies that the current signal, if any, be cleared (see the PIOCSSIG ioctl). PRCFAULT specifies that the cur-
rent fault, if any, be cleared (see the PIOCCFAULT ioctl). PRSTRACE specifies that the traced signal set is set to pr_trace (see the PIOC-
STRACE 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 instruction. 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
process 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 running 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 contained 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 structure 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 termi-
nates 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 signal 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 allo-
cate 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 pro-
cessor-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 excep-
tion 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 support. 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 sys-
set_t structure 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 sys-
set_t structure 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; 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 tracing 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 con-
tents 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 structure 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 EIN-
VAL 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. The PIOCSREG, PIOCGFPREG, and PIOCSFPREG ioctls can be used only if the task is stopped on
an event of interest. In a multithreaded 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[PRARGSIZ]; /* 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 version 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 argument is a pointer to a prusage_t structure containing at least
the following 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
process. 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 allocate space for p+1 mappings; see PIOCMAP.
PIOCMAP
This memory mapping operation returns the list of currently active mappings. 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 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 cre-
ated.
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 process. 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 trac-
ing.
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 completed.
Usage:
ioctl(fd, PIOCNTHR, p) where p is (int *p) ioctl(fd, PIOCTLIST, p) where p is (tid_t p)
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 com-
posed 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 manipulate.
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 <sys/procfs.h>, 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
*/ };
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 PIOCTRUN 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 <sys/procfs.h> 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
specified 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 <sys/procfs.h> 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 <sys/procfs.h> 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 <sys/procfs.h> 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 specified 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 <sys/procfs.h> 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;
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 indi-
cates that the process 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 indicates that the process has terminated. POLLERR indicates that the file descriptor has become invalid. POLL-
NVAL 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 structure elements, and may show elements out of order for descriptive
clarity. The actual structure definitions are contained in <sys/procfs.h>.
ERRORS
Errors that can be set in addition to the errors normally associated with file system access: The file does not exist, or its corresponding
process has terminated after being opened. An I/O or ioctl operation requiring write access was attempted on a file descriptor not open
for writing. 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 process 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. The calling process does not have appropriate privilege. An attempt was made to perform an unsupported operation by /proc file
system 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. 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. A signal was received by the controlling process while waiting for the traced
process to stop. An I/O or ioctl request referred to an invalid address in the controlling process. An I/O or ioctl request referred to
an invalid address in the traced process.
FILES
Contains the directory listing of active processes 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). delim off
proc(4)