proc(7) CLIX proc(7)
NAME
proc - Process file system
DESCRIPTION
The proc commands provide a number of data gathering and control functions
on /proc files. A /proc file describes a running process. Its contents
correspond to the process virtual address space and may be read or written
with the read() and write() system calls. The ioctl() commands described
below outline additional actions that may be performed on /proc files.
The ioctl() system call
ioctl(fildes,request,arg)
is used to support the proc functions. The value fildes is an open file
descriptor that refers to a /proc file. The value of request determines
the control function to be performed as described below. The value of arg
represents additional information needed by the command. The type of arg
depends on the request, but it is generally an integer or a pointer to a
data structure.
Since these proc commands are implemented through ioctl(), they are
subject to the errors described in ioctl(). Erros specific to request are
described below.
Command Functions
The following ioctl() commands apply to all /proc files:
PIOCGETPR
Copy the kernel proc structure for the referenced process into the
buffer address supplied in arg. This structure is in kernel memory
and cannot be reached through read(). The referenced buffer should
have the size of the proc structure as declared in <sys/proc.h>.
Including this file will require that the header files
<sys/types.h>, <sys/immu.h>, <sys/param.h>, and <sys/region.h> also
be included. On failure, errno is set to one of the following
values:
[EFAULT] An error occurred when copying the kernel proc structure
into the buffer pointed to by arg.
[ESRCH] The referenced process no longer exists.
PIOCGETUBLK
Copy the kernel user structure for the referenced process into the
buffer address supplied in arg. This structure is in kernel memory
and cannot be reached through read(). The referenced buffer should
have the size NBPP * USIZE as defined in <sys/immu.h> and
2/94 - Intergraph Corporation 1
proc(7) CLIX proc(7)
<sys/param.h>. Including these files will require that the header
file <sys/types.h> also be included. On failure, errno is set to
the following value:
[EFAULT] An error occurred when copying the kernel user structure
into the buffer pointed to by arg.
PIOCSTOP
Send the signal SIGSTOP and wait for the process to enter the
stopped state. The value returned by the function indicates the
reason the process stopped. The possible reasons for stopping are
as follows:
REQUESTED
The process was requested to stop through the PIOCSTOP command.
SIGNALLED
The process stopped due to receipt of a signal. For the process to
stop on a particular signal, a PIOCSMASK command must be issued.
SYSENTRY
The process was stopped when it entered a system call. For this to
occur, a previous PIOCSENTR command must have been issued.
SYSEXIT
The process was stopped when it exited a system call. For this to
occur, a previous PIOCSEXIT command must have been issued.
These return values are defined in <sys/proc.h>. In addition, arg
points to an integer that is updated with additional information on
what caused the process to stop. The interpretation of this
additional stop value depends on the return value as follows:
Return Value Stop Value Interpretation
________________________________________
REQUESTED The value will always be
0.
SIGNALLED The number of the signal
causing the process stop.
SYSENTRY The number of the system
call for which the
process stopped on entry.
SYSEXIT The number of the system
call for which the
process stopped on exit.
On failure, errno is set to the following value:
[ESRCH] The referenced process no longer exists.
PIOCWSTOP
2 Intergraph Corporation - 2/94
proc(7) CLIX proc(7)
Wait for a process to stop. See the PIOCSTOP description on the
interpretation of arg and the return value. On failure, errno is
set to the following value:
[ESRCH] The referenced process no longer exists.
[EINTR] The receipt of a signal caused premature return from the
system call.
PIOCRUN
Make a process runnable after a stop. On failure, errno is set to
the following value:
[ESRCH] The referenced process no longer exists.
PIOCSMASK
Specify, through a bit mask, signals whose receipt will cause the
process to enter the stopped state. A mask of zeros turns off
signal tracing. The address of the signal mask is supplied in arg.
The side effect to this call is that a process will remain traced
even after the process requesting the trace has closed the /proc
file. On failure, errno is set to one of the following values:
[EFAULT] An error occurred when copying the signal bit mask from
the address specified in arg.
[ESRCH] The referenced process no longer exists.
PIOCCSIG
Clear all pending signals to a process. The referenced process no
longer exists.
PIOCEXCLU
Mark the text segment of a process as nonshared so that subsequent
write requests will succeed. On failure, errno is set to one of
the following values:
[EIO] An error occurred when attempting to copy the shared,
read-only text segment to a nonshared, writable text
segment.
[ESRCH] The referenced process no longer exists.
PIOCOPENT
Return a read-only file descriptor for the file containing the
process text and data segments. This command allows debuggers to
access the symbol table without knowing the executable's pathname.
On failure, errno is set to one of the following values:
[EIO] The user block of the referenced process is not in core.
2/94 - Intergraph Corporation 3
proc(7) CLIX proc(7)
[ESRCH] The referenced process no longer exists.
PIOCSTR
Set the trace bit in the process Processor Status Word register.
This will cause the process to receive a SIGTRAP signal after
executing the next instruction. This is provided to facilitate
process single stepping. On failure, errno is set to one of the
following values:
[EIO] The user block of the referenced process is not in core.
[ESRCH] The referenced process no longer exists.
PIOCRREGS
Read the register set of the referenced process into the supplied
buffer. The full register set, including 16 general, 8 floating,
and 3 special registers, is read. On failure, errno is set to one
of the following values:
[EFAULT] An error occurred when copying the process registers
into the buffer pointed to by arg.
[EIO] The user block of the referenced process is not in core.
[ESRCH] The referenced process no longer exists.
PIOCWREGS
Read a register set from the supplied buffer and writes it to the
address space of the referenced process. The full register set,
including 16 general, 8 floating, and 3 special registers is
written. On failure, errno is set to the one of the following
values:
[EFAULT] An error occurred when copying the process's registers
from the buffer pointed to by arg.
[EIO] The user block of the referenced process is not in core.
[ESRCH] The referenced process no longer exists.
PIOCSENTER
Establish a system call which, upon entry, will cause the process
to enter the stopped state. The system call number is supplied in
an integer pointed to by arg. If the supplied system call number
is 0, system call entry tracing will be disabled. On failure,
errno is set to one of the following values:
[EFAULT] An error occurred when attempting to copy the system
call number from the address supplied in arg.
[EINVAL] The system call number is out of range.
4 Intergraph Corporation - 2/94
proc(7) CLIX proc(7)
[EIO] The user block of the referenced process is not in core.
[ESRCH] The referenced process no longer exists.
PIOCSEXIT
Establish a system call which, upon exit, will cause the process to
enter the stopped state. The system call number is supplied in an
integer pointed to by arg. If the supplied system call number is
0, system call exit tracing will be disabled. On failure, errno is
set to one of the following values:
[EFAULT] An error occurred when attempting to copy the system
call number from the address supplied in arg.
[EINVAL] The system call number is out of range.
[EIO] The user block of the referenced process is not in core.
[ESRCH] The referenced process no longer exists.
PIOCFENTR
Specify whether a process should enter the stopped stated when a
memory fault occurs. If arg is 0 the process will not be stopped,
otherwise the process will be stopped.
PIOCFADDR
The virtual address of the last page that faulted is copied into
the integer pointed to by arg. On failure, errno is set to the
following value:
[EFAULT] An error occurred when copying the address into integer
pointed to by arg.
PIOCGETPINFO
Copy the kernel pinfo structure for the referenced process into the
buffer address supplied in arg. This structure is in kernel memory
and cannot be reached through read(). The referenced buffer should
have the size of the pinfo structure as declared in <sys/pinfo.h>.
Including this file will require that the header file <sys/types.h>
also be included. On failure, errno is set to the following value:
[EFAULT] An error occurred when copying the pinfo structure into
the buffer pointed to by arg.
DIAGNOSTICS
Unless otherwise specified above, the return value from ioctl() is 0 upon
success and -1 upon failure with errno set as indicated.
RELATED INFORMATION
2/94 - Intergraph Corporation 5
proc(7) CLIX proc(7)
Functions: intro(2), close(2), ioctl(2), open(2), read(2), signal(2),
sigset(2), write(2)
CLIX Programming Guide
6 Intergraph Corporation - 2/94