proc(4)proc(4)NAMEproc - The process (/proc) file system and associated ioctl requests
SYNOPSIS
/proc
DESCRIPTION
The /proc file system is layered beneath the Virtual File System (VFS).
It is a pseudo-file system that occupies no disk space. The /proc
pseudo-file system appears to contain files, but these are actually
running processes.
The /proc file system enables running processes to be accessed as files
by the open(), close(), read(), write(), lseek(), poll()/select(), and
ioctl() system calls. This allows any process with the correct permis‐
sions to control another running process. The /proc file system is most
useful for debuggers because 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 appears as 00123. However, you do not have to
include 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 by 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 values for a file in the /proc directory
are the uid and gid values of the user who is running the process.
Setting Up the /proc File System
You can use the mount and umount commands to manually mount and unmount
the file system, or you can define an entry for the /proc file system
in the system's /etc/fstab file.
To mount the /proc file system by using the mount command, enter the
following:
mount -t procfs /proc /proc
Alternatively, you can add the following entry to the /etc/fstab file
to let the /proc file system be mounted automatically at startup: /proc
/proc procfs rw 0 0
To unmount the /proc file system, use the umount command as follows:
umount /proc
Security Considerations
All auditing requirements for the /proc file system are handled by the
Virtual File System (VFS). The root user, or superuser, can open all
processes by 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 one of the
following is true: The user who executed the file has root or SEC_DEBUG
privilege established. The user's UID or GID (for setuid() or setgid()
permission, respectively) matches that of the file.
If a debugging process opens an active process and the active process
uses an exec call 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 the root user
or users with superuser privileges.
Manipulating Processes: System Calls and ioctl Requests
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 by
using the lseek() system call, followed by the read() or write() system
call. Likewise, as long as a process is opened for both read and
write, the ioctl() operations 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 access can be requested. An open for write
access that includes the O_EXCL specifier only succeeds if the file is
not already open for write access. An open for write access that does
not specify O_EXCL always succeeds for the root or otherwise privileged
user. There can be any number of read-only opens, even when an exclu‐
sive open for write access 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 the
RLC flag because breakpoints are written into the text area of a run‐
ning process by a debugger; the debugger is therefore always responsi‐
ble for replacing the original instructions.
Information and control operations are provided through the ioctl()
system call. 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, request, p);
The p argument is a generic pointer whose use depends on the specified
ioctl request. When p is not mentioned in a request description, the
corresponding call argument should be zero. The <sys/procfs.h> header
file contains ioctl request definitions and the data structures used by
the requests. Certain requests, including all that affect process con‐
trol, can be performed on a process file only if it is open for writ‐
ing.
Process and control operations involve the use of a set of flags. The
sigset_t, fltset_t, and sysset_t set types are masks. The values used
to set these masks correspond respectively to the signal, fault, and
system call numbers that are 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 the flag is on */
Either prfillset() or premptyset() must be used to initialize set
before it is used in any operation. The flag argument must be a member
of the enumeration that corresponds to the set.
IOCTL REQUESTS
The process ioctl requests are divided into eight groups: process
information and control, signal interaction, fault trap interaction,
system call interaction, traced process control, general registers,
miscellaneous mapping control, and some requests specific to Tru64
UNIX. The following subsections describe the requests in these groups.
ioctl Requests for Process Information and Control
The following requests specify process requests:
PIOCSTATUS
Returns status information for the process. The p argument points to
the prstatus structure, key members of which are as follows:
long pr_flags; /* specifies process flags */ short pr_why; /* rea‐
son process is stopped */ long pr_what; /* specifies detailed rea‐
sons */ 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 flags can be included in the pr_flags bit-mask:
PR_STOPPED specifies that the process is stopped. PR_ISTOP specifies
that the process stopped on an event of interest. (See the description
of the PIOCSTOP request.) PR_DSTOP specifies that the process will
stop before entering user code. (See the description of the PIOCSTOP
request.) 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 by 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 description of the PIOCSTOP
request.)
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 a PIOCSTOP
request 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 the description of the
PIOCSTRACE request.) In this case, the pr_what field holds the signal
number that caused the process to stop. If this is a newly stopped
process, the signal number is placed in the pr_cursig field.
PR_FAULTED specifies that a process stopped upon encountering a fault.
(See the description of the PIOCSFAULT request.) In this case, 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 the descriptions of the PIOC‐
SENTRY and PIOCSEXIT requests.) In this case, 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 that was specified by a job control stop signal. (See sigac‐
tion()). In this case, the pr_what field holds the stopping signal's
number. PR_DEAD specifies that a process has terminated. At this
point, the process and memory context are considered invalid. In this
case, the pr_what field holds the exist status of the process. This
allows a debugger to determine that the process being debugged has ter‐
minated and to see its exit status. See also ioctl(2).
pr_info
The pr_info member of the prstatus structure is a structure that con‐
tains additional information specific to a signal or a fault when a
process is stopped with either PR_SIGNALLED or PR_FAULTED in the pr_why
field. See the <sys/siginfo.h> header file for details about the
pr_info structure.
pr_cursig
This field identifies the number of the next signal to be delivered to
a process.
pr_sigpend
This field is a mask of pending signals that are to be sent to a
process.
pr_sighold
This field 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 mask, which is 1 to N, where N is the maximum signal number.
pr_altstack
The field provides alternate signal stack information for a process.
(See sigaltstack(2).)
pr_action
The field contains any signal action related to the current signal.
(See sigaction(2).) The signal action is not returned if the pr_cursig
field is zero.
pr_pid
This field contains the process identification number.
pr_ppid
This field contains the process identification number of the parent
process.
pr_pgrp
This field contains the group identification number of the process.
pr_sid
This field contains the session identification number of the process.
pr_utime and pr_stmine
These fields contain the user and system time (in seconds and nanosec‐
onds) used by the process.
pr_cutime and pr_cstime
These fields contain the cumulative user and system time (in seconds
and nanoseconds) used by the child processes of the specified process.
pr_clname
This field contains the name of the scheduling class that the process
is using.
pr_reg
This array contains the contents of the general registers for the
thread specified by the pr_tid field. For a single-threaded process,
this is the first thread.
pr_nthreads
This field contains the number of threads currently in the process
(task).
pr_tid
If the process is stopped on an event of interest, the pr_tid field
contains the thread ID of the thread that encountered the process
(task) trace event. NOTE: In a multithreaded task, the PIOCSTOP
request sets pr_tid to the thread ID of the first thread and sets the
registers in the pr_reg field accordingly.
PIOCSTOP and PIOCWSTOP
The PIOCSTOP request requires write access to the process file. This
request specifies that a process stop on an event of interest and
remains in effect until the process does stop. The PIOCWSTOP request
waits for a process to stop on an event of interest. For both requests,
if the p argument is a nonzero value, it points to a prstatus_t struc‐
ture that holds status information on the stopped process.
If PIOCSTOP is specified for a process that is already stopped, but not
stopped on an event of interest, the stop directive takes affect only
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 was speci‐
fied in the pr_why field or a stop was specified in a tracing flag of a
process by the PIOCSTRACE, PIOCSFAULT, PIOCSENTRY, or PIOCSEXIT
request. 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
the /proc file system, and cannot be stopped. Applying PIOCSTOP or
PIOCWSTOP to a system process returns the error [EBUSY].
PIOCDUMPCORE
The PIOCDUMPCORE request generates a core snapshot of the traced
process, suitable for use with debuggers. This request does not kill or
otherwise perturb the process in any way, as would be the case when
sending it a signal. The process must be stopped (typically with PIOC‐
STOP or PIOCWSTOP). If the process is not stopped, [EBUSY] is returned.
Optionally, the caller can use setsysinfo(SSI_COREDIR) to specify a
directory in which to dump the core image. Otherwise, the core image is
dumped to the current directory of the caller.
To use the PIOCDUMPCORE request, the caller must have read permission
to the process being dumped and write permission to the directory in
which the core image is dumped.
PIOCRUN
The PIOCRUN request starts a traced process again after it has been
stopped. This request requires write access on the process file.
PIOCRUN fails with an [EBUSY] error if it is applied to a process that
is not stopped on an event of interest, even when the process 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 members of the prrun structure are only meaningful if the appropri‐
ate flags are set in the pr_flags field. The pr_flags bit-mask has the
following flags: PRCSIG specifies that the current signal, if any, be
cleared. (See the description of the PIOCSSIG request.) PRCFAULT spec‐
ifies that the current fault, if any, be cleared. (See the description
of the PIOCCFAULT request.) PRSTRACE specifies that the traced signal
set is set to the value of the pr_trace field. (See the description of
the PIOCSTRACE request.) PRSHOLD specifies that the held signal set is
set to the value of the pr_sighold. (See the description of the PIOCSH‐
OLD request.) PRSFAULT specifies that the traced fault set is set to
the value of the pr_fault field. (See the description of the PIOCS‐
FAULT request.) PRSVADDR specifies the address at which execution
resumes to the value of the pr_vaddr field. PRSTEP tells the process
to run and to 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.
The PRSTEP implementation requires hardware and operating system sup‐
port and might not be available on all systems. PRSABORT specifies
that the process is to abort execution of the current system call if
the process is in a PR_SYSENTRY stop or is marked by the PR_ASLEEP flag
in the pr_flags bitmask. (See the descriptions of the PIOCSENTRY and
PIOCEXIT requests.) PRSTOP specifies that a process stop again soon
after it has resumed execution. (See the description of the PIOCSTOP
request.) Specifically, when a process is stopped with PR_SIGNALLED or
PR_FAULTED in the pr_why field, the next stop displays PR_REQUESTED in
the pr_what field. In this case, no other stop can intervene, and the
process will not have executed any user-level code.
PIOCSRLC
The PIOCSRLC request sets the run-on-last-close flag in the traced
process. When the last writable /proc file descriptor that refers 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) the process is set running as though a PIOCRUN
request had been applied to it. The PIOCSRLC request requires write
access on the process file. The run-on-last-close flag is off by
default.
PIOCRRLC
The PIOCRRLC request sets the run-on-last-close flag to off. The trac‐
ing flags of a process are retained, and the process is not restarted
when the process file is closed. This request requires write access on
the process file.
PIOCNICE
The PIOCNICE request increments a traced process's nice priority by the
amount contained in the int value 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.
ioctl Requests for Signal Interaction
The following requests specify signal interaction:
PIOCSTRACE
The PIOCSTRACE request defines a set of signals to be traced. 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 p argument. Receipt of SIGKILL cannot be traced.
This request requires write access on the process file.
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 the
process to stop until the signal is removed from the held signal set.
The signal can be removed from the held set either by the process
itself, by setting the held signal set with the PIOCSHOLD request, or
by using the PRSHOLD option defined by the PIOCRUN request.
PIOCGTRACE
The PIOCGTRACE request returns the current traced signal set in an
instance of the sigset_t structure pointed to by the p argument.
PIOCSSIG
The PIOCSSIG request sets the current signal and its associated signal
information according to the contents of the siginfo structure
addressed by the p argument. (See the <sys/siginfo.h> file for the
structure definition.) If the specified signal number is zero or if
the p argument is zero, the current signal is cleared. This request
requires write access on the process file.
The [EBUSY] error is returned if the process is not stopped on an event
of interest. The semantics of this request are different from those of
the kill() function or the PIOCKILL request in that the signal is
delivered to the process immediately after execution is resumed (even
if the signal is being held). Furthermore, 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
The PIOCKILL request sends a signal to the process with semantics iden‐
tical to those of the kill() function. The p argument points to a buf‐
fer of type int that names the signal. Sending a SIGKILL signal termi‐
nates the process immediately. This request requires write access on
the process file.
PIOCUNKILL
The PIOCUNKILL request deletes a signal (removes it from the set of
pending signals). The current signal, if any, is unaffected. The p
argument points to a buffer of type int that names the signal. When
using this request, an attempt to delete the SIGKILL signal is an
error. The current signal is unaffected. This request requires write
access on the process file.
PIOCGHOLD
The PIOCGHOLD request returns the set of held signals (signals whose
delivery is delayed if sent to the process) in an instance of the
sigset_t type addressed by the p argument. Signal number 0 is always
returned if not held.
PIOCSHOLD
The PIOCSHOLD request sets the held signal set. The SIGKILL and stop
signals cannot be held. If specified, they are silently ignored. The
request requires write access on the process file. (See the descrip‐
tion of the PIOCGHOLD request.) Signal number 0 cannot be held; it is
ignored if specified.
PIOCMAXSIG
The PIOCMAXSIG request, along with the PIOCACTION request, provides
information about the signal actions associated with the traced
process. (See sigaction(2).) In the int value returned by the p argu‐
ment, this request retrieves the maximum signal number understood by
the system. This number must be obtained to allocate the storage used
with the PIOCACTION request.
PIOCACTION
The PIOCACTION request, along with the PIOMAXSIG request, provides
information about the signal actions associated with the traced
process. PIOCACTION returns the traced process's signal actions in an
array of sigaction structures addressed by the p argument. Signal num‐
bers are displaced by 1 from array indices, so that the action for sig‐
nal number n appears in position n-1 of the array. Note that the PIOC‐
MAXSIG request must be used prior to using the PIOCACTION request.
See sigaction(2) for the definition of the sigaction structure.
ioctl Requests for Fault Trap Interaction
The following requests specify fault trap interaction:
PIOCSFAULT
ThePIOCSFAULT request defines a set of hardware faults to be traced.
When incurring one of these faults, the traced process stops. This
request requires write access on the process file. The set of hardware
faults is defined by using an instance of type fltset_t addressed by
the p argument: typedef struct { unsigned long word[FLTSET_SZ]; } flt‐
set_t;
The following supported fault names are defined in the <sys/fault.h>
file: FTTILL specifies an illegal instruction FLTPRIV specifies a priv‐
ileged instruction FLTBPT specifies a breakpoint trap FLTTRACE speci‐
fies a trace trap FLTACCESS specifies a memory access fault FLTBOUNDS
specifies a memory bounds violation FLTIOVF specifies an integer over‐
flow 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
Some of these fault names may be identical on some processors and some
names may not occur on all processors. Furthermore, there may be pro‐
cessor-specific fault names that are not listed here.
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 the PIOCCFAULT request or by the PRCFAULT
option of the PIOCRUN request. The FLTPAGE and FLTALIGN faults are
exceptions. No signal is posted after a FLTPAGE fault. A signal may or
may not be posted after a FLTALIGN fault, depending on operating sys‐
tem support. There may be additional processor-specific faults that
behave in this way. The pr_info structure member in the prstatus
structure identifies the signal to be sent and contains machine-spe‐
cific information about the fault.
PIOCGFAULT
The PIOCGFAULT request returns the current traced fault set in the flt‐
set_t structure that is pointed to by the p argument.
PIOCCFAULT
The PIOCCFAULT request clears the current fault (if any), and the asso‐
ciated signal is not sent to the process. This request requires write
access to the process file.
ioctl Requests for System Call Interaction
The following requests specify system call interaction:
PIOCSENTRY
The PIOCSENTRY request instructs the process to stop on entry to the
specified system calls. The set of system calls to be traced is
defined in the sysset_t structure addressed by the p argument. (See
the description of the PIOCEXIT request for the format of the sysset_t
structure.) The PIOCSENTRY request requires write access to the
process file.
When an entry to a system call is being traced, the traced process
stops at beginning of the call to the system.
PIOCSEXIT
The PIOCSEXIT request instructs the process to stop on exit from the
specified system calls. The set of system calls to be traced is
defined in the sysset_t structure addressed by the p argument: typedef
struct {
unsigned long word[SYSSET_SZ]; } sysset_t;
This request requires write access to the process file.
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 (a
PR_SYSENTRY value in the pr_why field), or if the process is in an
interruptible system call (with PR_ASLEEP set), the process 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.
Note
An exec system call can fail after a new image has been loaded par‐
tially, and the old memory context has been destroyed. When that hap‐
pens, the traced process will exit without stopping on exit from the
exec system call.
PIOCGENTRY
The PIOCGENTRY request returns the entry of the currently traced system
call in the sysset_t structure pointed to by the p argument.
PIOCGEXIT
The PIOCGEXIT request returns the exit set of the currently traced sys‐
tem call in the sysset_t structure pointed to by the p argument.
ioctl Requests for Traced Process Control
The following requests specify traced process control:
PIOCSFORK
The PIOCSFORK request sets the inherit-on-fork-flag in the traced
process. The tracing flags of a process are inherited by the child of a
fork() or vfork() call. This request requires write access on the
process file.
PIOCRFORK
The PIOCRFORK request turns the inherit-on-fork flag off. Each child
process starts with all tracing flags cleared. This request requires
write access on the process file.
ioctl Requests for Retrieving and Setting General Registers
The following requests retrieve and set general registers:
PIOCGREG
The PIOCGREG request retrieves the registers of the saved process from
the gregset_t structure that is pointed to by the p argument. struct
gregset {
long regs[PRC_NREGS]; }; typedef struct gregset gregset_t;
The register contents are accessible using a set of predefined indices
as described in the description of the PIOCSTATUS request. Register
contents are set by using the PIOCSREG request.
In a multithreaded process, if the task is not stopped on an event of
interest (a trace event), the PIOCGREG request returns the registers
for the first thread. If the task is stopped on an event of interest,
the registers for the thread that encountered the event are returned.
(The pr_tid field that identifies the thread is returned by the PIOC‐
STATUS request and is discussed in the description for that request.)
PIOCSREG
The PIOCSREG request sets the registers of the saved process in the
gregset_t structure pointed to by the p argument. This request
requires write access to the process file. The register contents are
accessible using a set of predefined indices as discussed in the
description of the PIOCSTATUS request.
The PIOCSREG request fails with an [EBUSY] error if applied to a
process that is not stopped on an event of interest.
PIOCGFPREG
The PIOCGFPREG request retrieves the floating-point registers of a
saved process from the fpregset_t structure pointed to by the p argu‐
ment. The [EINVAL] error is returned if floating-point hardware is not
present on the machine.
The fpregset_t structure is shown in the description of the PIOCSFPREG
request, which is architecture dependent.
PIOCSFPREG
The PIOCSFPREG request sets the floating-point registers of a saved
process in a fpregset_t structure pointed to by the p argument. struct
fpregset {
long regs[PRC_NREGS]; }; typedef struct fpregset fpregset_t;
The PIOCSFPREG request, which is architecture dependent, requires write
access to the process file. This request returns [EINVAL] if floating-
point hardware is not present on the machine and [EBUSY] if applied to
a process that is not stopped on an event of interest.
Note
The PIOCSREG, PIOCGFPREG, and PIOCSFPREG requests 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 discussion of the pr_tid field
in the description of the PIOCSTATUS request.) If the task stopped
because of a PIOCSTOP request, the registers are those of the first
thread.
Miscellaneous ioctl Requests
The following requests perform a variety of operations.
PIOCPSINFO
The PIOCPSINFO request returns miscellaneous process information that
is similar to the information returned by the ps command. The p argu‐
ment is a pointer to a prpsinfo structure that contains the following
key members:
char pr_state: /* numeric process state
* (see pr_sname) */
char pr_sname; /* printable char representing
* pr_state */
char pr_zomb; /* !=0: process terminated
* but not waited for */
char pr_nice; /* nice for cpu usage */
u_long pr_flag; /* process flags */
uid_t pr_uid; /* real user id */
gid_t pr_gid; /* real group id */
pid_t pr_pid; /* unique process id */
pid_t pr_ppid; /* process id of parent*/
pid_t pr_pgrp: /* process id of process group
* leader */
pid_t pr_sid; /* session id */
long pr_size; /* size of process image in
* pages */
long pr_rssize; /* resident set size in pages */
caddr_t pr_wchan; /* wait addr for sleeping
* process */
timestruc_t pr_start; /* process start time,
* sec+nsec since the
* epoch */
timestruc_t pr_time; /* usr+sys time for
* this process */
long pr_pri; /* priority, high value =
* high priority */
char pr_oldpri; /* old style priority,
* low value is high
* priority */
char pr_cpu; * cpu usage for scheduling */
dev_t pr_ttydev; /* controlling tty device
* (PRNODEV if none) */
char pr_clname[8]; /* Scheduling class name */
char pr_fname[16]; /* last component of exec'd
* pathname */
char pr_psargs[PSARGS_SZ]; /* initial characters
* of arg list */
Some fields in the prpsinfo structure, such as the pr_state and the
pr_flag fields, are system specific and may not have the same meaning
on each version of the operating system.
The PIOCPSINFO request can be applied to a process that has become a
zombie; however, in this case, not all fields are filled in.
PIOCUSAGE
The PIOCUSAGE request returns resource usage information about a
process. The p argument is a pointer to a prusage_t structure contain‐
ing the following key members:
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
The PIOCNMAP request, like the PIOCMAP request, provides information
about the memory mappings (virtual address ranges) associated with the
traced process. The int value returned by the p argument is the number
of mappings that are currently active. This information can be then
used to allocate additional storage with the PIOCMAP request. In other
words, you use PIOCMAP to allocate space for p+1 mappings.
PIOCMAP
The PIOCMAP request 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-zeros element to mark the end of the list.
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 the members of the prmap structure: 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 the mapping is readable by the traced
process
MA_WRITE specifies that the mapping is writable by the traced
process
MA_EXEC specifies that the mapping is executable by the traced
process
Note
The PIOCNMAP request must be called immediately before the PIOCMAP
request.
PIOCOPENM
If the PIOCOPENM request 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
The PIOCCRED request 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 deter‐
mines the size of the field that the user must allocate and pass to the
PIOCGROUPS request.
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
The PIOCGROUPS request fetches 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 request must be applied beforehand to determine the
number of groups (pr_ngroups) that are to be returned and the amount of
storage that should be allocated to hold them.
PIOCSSPCACT
The PIOCSSPCACT request is the ``set special action'' request and
requires write access to the process file. This request is used to
enable or disable tracing of certain process control functions. The p
argument contains a mask that consists of one or more of the following
flags. (Note that a zero value disables all tracing.) The pr_why and
pr_what values referred to in the flag descriptions are the same as
those described in the description of the PIOCSTATUS request. Sets a
condition called stop-on-thread-create. This condition causes the task
in which a new thread is created by a user level call to thread_cre‐
ate() to stop on an event of interest before the new thread executes
any user level code. The pr_why field is set to PR_TCRSTOP, and the
pr_what field is set to the thread ID of the newly created thread. The
PIOCRUN request should be used to restart the task. (Note that setting
the PRFS_STOPTCR flag does not cause a task to stop when a fork() sys‐
tem call creates a new thread.) Sets a condition called stop-on-
thread-terminate. This will cause a task to stop when any of its
threads enters the kernel thread_terminate() routine because of a user
level call to thread_terminate(). The pr_why value is set to PR_TTSTOP,
and the pr_what value is set to the thread ID of the terminating
thread. The PIOCRUN request should be used to restart the task. (The
last thread of an exiting process does not cause a task to stop if
stop-on-thread-terminate is set. 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, the PRFS_KOLC flag overrides
the run-on-last-close flag. (See also the description of the PIOCSRLC
request.)
PIOCGSPCACT
The PIOCGSPCACT request is the “get special actions” request. It is
used to return, in the address pointed to by the p argument, the latest
mask value that was set by the PIOCSSPCACT request. Programs can use
PIOCGSPCACT to get the current mask setting. They can then OR in bits
to be set, AND out bits to be cleared, or both; the PIOCSSPCACT request
can then be called with the modified mask to affect the desired change
in tracing.
PIOCNTHR, PIOCTLIST
The PIOCNTHR and PIOCTLIST requests get a list of all the thread IDs in
a task. The PIOCNTHR request must be called first; it tells the program
how large a buffer must be passed to the PIOCTLIST request and tells
the kernel the maximum number of thread IDs to return through that
request. If the PIOCNTHR request is not called first, the PIOCTLIST
request returns the [EINVAL] error. The PIOCNTHR request includes the p
argument as a pointer to an int value, whereas the PIOCTLIST request
includes the p argument as a pointer to an array of tid_t values
(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 number of threads returned
by PIOCTLIST will always be less than or equal to the value returned by
PIOCNTHR. To work around this problem, the program can stop the task
(by using the PIOCSTOP request, for example) before invoking PIOCNTHR,
and then, after PIOCTLISL completes, restart the task with PIOCRUN.
An ioctl() call using the PIOCNTHR request has the following format:
ioctl(fd, PIOCNTHR, p)
where p is (int *p)
An ioctl() call using the PIOCTLIST request has the following format:
ioctl(fd, PIOCTLIST, p)
where p is (tid_t p)
See the description of the PIOCTCRAD request for a sample program that
shows use of the PIOCNTHR and PIOCTLIST requests.
PIOCVTOP
The PIOCVTOP request takes a virtual address for a given PID and, if
the page at that address is both in the user map and is resident,
returns the associated physical address and RAD ID. The p argument is a
pointer to a prvtop structure, which has the following definition:
struct prvtop {
caddr_t pr_vaddr; /* user virtual address */
caddr_t pr_paddr; /* physical address */
int pr_radid; /* RAD id where pr_vaddr resides */
int pad1;
long pad2[5];
};
typedef struct prvtop prvtop_t;
The following program fragment shows how to use the PIOCVTOP request:
int main(int argc, char *argv[]) {
prvtop_t radinfo;
char fname[80];
caddr_t vaddr;
int i;
int fd;
if (argc != 3) {
fprintf(stderr, "Usage: %s pid vaddr\n", argv[0]);
exit(1);
}
sprintf(fname, "/proc/%s", argv[1]);
sscanf(argv[2], "%lx", &vaddr);
printf("fname=%s vaddr=%p\n", fname, vaddr);
fd = open(fname, O_RDONLY);
if (fd == -1) {
perror("open");
return 1;
}
radinfo.pr_vaddr = vaddr;
radinfo.pr_radid = -1;
radinfo.pr_paddr = NULL;
if (ioctl(fd, PIOCVTOP, &radinfo) < 0) {
perror("ioctl(PIOCVTOP)");
exit(1);
}
printf("0x%016lx (physaddr = 0x%016lx) is in RAD %d\n",
radinfo.pr_vaddr, radinfo.pr_paddr, radinfo.pr_radid); }
Thread-Specific ioctl Requests
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, the kernel returns a thread ID to the program through /proc
ioctl requests. Also through /proc ioctl requests, this thread ID is
passed from the program to the kernel to identify which thread in a
task to manipulate.
With the exception of the PIOCTLIST request, the thread-specific
requests (PIOCTxxx) can operate on one or more threads. These requests
are invoked in the context of a process, just as the basic process
requests are invoked. For example, if process 123 is opened by using
/proc file system: fd=open("/proc/123", O_RDWR)
then the following call can be used to return status for one or more of
its threads: ioctl(fd, PIOCTSTATUS, p)
However, unlike the basic requests, which take the address of a fixed
length entity for the p argument, the PIOCTxxx requests use the p argu‐
ment to specify the address of a buffer that varies in length, depend‐
ing on the number of threads that are to be operated on. In addition,
the PIOCTxxx requests always require a valid p argument because it con‐
tains the number of threads to operate on and their IDs (even when the
number is 1).
The struct prthreads structure, which is defined in the <sys/procfs.h>
header file, is used as a common header for each of the PIOCTxxx
requests:
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 an error status, the ID of
the thread on which the error was detected is returned in the
pr_error_thread field. When the kernel detects an error, ioctl() pro‐
cessing stops. This means that the request succeeded for all threads
in the specified list that were processed before the thread on which
the error was reported. The request is not attempted for any threads
that remain in the list after the error is detected. If a failure is
encountered that is not related to a specific thread, the
pr_error_thread value is returned as 0.
If a specified thread is not found in the task->thread_list, the
[EBADF] error is returned.
If the pr_count value exceeds the number of threads in the task, the
[EINVAL] error is returned before any of the threads on the specified
list are processed. In this case, the pr_error_thread field is not
updated. (See the description of the PIOCNTHR request for information
on retrieving the thread count value.)
This error behavior applies to all of the PIOCTxxx requests.
PIOCTSTOP, PIOCTSTATUS
The PIOCTSTOP request stops the specified thread (or threads) and
returns status in the specified prstatus structure (or structures).
This request requires write access on the process file. The PIOCTSTATUS
request returns status without stopping the threads.
The PIOCTSTOP and PIOCTSTATUS requests use the same status structure,
prstatus, that is used by the comparable requests (PIOCSTOP and PIOC‐
STATUS) in the base request set.
Unlike the case with PIOCSTOP, a prstatus structure is always specified
with PIOCTSTOP. A thread is selected by filling in the pr_tid field of
the prstatus structure pointed to by the p argument. (See the line that
refers to thread_1 in the sample definitions below.)
The ioctl() calls with the PIOCTSTOP and PIOCTSTATUS requests have the
following formats: ioctl(fd, PIOCTSTOP, p)
ioctl(fd, PIOCTSTATUS, p)
Key definitions for both these requests are 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 the return
* status for (PIOCTSTATUS)
*/
PIOCTRUN
The PIOCTRUN request restarts one or more threads that were stopped by
the PIOCTSTOP request and requires write access on the process file.
The PIOCTRUN request provides the same functionality for threads as the
PIOCRUN request does for the process/task, except that the PRCSIG, PRC‐
FAULT and PRSHOLD flags of the prrun.pr_flags field are not recognized.
Unlike the case for 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. If the prrun.pr_flags field is set to 0, the
PIOCTRUN request does provide the same functionality as the PIOCRUN
request with a NULL p pointer.
If a specified thread is not stopped with PIOCTSTOP, the [EBUSY] error
is returned. If any error is detected while attempting to run a
thread: the ioctl() call 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 the PIOCRUN and PIOCTRUN requests, 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.
The ioctl() arguments with the PIOCTRUN request are as follows:
ioctl(fd, PIOCTRUN, p)
The buffer pointed to by the p argument includes the following key mem‐
bers:
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
The PIOCTSSIG request allows the ``current signal'' to be cleared or
changed to some other signal, only if the specified thread or threads
are stopped on an event of interest. This request requires write access
on the process file.
The arguments of an ioctl() call using the PIOCTSSIG request are as
follows: ioctl(fd, PIOCTSSIG, p)
The buffer pointed to by the p argument includes the following key mem‐
bers:
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
*/
The tsiginfo_t structure is defined in <sys/procfs.h> as follows:
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
The PIOCTKILL request allows a signal to be sent to one or more speci‐
fied threads. A different signal can be sent to each thread. Sending
SIGKILL kills a thread immediately. This request requires write access
on the process file.
The arguments for an ioctl() call using the PIOCTKILL request are as
follows: ioctl(fd, PIOCTKILL, p)
The buffer pointed to by the p argument includes the following key mem‐
bers:
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
*/
The tsignal_t structure is defined in the <sys/procfs.h> file as fol‐
lows:
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
The PIOCTUNKILL request 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 of those threads. The current signals for those
threads are unaffected. This request requires write access on the
process file.
The arguments for an ioctl() call using the PIOCTUNKILL request are as
follows: ioctl(fd, PIOCTUNKILL, p)
The buffer pointed to by the p argument includes the following key mem‐
bers:
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
*/
The tsignal_t structure is defined in <sys/procfs.h> as follows:
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
The PIOCTUSAGE request returns resource usage information about a spe‐
cific thread in a process. The p argument is a pointer to a prusage_t
structure as described in the description of the PIOCUSAGE request.
Additionally, the following field must be filled in with the desired
thread ID (obtained by a PIOCTLIST request) before the call is made:
tid_t tid; /* Thread ID to get info on */
PIOCTGFPREG, PIOCTSFPREG
The PIOCTGFPREG and PIOCTSFPREG requests are used to get and set the
Floating Point registers for one or more threads and perform the same
type of functions for threads as the PIOCGFPREG and PIOCSFPREG requests
do for the task/process. The PIOCTSFPREG request requires write access
to the process file.
For PIOCTGFPREG, if the floating-point 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, the [EBUSY] error is returned.
For PIOCTSFPREG, if a specified thread is not stopped on an event of
interest, the [EBUSY] error is returned. No check is made to see if the
floating-point hardware had been in use.
The arguments for an ioctl() call using the PIOCTGFPREG and PIOCTSFPREG
requests are as follows: ioctl(fd, PIOCTGFPREG, p)
ioctl(fd, PIOCTSFPREG, p)
The buffer pointed to by p argument includes the following key members:
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
*/
The tfpregset_t structure is defined in <sys/procfs.h> as follows:
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
The PIOCTGREG and PIOCTSREG requests are used to get and set the gen‐
eral registers for one or more threads; these requests perform the same
type of functions for threads as PIOCGREG and PIOCSREG perform for the
task/process. The PIOCTSREG request requires write access to the
process file.
For PIOCTSREG, if a specified thread is not stopped on an event of
interest, the [EBUSY] error is returned.
The arguments for an ioctl() call using the PIOCTGREG and PIOCTSREG
requests are as follows: ioctl(fd, PIOCTGREG, p) ioctl(fd, PIOCTSREG,
p)
The buffer pointed to by the p argument includes the following key mem‐
bers:
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
*/
The tgregset_t structure is defined in <sys/procfs.h> as follows:
struct tgregset {
gregset_t pr_regs; /* general registers
*/
tid_t pr_tid; /* the thread ID to act upon
*/ }; typedef struct tgregset
tgregset_t;
PIOCTGRAD
The PIOCTGRAD request returns per-thread NUMA and processor-scheduling
locality information for a specified process. This request uses the
following structure:
typedef struct tradid {
int pr_radid; /* Home RAD for thread */
int pr_rad_bound; /* Thread bound to RAD? */
int pr_cpuid; /* CPU thread last ran on */
int pr_cpu_bound; /* Thread bound to CPU? */
long pad[5]; /* Reserved for future use */
tid_t pr_tid; /* Thread ID */
} tradid_t;
The following program shows an implementation of this request:
#include <unistd.h> #include <stdlib.h> #include <stdio.h> #include
<fcntl.h> #include <sys/types.h> #include <sys/procfs.h>
int main(int argc, char *argv[]) {
prthreads_t *hdr;
pid_t pid;
tid_t *tidlist;
int nthreads;
char fname[80];
int i;
int fd;
int status = 0;
tradid_t *radp;
if (argc != 2) {
fprintf(stderr, "Usage: %s pid\n", argv[0]);
exit(1);
}
pid = atoi(argv[1]);
sprintf(fname, "/proc/%d", pid);
fd = open(fname, O_RDWR);
if (fd < 0) {
perror("open");
return 1;
}
if (ioctl(fd, PIOCSTOP, NULL) != 0) {
perror("ioctl(PIOCSTOP)");
status = 1;
goto restart;
}
if (ioctl(fd, PIOCNTHR, &nthreads) < 0) {
perror("ioctl(PIOCNTHR)");
status = 1;
goto restart;
}
printf("Num Threads: %d\n", nthreads);
tidlist = malloc(sizeof(tid_t) * nthreads);
if (ioctl(fd, PIOCTLIST, tidlist) < 0) {
perror("ioctl(PIOCTLIST)");
status = 1;
goto restart;
}
hdr = malloc(sizeof(prthreads_t) + (sizeof(tradid_t) * nthreads));
hdr->pr_count = nthreads;
hdr->pr_error_thread = -1;
radp = (tradid_t *)&hdr->pr_data[0];
for (i = 0; i < nthreads; i++) {
radp[i].pr_tid = tidlist[i];
radp[i].pr_radid = -1;
radp[i].pr_rad_bound = -1;
radp[i].pr_cpuid = -1;
radp[i].pr_cpu_bound = -1;
}
if (ioctl(fd, PIOCTGRAD, hdr) < 0) {
perror("ioctl(PIOCTGRAD)");
printf("\nError thread: %d\n", hdr->pr_error_thread);
status = 1;
goto restart;
}
printf(" Bound Bound\n");
printf(" TID RAD id to RAD? CPU id to CPU?\n");
printf(" ---------------------- -------\n");
for (i = 0; i < nthreads; i++) {
printf(" %3d %2d %c %2d %c\n",
radp[i].pr_tid,
radp[i].pr_radid,
radp[i].pr_rad_bound ? 'Y' : 'N',
radp[i].pr_cpuid,
radp[i].pr_cpu_bound ? 'Y' : 'N');
} restart:
if (ioctl(fd, PIOCRUN, NULL) != 0) {
perror("ioctl(PIOCRUN)");
status = 1;
}
return status; }
NOTES
To wait for one or more processes to stop, /proc file descriptors can
be used in a poll() system call. A POLLPRI event is used to specify
waiting for a process or one of its threads to stop on an event of
interest. When requested and returned, the polling event POLLPRI indi‐
cates that the process or one of its threads 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 descrip‐
tor that refers to a system process. The select() system call can be
used in a similar way. When used in a select() system call, the
exceptfds parameter specifies which file descriptors are to be checked.
(See select(2).) A positive indication is returned if the process, cor‐
responding 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 by using PIOCTRUN; PIOCRUN
has no effect on the thread. Threads stopped on all other events of
interest must restarted by using PIOCRUN.
This reference page includes only the interesting members of the struc‐
tures defined in the <sys/procfs.h> header file and may show elements
out of order for descriptive clarity. Refer to the header file itself
for complete structure definitions.
ERRORS
In addition to the errors normally associated with file system access,
the following errors can be set by the ioctl() requests described in
this reference page: The operation failed because the traced process
performed an exec call on a setuid/setgid object file or on an object
file that the process cannot read; subsequent operations (except for a
close() call) on the file descriptor will fail with this error. An I/O
or ioctl() call requiring write access was attempted on a file descrip‐
tor not open for writing. One of the following conditions was encoun‐
tered: PIOCRUN, PIOCTRUN, PIOCSREG, PIOCTSREG, PIOCSFPREG, or PIOCTSF‐
PREG was applied to a process or one of its threads not stopped on an
event of interest. An exclusive open() was attempted on a process file
already open for writing. An open() for write was attempted and an
exclusive open() is in effect on the process file. An attempt was made
to mount the /proc file system when it is already mounted. PIOCDUMP‐
CORE was applied to a process that was not stopped. An I/O or ioctl()
request referred to an invalid address in the controlling process. A
signal was received by the controlling process while waiting for the
traced process to stop. One of the following occurred: An invalid
argument was supplied to a system call. A non-exhaustive list of rea‐
sons this can happen includes the following: An ioctl request was
applied to a file descriptor referring to the /proc directory. The
specified ioctl request is undefined. The pr_count value used with one
of the thread-specific ioctl() requests exceeded the number of threads
in the task. In this case, the requested operation was not performed
for any thread. An I/O or ioctl() request referred to an invalid
address in the traced process. The file does not exist, or its corre‐
sponding process has terminated after being opened. An attempt was
made to perform an operation that is not supported by the /proc file
system. The calling process does not have appropriate privilege.
FILES
The directory that contains process file identifiers.
SEE ALSO
Functions: intro(2), close(2), ioctl(2), open(2), poll(2), read(2),
setsysinfo(2), sigaction(2), signal(2), write(2)
Others: siginfo(5)proc(4)
