 |
Index for
Section 4 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
proc(4)
NAME
proc - 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 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
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.
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; /* 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 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
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
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 user-level 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
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
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
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
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 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
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 description 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 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
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
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
The PIOCGFAULT request returns the current traced fault set in the fltset_t
structure that is pointed to by the p argument.
PIOCCFAULT
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
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
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
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 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
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 PIOCSTATUS
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 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
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 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
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
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 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
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.
PRFS_STOPTCR
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_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.)
PRFS_STOPTTERM
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.
PRFS_KOLC
Sets the kill-on-last-close flag in the traced process. This flag
is off by default. If the flag is set, the traced process is
terminated by a SIGKILL signal when the last /proc file descriptor
referring to the traced process is closed. This action occurs even
if the traced process is stopped on a trace event. All further
tracing is disabled. If set, 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 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 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 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
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, PRCFAULT 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 members:
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 members:
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 specified
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 members:
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 follows:
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 members:
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 specific
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 general
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 members:
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 indicates 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. POLLNVAL is returned immediately
if POLLPRI is requested on a file descriptor 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, corresponding to the open file descriptor, has
stopped on an event of interest.
If PIOCTSTOP is invoked for a thread, and the thread is successfully
stopped, the thread can be restarted only 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 structures
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:
[EAGAIN]
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.
[EBADF]
An I/O or ioctl() call requiring write access was attempted on a file
descriptor not open for writing.
[EBUSY]
One of the following conditions was encountered:
· PIOCRUN, PIOCTRUN, PIOCSREG, PIOCTSREG, PIOCSFPREG, or PIOCTSFPREG
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.
· PIOCDUMPCORE was applied to a process that was not stopped.
[EFAULT]
An I/O or ioctl() request referred to an invalid address in the
controlling process.
[EINTR]
A signal was received by the controlling process while waiting for the
traced process to stop.
[EINVAL]
One of the following occurred:
· An invalid argument was supplied to a system call. A non-
exhaustive list of reasons 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.
[EIO]
An I/O or ioctl() request referred to an invalid address in the traced
process.
[ENOENT]
The file does not exist, or its corresponding process has terminated
after being opened.
[ENOSYS]
An attempt was made to perform an operation that is not supported by
the /proc file system.
[EPERM]
The calling process does not have appropriate privilege.
FILES
/proc
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)
|
Index for
Section 4 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|