proc - The process (/proc) file system and associated
ioctl requests
/proc
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 permissions 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 [Toc] [Back]
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 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 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 exclusive 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 running process by a debugger; the debugger is
therefore always responsible 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 control, can be performed on a process file only
if it is open for writing.
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.
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 [Toc] [Back]
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; /* 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 flags can be included in the pr_flags bitmask:
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 PIOCSENTRY 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
sigaction()). 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 terminated and to see its exit status. See
also ioctl(2).
pr_info
The pr_info member of the prstatus structure is a structure
that contains 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 nanoseconds) 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 [Toc] [Back]
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
structure 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 userlevel
code.
An event of interest occurs when either a PR_REQUESTED
stop was specified 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 [Toc] [Back]
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 PIOCSTOP 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 [Toc] [Back]
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 appropriate 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 specifies
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 PIOCSHOLD request.) PRSFAULT specifies that the
traced fault set is set to the value of the pr_fault
field. (See the description of the PIOCSFAULT 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 support 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 [Toc] [Back]
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 tracing 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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
The PIOCGTRACE request returns the current traced signal
set in an instance of the sigset_t structure pointed to by
the p argument.
PIOCSSIG [Toc] [Back]
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 [Toc] [Back]
The PIOCKILL request sends a signal to the process with
semantics identical to those of the kill() function. The
p argument points to a buffer of type int that names the
signal. Sending a SIGKILL signal terminates the process
immediately. This request requires write access on the
process file.
PIOCUNKILL [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 description of the
PIOCGHOLD request.) Signal number 0 cannot be held; it is
ignored if specified.
PIOCMAXSIG [Toc] [Back]
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 argument, 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 [Toc] [Back]
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 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 the PIOCMAXSIG 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 [Toc] [Back]
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];
} fltset_t;
The following supported fault names are defined in the
<sys/fault.h> file: 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
Some of these fault names may be identical on some processors
and some names may not occur on all processors. Furthermore,
there may be processor-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 system 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-specific information about the fault.
PIOCGFAULT [Toc] [Back]
The PIOCGFAULT request returns the current traced fault
set in the fltset_t structure that is pointed to by the p
argument.
PIOCCFAULT [Toc] [Back]
The PIOCCFAULT request clears the current fault (if any),
and the associated 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 [Toc] [Back]
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 [Toc] [Back]
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 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 [Toc] [Back]
The PIOCGENTRY request returns the entry of the currently
traced system call in the sysset_t structure pointed to by
the p argument.
PIOCGEXIT [Toc] [Back]
The PIOCGEXIT request returns the exit set of the currently
traced system 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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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
PIOCSTATUS request and is discussed in the description for
that request.)
PIOCSREG [Toc] [Back]
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 [Toc] [Back]
The PIOCGFPREG request 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 shown in the description of
the PIOCSFPREG request, which is architecture dependent.
PIOCSFPREG [Toc] [Back]
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 [Toc] [Back]
The following requests perform a variety of operations.
PIOCPSINFO [Toc] [Back]
The PIOCPSINFO request returns miscellaneous process
information that is similar to the information returned by
the ps command. The p argument 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 [Toc] [Back]
The PIOCUSAGE request returns resource usage information
about a process. The p argument is a pointer to a
prusage_t structure containing 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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 determines 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 [Toc] [Back]
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 [Toc] [Back]
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-onthread-create.
This condition causes 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 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() system 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-onthread-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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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, 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 threadspecific
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 argument to specify the address of a
buffer that varies in length, depending on the number of
threads that are to be operated on. In addition, the
PIOCTxxx requests always require a valid p argument
because it contains 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() processing 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 PIOCSTATUS) 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
|
