 |
Index for
Section 4 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
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
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 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
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.
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
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 operations 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 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
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_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
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 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
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 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
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 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
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 sysset_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 sysset_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;
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
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 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
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 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
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
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
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 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
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 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
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
*/
};
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
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 indicates 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. 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
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:
[ENOENT] The file does not exist, or its corresponding process has
terminated 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
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.
[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).
|
Index for
Section 4 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|