*** UNIX MANUAL PAGE BROWSER ***

proc(4) Kernel Interfaces Manual proc(4) NAME proc - Process file system SYNOPSIS /proc DESCRIPTION The /proc file system enables running processes to be accessed as files by the system calls open, close, read, write, lseek, poll/select, and ioctl. While the /proc file system is most useful for debuggers, the /proc file system enables any process with the correct permissions to control another running process. Thus, a parent/child relationship does not have to exist between a debugger and the process that is being debugged. For each active or zombie process, there is an entry in the system process table, which appears as a file name in the /proc directory. The file name is the decimal representation of the process id. File names are padded with leading zeros (0) so that each file name is a minimum of 5 decimal digits. For example, if a process has a process id of 123, its file name would be specified as 00123. You do not have to specify the leading zeros when specifying the file name. For exam- ple, specifying ls -l /proc/123 is acceptable. The only files that appear to exist in the /proc directory correspond to valid (active or zombie) processes in the system proc table. Other than creating or terminating a process, you cannot create or remove files in the /proc directory. The permissions for a file in the /proc directory are 0600, which indicates read and write permissions for the owner only. The uid and gid for a file in the /proc directory are the uid and gid of the user who is running the process. Setting Up the /proc Filesystem The /proc file system is layered beneath the Virtual File System (VFS). It is a pseudo-file system that occupies no actual disk space. The /proc pseudo-file system appears to contain files (which are actually running processes). You can use the mount and umount commands to manu- ally mount and dismount the file system, or you can define an entry for the /proc file system in your /etc/fstab file. To mount the /proc file system using the mount command, enter the fol- lowing: mount -t procfs /proc /proc To dismount the file system, use the umount command as follows: umount /proc You can add the following entry to your /etc/fstab file to let the /proc file system be mounted automatically at startup: /proc /proc procfs rw 0 0 Security Considerations All auditing requirements for the /proc file system are handled at the Virtual File System (VFS). root or the superuser can open all processes using the /proc file system. A nonprivileged user can open an active process only if the following conditions are met: Both the uid and gid of the user match those of the running process. The user has read permission for the executable file from which the active process was created. The executable file from which the active process was created must not have setuid or setgid permission unless the user has root or SEC_DEBUG privilege established or is the owner (for se- tuid) or a group member (for setgid). If a debugging process opens an active process and the active process calls exec(2) to start another image that has suid or sgid permissions, or if the debugging process does not have read permission for the image that the active process invokes, the debugging process is denied access to the process information for the new image with the exception of a close operation. This is also true for root or users with superuser privileges. Manipulating Processes: System Calls and ioctls Files are manipulated using the open, close, read write, poll/select, and ioctl system calls. Once a process has been opened, its user vir- tual address space can be examined or written using the lseek system call followed by the read or write system calls. Likewise, as long as a process is opened for both read and write, the ioctl system calls can be used to control, trace, or get status for a process that has been opened. The close system call should be used when interaction with a process is complete. Any number of opens for read and write are al- lowed; however, to prevent confusion, if several processes are trying to control another process, an exclusive open for write can be re- quested. An open for write that includes the O_EXCL specifier only succeeds if the process is not already open for a write. An open for write that does not specify O_EXCL always succeeds for root or an oth- erwise privileged user. There can be any number of read-only opens, even when an exclusive write open is in effect on the file. When a file is closed, any tracing flags that were set are left on, un- less the Run on Last Close (RLC) flag was set by an ioctl call. If RLC is set, and the last writable file descriptor pertaining to the process is closed, all tracing flags are cleared and the process is set to run (if it was stopped). Breakpoints are not affected by RLC because breakpoints are written into the text area of a running process by a debugger; the debugger is therefore always responsible for replacing the original instructions. Information and control operations are provided through ioctl. The op- erations have the form: #include <sys/types.h> #include <sys/signal.h> #include <sys/fault.h> #include <sys/syscall.h> #include <sys/procfs.h> ioctl(fd, COMMAND, p); The p argument is a generic pointer whose use depends on a specific ioctl code. Where not mentioned in the description of the ioctl calls, the value should be zero. <sys/procfs.h> contains definitions of ioctl codes and data structures used by the operations. Certain operations can be performed only if the process file is open for writing; these include all operations that affect process control. Process and control operations involve the use of a set of flags. The set types sigset_t, fltset_t, and sysset_t are masks. The values used to set these masks correspond respectively to the signal, fault, and system call numbers defined in <sys/signal.h>, <sys/fault.h>, and <sys/syscall.h>. Each set type is large enough to hold the masks bits for all legal values of the related action. Although they are of dif- ferent sizes, they have a common structure and can be manipulated by the following macros: prfillset(&set); /* turns on all flags * in set */ premptyset(&set); /* turns off all flags * in set */ praddset(&set,flag); /* turns on a specified * flag */ prdelset(&set,flag); /* turns off a specified * flag */ r = prismember(&set,flag); /* returns true if flag * is on */ Either prfillset or premptyset must be used to initialize set before it is used in any operation. The argument flag must be a member of the enumeration corresponding to the set. Ioctl Codes The ioctl codes are divided into eight groups: process requests, signal interaction, fault trap interaction, system call interaction, traced process control, general registers, miscellaneous mapping control, and DIGITAL UNIX specific requests. The following subsections describe these ioctl codes. Process Requests The following ioctls specify process requests: PIOCSTATUS Returns status information for the process. The argument p points to the prstatus structure containing following members: long pr_flags; /* specifies process flags */ short pr_why; /* reason process is stopped */ long pr_what; /* specifies detailed reasons */ struct siginfo pr_info; /* data related to signal * or fault */ short pr_cursig; /* specifies current * signal */ sigset_t pr_sigpend; /* set of other pending * signals */ sigset_t pr_sighold; /* set of held signals */ struct sigaltstack pr_altstack; /* alternate * signal stack * data */ struct sigaction pr_action; /* signal action of * current signal */ pid_t pr_pid; /* specifies process id */ pid_t pr_ppid; /* specifies parent process id */ pid_t pr_pgrp; /* specifies group process id */ pid_t pr_sid /* specifies session id */ timestruc_t pr_utime; /* specifies process * user cpu time */ timestruc_t pr_stime; /* specifies process * system cpu time */ timestruc_t pr_cutime; /* sum child processes * user time */ timestruc_t pr_cstime; /* sum child processes * system time */ char pr_clname[8]; /* scheduling class name */ gregset_t pr_reg; /* specifies general registers */ long pr_nthreads; /* number of threads */ tid_t pr_tid; /* thread id output by * PIOCSTATUS */ The following list describes each member of the structure pr_flags. The pr_flags bit-mask has the following flags: PR_STOPPED specifies that the process is stopped. PR_ISTOP specifies that the process stopped on an event of interest (see PIOCSTOP) PR_DSTOP specifies that the process will stop before entering user code (see PIOCSTOP). PR_ASLEEP specifies that a process is in an interruptible sleep within a system call. PR_RLC specifies that a process has its run-on-last- close flag set. PR_PTRACE specifies that a process is being traced us- ing ptrace. PR_PCINVAL specifies that a process program counter refers to an invalid address. PR_ISSYS specifies that a process is a system process (see the PIOCSTOP ioctl). pr_why and pr_what The pr_why and pr_what fields describe why a process is stopped and what stopped it. The possible values for pr_why follow. Included in the description of the pr_why values is an explanation of what pr_what holds. The pr_why values are: PR_REQUESTED indicates that PIOCSTOP was specified, hence the process was stopped. In this instance, the pr_what field is not used. PR_SIGNALLED indicates that a process stopped upon receiving a signal (see PIOCSTRACE). The pr_what field holds the signal number that caused the stop. If this is a newly stopped process, the signal number is placed in pr_cursig. PR_FAULTED specifies that a process stopped upon encountering a fault (see PIOCS- FAULT). 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 oc- cur on an entry to or an exit from a system call (see PIOCSENTRY and PIOCSEXIT). The pr_what field holds the number of the system call, in- cluding the habitat number, if any. PR_JOBCONTROL specifies that a process stopped because of the default action specified by a job con- trol stop signal (see sigaction). The pr_what field holds the stopping signal number. PR_DEAD specifies that a process has terminated. At this point, the process and memory context are considered invalid. The pr_what field holds the exist status of the process. This function provides the debugger with the ability to determine that the process being debugged has terminated, and to see its exit status. ioctl. pr_info Contains additional information specific to a signal or fault when a process has been stopped by either PR_SIGNALLED or PR_FAULTED (see <sys/siginfo.h>). pr_cursig Identifies the number of the next signal to be delivered to a process. pr_sigpend Is a mask of pending signals that are to be sent to a process. pr_sighold Is a mask of those signals whose delivery will be delayed if sent to a process. Note that this mask is 0 to (N-1), as opposed to pr_sigpend, which is 1 to N, where N is the max signal number. pr_altstack Provides alternate signal stack information for a process (see sigalt- stack). pr_action Contains any signal action related to the current signal (see sigac- tion). The signal action is not defined if pr_cursig is zero. pr_pid Contains the process identification number. pr_ppid Contains the process identification number of the parent process. pr_pgrp Contains the group identification number of the process. pr_sid Contains the session identification number of the process. pr_utime and pr_stmine Contain the user and system time (in seconds and nanoseconds) used by the process. pr_cutime and pr_cstime Contain the cumulative user and system time (in seconds and nanosec- onds) used by the process's children. pr_clname Contains the name of the scheduling class that a process is using. pr_reg An array that contains the contents of the general registers for the thread specified by pr_tid. For a single-threaded process, this is the first thread. pr_nthreads Contains the number of threads currently in the process (task). pr_tid If the process is stopped on an event of interest, pr_tid contains the thread ID of the thread that hit the process (task) trace event. NOTE: In a multithreaded task, the PIOCSTOP ioctl sets pr_tid to the thread ID of the first thread and sets the registers in pr_reg accordingly. PIOCSTOP and PIOCWSTOP The PIOCSTOP ioctl requires write access. This ioctl code requests that a process stop on an event of interest and remains in effect until the process does stop. The PIOCWSTOP ioctl waits for a process to stop on an event of interest. For both ioctls, if the p argument is of a nonzero value, it points to prstatus_t structure that holds status in- formation on a stopped process. If PIOCSTOP is specified with a process that is stopped, but not stopped on an event of interest, the stop directive only takes affect when the process is restarted by the competing mechanism, and before executing any user level code. An event of interest occurs when either a PR_REQUESTED stop has been specified or when a stop has been specified in tracing flag of a process that can be set by PIOCSTRACE, PIOCSFAULT, PIOCSENTRY, or PIOC- SEXIT. A PR_JOBCONTROL flag is not considered an event of interest. A system process (indicated by the PR_ISSYS flag) never executes at user level, does not have a user level address space visible through /proc, and cannot be stopped. Applying PIOCSTOP or PIOCWSTOP to a sys- tem process returns the error EBUSY. PIOCRUN Starts a traced process again after it has been stopped. This ioctl requires write access. PIOCRUN fails with an EBUSY error if it is ap- plied to a process that is not stopped on an event of interest, even when it is stopped due to a competing mechanism. The p argument points to a prrun structure that provides additional directives or actions that can be performed: typedef struct prrun { long pr_flags; /* specifies process flags */ sigset_t pr_trace; /* specifies set of signals to * trace */ sigset_t pr_sighold; /* specifies set of * signals to hold */ fltset_t pr_fault; /* specifies set of faults to * trace */ caddr_t pr_vaddr; /* specifies virtual address * at which to resume */ long pr_filler[8]; /* filler area for future * expansion */ tid_t pr_tid; /* Thread to resume for PIOCTRUN, * ignored by PIOCRUN */ } prrun_t; The fields in the prrun structure are only meaningful if the appropri- ate flags are set in pr_flags bit-mask. The pr_flags bit-mask has the following flags: PRCSIG specifies that the current signal, if any, be cleared (see the PIOCSSIG ioctl). PRCFAULT specifies that the current fault, if any, be cleared (see the PIOCCFAULT ioctl). PRSTRACE speci- fies that the traced signal set is set to pr_trace (see the PIOCSTRACE ioctl). PRSHOLD specifies that the held signal set is set to pr_sighold (see the PIOCSHOLD ioctl). PRSFAULT specifies that the traced fault set is set to pr_fault (see the PIOCSFAULT ioctl). PRSVADDR specifies the address at which execution resumes to pr_vaddr. PRSTEP tells the process to run and execute a single machine instruc- tion. When execution has completed, a hardware trace trap occurs. If FLTTRACE is being traced, the process stops on the fault, otherwise, a SIGTRAP is posted. If SIGTRAP is being traced and not held, the process stops on the signal. This operation requires hardware and op- erating system support and might not be implemented on all systems. PRSABORT specifies that the process is to abort execution of current system call if the process is in a PR_SYSENTRY stop or it is marked PR_ASLEEP (see PIOCSENTRY and PIOCEXIT). PRSTOP specifies that a process stop again soon after it has resumed execution (see PIOCSTOP). Specifically, when a process is stopped on PR_SIGNALLED or PR_FAULTED, the next stop displays PR_REQUESTED, no other stop can intervene, and the process will not have executed any user-level code. PIOCSRLC This ioctl sets the run-on-last-close flag in the traced process. When the last writable /proc file descriptor referring to the traced process is closed, all of the process's tracing flags are cleared, any out- standing stop directive is canceled, and if the process is stopped, it is set running as though PIOCRUN had been applied to it. This ioctl requires write access. The flag run-on-last-close is off by default. PIOCRRLC This ioctl turns the run-on-last-close flag off. The tracing flags of a process are retained and the process is not restarted when the process file is closed. This ioctl requires write access. PIOCNICE The traced process's priority is incremented by the amount contained in the int addressed by the p argument. Only the superuser can better the priority of a process in this manner, but any user can make the prior- ity worse. Signal Interaction The following ioctls specify signal interaction. PIOCSTRACE This defines a set of signals to be traced and the receipt of one of these signals causes the traced process to stop. The set of signals is defined through the sigset_t structure that is pointed to by the argu- ment p. Receipt of SIGKILL cannot be traced. This ioctl requires write access. If a signal that is included in the held signal set is sent to the traced process, the signal is not received and does not cause a process stop until it is removed from the held signal set, either by the process itself or by setting the held signal set with the PIOCSHOLD ioctl or using the PRSHOLD option defined by the PIOCRUN ioctl. PIOCGTRACE The current traced signal set is returned in an instance of sigset_t structure pointed to by the p argument. PIOCSSIG The current signal and its associated signal information are set ac- cording to the contents of the siginfo structure addressed by p (see <sys/siginfo.h>). If the specified signal number is zero or if p is zero, the current signal is cleared. This ioctl requires write access. An error (EBUSY) is returned if the process is not stopped on an event of interest. The semantics of this ioctl are different from those of kill or PIOCKILL in that the signal is delivered to the process immedi- ately after execution is resumed (even if it is being held) and an ad- ditional PR_SIGNALLED stop does not intervene even if the signal is traced. Setting the current signal to SIGKILL terminates the process immediately, even if it is stopped. PIOCKILL A signal is sent to the process with semantics identical to those of kill(2); p points to an int naming the signal. Sending SIGKILL termi- nates the process immediately. This ioctl requires write access. PIOCUNKILL A signal is deleted (removed from the set of pending signals); the cur- rent signal, if any, is unaffected. The p argument points to an int naming the signal. It is an error to attempt to delete SIGKILL. The current signal is unaffected. This ioctl requires write access. PIOCGHOLD This ioctl returns the set of held signals (signals whose delivery is delayed if sent to the process) in an instance of sigset_t addressed by the p argument. Signal number 0 is always returned if not held. PIOCSHOLD This ioctl sets the held signal set. SIGKILL or stop signals can not be held. If specified, they will be ignored silently. It requires write access. See PIOCGHOLD. Signal number 0 cannot be held; it is ignored if specified. PIOCMAXSIG This ioctl, with the PIOCACTION ioctl, provides information about the signal actions associated with the traced process (see sigaction). In the int returned by the p argument, this ioctl returns the maximum signal number understood by the system. This must be used to allocate storage for use with the PIOCACTION ioctl. PIOCACTION This ioctl, with the PIOMAXSIG ioctl, provides information about the signal actions associated with the traced process. This ioctl returns the traced process's signal actions in an array of sigaction structures addressed by the p argument. Signal numbers are displaced by 1 from array indices, so that the action for signal number n appears in posi- tion n-1 of the array. Note that PIOCMAXSIG should be called before invoking the PIOCACTION ioctl. See sigaction(2) for the definition of the sigaction structure. Fault Trap Interaction The following ioctls specify fault trap interaction. PIOCSFAULT This defines a set of hardware faults to be traced. When incurring one of these faults the traced process stops. This ioctl requires write access. The set is defined via an instance of fltset_t addressed by p. Supported fault names are defined in <sys/fault.h> and include the fol- lowing. Some of these may be identical on some processors; some of these may not occur on all processors; there may be processor-specific faults in addition to the following: FTTILL specifies an illegal in- struction 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 speci- fies an unrecoverable stack fault FLTPAGE specifies a recoverable page fault FLTALIGN specifies an unaligned access fault When not traced, a fault normally results in the posting of a signal to the process that incurred the fault. If the process stops on a fault, the signal is posted to the process when execution is resumed unless the fault is cleared by PIOCCFAULT or by the PRCFAULT option of PI- OCRUN. FLTPAGE and FLTALIGN are exceptions; no signal is posted after FLTPAGE fault. A signal may or may not be posted after FLTALIGN de- pending on operating system support. There may be additional proces- sor-specific faults like this. The pr_info structure member in the prstatus structure identifies the signal to be sent and contains ma- chine-specific information about the fault. typedef struct { unsigned long word[FLTSET_SZ]; } fltset_t; PIOCGFAULT The current traced fault set is returned in the fltset_t structure that is pointed to by the p argument. PIOCCFAULT The current fault (if any) is cleared; the associated signal is not sent to the process. This ioctl requires write access. System Call Interaction The following ioctls specify system call interaction. PIOCSENTRY This ioctl instructs the process to stop on entry to the specified sys- tem calls. The set of syscalls to be traced is defined in the sysset_t structure addressed by the p argument. See the PIOCEXIT ioctl for a description of the sysset_t structure. This ioctl requires write ac- cess. When an entry to a system call is being traced, the traced process stops at beginning of the call to the system. PIOCSEXIT This ioctl instructs the process to stop on exit from the specified system calls. The set of syscalls to be traced is defined in the sys- set_t structure addressed by the p argument. This ioctl requires write access. When exit from a system call is being traced, the traced process stops on completion of the system call after return values are stored into the traced process's saved registers. If the traced process is stopped on an entry to a system call by PR_SY- SENTRY, or if it is in an interruptible system call with PR_ASLEEP set, it may be instructed to go directly to system call exit by specifying the PRSABORT flag in a PIOCRUN request. Unless exit from the system call is being traced, the process returns to the user level with the EINTR error. typedef struct { unsigned long word[SYSSET_SZ]; } sysset_t; An exec system call can fail after a new image has been loaded partially, and the old memory context has been destroyed. When that happens, the traced process will exit without stopping on exit from the exec system call. PIOCGENTRY This ioctl returns the entry of the currently traced system call in the sysset_t structure pointed to by the p argument. PIOCGEXIT This ioctl returns the exit set of the currently traced system call in the sysset_t structure pointed to by the p argument. Traced Process Control The following ioctls specify traced process control. PIOCSFORK This ioctl sets the inherit-on-fork-flag in the traced process. The tracing flag of a process are inherited by the child of a fork(2) or vfork(2). This ioctl requires write access. PIOCRFORK This ioctl turns the inherit-on-fork flag off. Each child process starts with all tracing flags cleared. This ioctl requires write ac- cess. General Registers The following ioctls are the general registers. PIOCGREG This ioctl retrieves the registers of the saved process from the gregset_t structure that is pointed by the p argument. The register contents are accessible using a set of predefined indices as described under the PIOCSTATUS ioctl. In a multithreaded process, if the task is not stopped on an event of interest (a trace event), the registers are returned for the first thread. If the task is stopped on an event of interest, the registers for the thread that hit the event are returned. (See the pr_tid field as returned by PIOCSTATUS.) The gregset_t structure is described under the PIOCSREG ioctl. PIOCSREG This ioctl sets the registers of the saved process in the gregset_t structure pointed to by the argument. It requires write access. The register contents are accessible using a set of predefined indices as described under the PIOCSTATUS ioctl. This ioctl fails with an EBUSY error if applied to a process that is not stopped on an event of inter- est. struct gregset { long regs[PRC_NREGS]; }; typedef struct gregset gregset_t; PI- OCGFPREG This ioctl retrieves the floating-point registers of a saved process from the fpregset_t structure pointed to by the p argument. The EINVAL error is returned if floating-point hardware is not present on the ma- chine. The fpregset_t structure is displayed under the PIOCSFPREG ioctl. Note that this ioctl is architecture dependent. PIOCSFPREG This ioctl sets the floating-point registers of a saved process in a fpregset_t structure pointed to by the p argument. It requires write access. The EINVAL error is returned if floating-point hardware is not present on the machine. This ioctl fails with an EBUSY error if it is applied to a process that is not stopped on an event of interest. struct fpregset { long regs[PRC_NREGS]; }; typedef struct fpregset fpregset_t; Note that this ioctl is architecture dependent. The PIOCSREG, PIOCGF- PREG, and PIOCSFPREG ioctls can be used only if the task is stopped on an event of interest. In a multithreaded task, the register set that is manipulated is the set associated with the task that hit the trace event. (See the pr_tid field as returned by PIOCSTATUS.) If the task stopped because of a PIOCSTOP ioctl, the registers are those of the first thread. Miscellaneous Requests The following ioctls perform a variety of requests. PIOCPSINFO This ioctl returns miscellaneous information about a process similar to the information returned by the ps command. The p argument is a pointer to a prpsinfo structure containing at least the following fields: char pr_state: /* numeric process state * (see pr_sname) */ char pr_sname; /* printable char representing * pr_state */ char pr_zomb; /* !=0: process terminated * but not waited for */ char pr_nice; /* nice for cpu usage */ u_long pr_flag; /* process flags */ uid_t pr_uid; /* real user id */ gid_t pr_gid; /* real group id */ pid_t pr_pid; /* unique process id */ pid_t pr_ppid; /* process id of parent*/ pid_t pr_pgrp: /* process id of process group * leader */ pid_t pr_sid; /* session id */ long pr_size; /* size of process image in * pages */ long pr_rssize; /* resident set size in pages */ caddr_t pr_wchan; /* wait addr for sleeping * process */ timestruc_t pr_start; /* process start time, * sec+nsec since the * epoch */ timestruc_t pr_time; /* usr+sys time for * this process */ long pr_pri; /* priority, high value = * high priority */ char pr_oldpri; /* old style priority, * low value is high * priority */ char pr_cpu; * cpu usage for scheduling*/ dev_t pr_ttydev; /* controlling tty device * (PRNODEV if none) */ char pr_clname[8]; / *Scheduling class name */ char pr_fname[16]; /* last component of exec'd * pathname */ char pr_psargs[PRARGSIZ]; /* initial characters * of arg list */ Some fields in the prpsinfo structure, such as the pr_state and the pr_flag fields, are system-specific and may not have the same meaning on each version of the operating system. The field pr_cpu is always set to zero. PIOCPSINFO can be applied to a process that has become a zombie, but not all fields are filled in. PIOCNMAP This operation, like the PIOCMAP ioctl, provides information about the memory mappings (virtual address ranges) associated with the traced process. In the int returned by the p argument, this ioctl returns the number of mappings that are currently active. This information can be used to allocate storage that can be used with the PIOCMAP ioctl. You must allocate space for p+1 mappings; see PIOCMAP. PIOCMAP This memory mapping operation returns the list of currently active map- pings. For PIOCMAP, the p argument addresses an array of elements of type prmap_t; one array element (structure) is returned for each map- ping with an additional all-zeroes element to mark the end of the list. (See PIOCNMAP.) typedef_t struct prmap { caddr_t pr_vaddr; /* Virtual address base */ u_long pr_size; /* Size of mapping in bytes */ off_t pr_off; /* Offset into mapped object, * if any */ long pr_mflags; /* Protection and attribute * flags */ long pr_filler[4]; /* Filler for future expansion */ } prmap_t; The following list describes structure members: The pr_vaddr contains the virtual address base (the lower limit) of the mapping within the traced process and the pr_size field contains its size in bytes. The pr_off field specifies the offset within the mapped object (if any) to which the address base is mapped. The pr_mflags field is a bit-mask of protection and attribute flags as follows: MA_READ specifies that mapping is readable by traced process MA_WRITE specifies that mapping is writable by the traced process MA_EXEC specifies that mapping is executable by the traced process The PIOCNMAP ioctl must be called immediately before the PIOCMAP ioctl. PIOCOPENM If this ioctl is called with a NULL value for p, it returns a read-only file descriptor to the disk file from which the process was created. new_fd = ioctl(fd, PIOCOPENM, NULL) PIOCCRED This operation obtains the set of credentials associated with the process. The p argument points to the prcred_t structure where the in- formation from this operation is placed. The pr_ngroups value deter- mines the size of the field that the user must allocate and pass to the PIOCGROUPS ioctl. typedef struct prcred { uid_t pr_euid; /* contains effective user id */ uid_t pr_ruid; /* contains real user id */ uid_t pr_suid; /* contains saved user id * (from exec) */ uid_t pr_egid; /* contains effective group id */ uid_t pr_rgid; /* contains real group id */ uid_t pr_sgid; /* contains saved group id * (from exec) */ u_int pr_ngroups; /* number of supplementary groups */ } pr- cred_t; PIOCGROUPS Fetch the set of supplementary group IDs that are associated with the process. The p argument points to an array of elements of type uid_t that are to be filled by the operation. Note that the PIOCCRED ioctl must be applied beforehand to determine the number of groups (pr_ngroups) that are returned and the amount of storage that should be allocated to hold them. PIOCSSPCACT This ioctl is referred to as "set special action" and requires write access. It is used to enable or disable tracing of certain process control functions. The p argument contains a mask that consists of the following values (note that a zero value disables all tracing). The pr_why and pr_what values are the same as those described under the PI- OCSTATUS ioctl. PRFS_STOPTCR sets a condition called stop-on-thread-create. This will cause the task in which a new thread is created by a user level call to thread_create() to stop on an event of interest before the new thread has executed any user level code. Setting this flag will not cause a task stop when a fork() system call creates a new thread. pr_why is set to PR_TCRSTOP, and pr_what is set to the thread ID of the newly created thread. The PIOCRUN ioctl should be used to restart the task. PRFS_STOPTTERM sets a condition called stop-on-thread-terminate. This will cause a task stop whenever any of its threads enters the kernel thread_terminate() routine because of a user level call to thread_ter- minate(). pr_why is set to PR_TTSTOP, and pr_what is set to the thread ID of the terminating thread. The PIOCRUN ioctl should be used to restart the task. (The last thread of an exiting process does not cause a task stop if stop-on-thread-terminate is set. PRFS_KOLC sets the kill-on-last-close flag in the traced process. This flag is off by default. If the flag is set, the traced process is ter- minated by a SIGKILL signal when the last /proc file descriptor refer- ring to the traced process is closed. This action occurs even if the traced process is stopped on a trace event. All further tracing is disabled. If set, PRFS_KOLC overrides the run-on-last-close flag; see the description of the PIOCSRLC ioctl. PIOCGSPCACT This ioctl is referred to as "get special actions". It is used to re- turn, in the address pointed to by the p argument, the latest mask value that was set by the PIOCSSPCACT ioctl. User code can invoke this ioctl to get the current mask setting. It can then OR in bits to be set, and/or AND out bits to be cleared; the PIOCSSPCACT can then be called with the modified mask to affect the desired change in tracing. PIOCNTHR, PIOCTLIST These ioctls are used to list the thread IDs of all the threads in a task. PIOCNTHR must be called first; it lets the user know how large a buffer it must pass to the PIOCTLIST ioctl, and tells the kernel code the max number of thread IDs to return via the PIOCTLIST ioctl. If PI- OCNTHR is not invoked first, PIOCTLIST returns error EINVAL. PIOCNTHR takes a pointer to an int, and PIOCTLIST expects a pointer to an array of tid_t (pointers to struct thread). Note that if the task is not stopped, the actual number of threads in the task may change in the time between the invocation of PIOCNTHR and PIOCTLIST. The actual list of threads returned by PIOCTLIST will be less than or equal to the value returned by PIOCNTHR. To get around this, the task could be stopped (by PIOCSTOP for example) before PIOCNTHR is invoked, and restarted by PIOCRUN after PIOCTLISL has completed. Usage: ioctl(fd, PIOCNTHR, p) where p is (int *p) ioctl(fd, PIOCTLIST, p) where p is (tid_t p) Thread-Specific ioctls In a multithreaded program, user code must be able to identify which thread or threads to examine or manipulate. Each user process is com- posed of a task, which contains one or more threads; For each thread in a task, a thread ID is returned to the user via /proc ioctls. This ID is also passed to the kernel by user ioctls to identify which thread in a task to manipulate. With the exception of PIOCTLIST, the thread specific ioctls (PIOCTxxx) can operate on one or more threads. These ioctls are invoked in the context of a process, just like the "base" ioctls. For example, if process 123 is opened via /proc -- fd=open("/proc/123", O_RDWR), then ioctl(fd, PIOCTSTATUS, p) could be used to return status for 1 or more of its threads. However, unlike the "base" ioctls, which take the address of a fixed length entity for parameter p, the PIOCTxxx ioctls use p to specify the address of a buffer that varies in length, depending on the number of threads that are to be operated on. Also, the PIOCTxxx ioctls always require a valid p parameter -- because, the p parameter contains the number of threads to operate on, and their IDs (even if the number is 1). The structure, struct prthreads, which is defined in <sys/procfs.h>, is used as a common "header" for each of the PIOCTxxx ioctls. struct prthreads { long pr_count; /* number of threads to operate on * written by user, read by kernel */ tid_t pr_error_thread; /* if error, the ID of the thread * causing the error is written here * by the kernel */ char pr_data[1]; /* this is a place holder, its * address is used as the start of * the list of ioctl specific data * structures */ }; If a thread-specific ioctl() call returns error status, the ID of the thread on which the error was detected is returned in pr_error_thread. When the kernel code detects an error, ioctl processing stops. This means that the ioctl actions succeeded for each thread in the specified list that proceeded the thread for which the error was reported. No ioctl action is attempted for any remaining threads in the list after an error is detected. If a failure is encountered that is not related to a specific thread the pr_error_thread value will be returned as 0. If a specified thread is not found in the task->thread_list, error EBADF is returned. This is common to all of the PIOCTxxx ioctls. PIOCTSTOP, PIOCTSTATUS PIOCTSTOP stops the specified thread(s) and returns status in the spec- ified prstatus structure(s); PIOCTSTATUS just returns status. The PI- OCTSTOP ioctl requires write access. These ioctls use the same status structure, prstatus, that is used by the "base" PIOCSTOP and PIOCSTATUS ioctls. Unlike PIOCSTOP, a prstatus structure must always be specified for PI- OCTSTOP. A thread is selected by filling in the pr_tid field of the prstatus structure. (See the comment for the thread_1 entry below.) Usage: ioctl(fd, PIOCTSTOP, p) ioctl(fd, PIOCTSTATUS, p) The buffer pointed to by p for both these ioctls is as follows: long pr_count; /* number of threads in list */ tid_t pr_error_thread; /* thread ID if er- ror */ struct prstatus thread_1; /* "selected" thread is in * thread_1.pr_tid */ . . . struct prstatus thread_N; /* thread_N.pr_tid contains ID of last * thread to stop (PIOCTSTOP) or return * status for (PIOCTSTATUS) */ PIOCTRUN This ioctl is used to run one or more threads that are stopped via PI- OCTSTOP. This ioctl provides the same functionality for the specified thread(s) as the "base" PIOCRUN ioctl provides for the process/task, except that the PRCSIG, PRCFAULT and PRSHOLD flags of prrun.pr_flags are not recognized. This ioctl requires write access. Unlike PIOCRUN, a prrun structure must always be specified for PIOC- TRUN. A thread is selected by filling in the pr_tid field of the prrun structure. The PIOCTRUN ioctl does provide the same functionality as the PIOCRUN ioctl with a NULL p pointer if the prrun.pr_flags field is set to 0. If a specified thread is not stopped via PIOCTSTOP, error EBUSY is re- turned. If any error is detected while attempting to run a thread, the ioctl code returns; any threads in the list before the error will have been started, any threads in the list after the thread in error will not have been started. Usage: ioctl(fd, PIOCTRUN, p) The buffer pointed to by p has the following format: long pr_count; /* number of threads to run */ tid_t pr_error_thread; /* set by kernel if error is detected */ struct prrun thread_1; /* prrun struct, containing thread ID of * 1st thread to run in thread_1.pr_tid */ . . . struct prrun thread_N; /* prrun.pr_tid contains ID of last * thread to run in thread_N.pr_tid */ PIOCTSSIG This ioctl allows the "current signal" to be cleared or changed to some other signal, only if the specified thread(s) is stopped on an event of interest. This ioctl requires write access. Usage: ioctl(fd, PIOCTSSIG, p) The buffer pointed to by p has the following format: long pr_count; /* number of threads specified */ tid_t pr_error_thread; /* thread ID if er- ror */ tsiginfo_t thread_1; /* first thread to act on */ tsiginfo_t thread_N; /* last thread to act on */ tsiginfo_t is defined in <sys/procfs.h> and has the following format: typedef struct tsiginfo { siginfo_t pr_siginfo; /* the actual siginfo structure */ tid_t pr_tid; /* the thread ID to act upon */ } tsiginfo_t; /* note, this is not a pointer */ PIOCTKILL This ioctl allows a signal to be sent to a specified thread. Multiple threads can be specified, and a different signal can be sent to each specified thread. Sending SIGKILL kill a thread immediately. This ioctl requires write access. Usage: ioctl(fd, PIOCTKILL, p) The buffer pointed to by p has the following format: long pr_count; /* number of threads specified */ tid_t pr_error_thread; /* thread ID if er- ror */ tsignal_t thread_1; /* first thread to act on */ tsignal_t thread_N; /* last thread to act on */ tsignal_t is defined in <sys/procfs.h> and has the following format: typedef struct tsignal { int pr_signal; /* the signal to send */ tid_t pr_tid; /* the thread ID to act upon */ } tsignal_t; /* note, this is not a pointer */ PIOCTUNKILL This ioctl allows a thread-specific signal that is pending for a speci- fied thread to be deleted from the list of pending signals. Multiple threads can be specified, and a different signal can be removed from each specified thread. The current signals for those specified threads are unaffected. This ioctl requires write access. Usage: ioctl(fd, PIOCTUNKILL, p) The buffer pointed to by p has the following format: long pr_count; /* number of threads specified */ tid_t pr_error_thread; /* thread ID if er- ror */ tsignal_t thread_1; /* first thread to act on */ tsignal_t thread_N; /* last thread to act on */ tsignal_t is defined in <sys/procfs.h> and has the following format: typedef struct tsignal { int pr_signal; /* the signal to remove */ tid_t pr_tid; /* the thread ID to act upon */ } tsignal_t; /* note, this is not a pointer */ PIOCTGFPREG, PIOCTSFPREG* These ioctls are used to get and set the Floating Point registers for the specified thread(s); they perform the same type of functions as the "base" ioctls PIOCGFPREG and PIOCSFPREG. The PIOCTSFPREG* ioctl re- quires write access. For PIOCTGFPREG, if the FP hardware had not been in use (pcb_ownedfp is NULL) all NULLs are returned. If a specified thread is not stopped on an event of interest, error EBUSY is returned. For PIOCTSFPREG, if a specified thread is not stopped on an event of interest, error EBUSY is returned. No check is made to see if the FP hardware had been in use. Usage: ioctl(fd, PIOCTGFPREG, p) ioctl(fd, PIOCTSFPREG, p) The buffer pointed to by p has the following format: long pr_count; /* number of threads specified */ tid_t pr_error_thread; /* thread ID if er- ror */ tfpregset_t thread_1; /* first thread to act on */ tfpregset_t thread_N; /* last thread to act on */ tfpregset_t is defined in <sys/procfs.h> and has the following format: struct tfpregset { fpregset_t pr_fpregs; /* floating point registers */ tid_t pr_tid; /* the thread ID to act upon */ }; typedef struct tfpregset tf- pregset_t; PIOCTGREG, PIOCTSREG These ioctls are used to get and set the general registers for the specified thread(s); they perform the same type of functions as the "base" ioctls PIOCGREG and PIOCSREG. The PIOCTSREG ioctl requires write access. For PIOCTSREG, if a specified thread is not stopped on an event of in- terest, error EBUSY is returned. Usage: ioctl(fd, PIOCTGREG, p) ioctl(fd, PIOCTSREG, p) The buffer pointed to by p has the following format: long pr_count; /* number of threads specified */ tid_t pr_error_thread; /* thread ID if er- ror */ tgregset_t thread_1; /* first thread to act on */ tgregset_t thread_N; /* last thread to act on */ tgregset_t is defined in <sys/procfs.h> and has the following format: struct tgregset { gregset_t pr_regs; /* general registers */ tid_t pr_tid; /* the thread ID to act upon */ }; typedef struct tgregset tgregset_t; NOTICES To wait for one or more processes to stop, /proc file descriptors can be used in a poll(2) system call. POLLPRI event is used to specify waiting for a process or one of its thread to stop on an event of in- terest. When requested and returned, the polling event POLLPRI indi- cates that the process or one of its thread has stopped on an event of interest. The polling events POLLHUP, POLLERR and POLLNVAL may be re- turned as well. POLLHUP indicates that the process has terminated. POLLERR indicates that the file descriptor has become invalid. POLL- NVAL is returned immediately if POLLPRI is requested on a file descrip- tor referring to a system process. select(2) system call can be used in a similar way. When used in a select(2) system call, the exceptfds pa- rameter (see select(2)) is used to specify which file descriptors are to be checked. A positive indication is returned if the process, cor- responding to the open file descriptor, has stopped on an event of in- terest. If PIOCTSTOP is invoked for a thread, and the thread is successfully stopped, the thread can be restarted only via PIOCTRUN; PIOCRUN will have no effect on it. All other stops on events of interest must restarted via PIOCRUN. Descriptions of structures in the document include only interesting structure elements, and may show elements out of order for descriptive clarity. The actual structure definitions are contained in <sys/procfs.h>. ERRORS Errors that can be set in addition to the errors normally associated with file system access: The file does not exist, or its corresponding process has terminated after being opened. An I/O or ioctl operation requiring write access was attempted on a file descriptor not open for writing. PIOCRUN, PIOCTRUN, PIOCSREG, PIOCTSREG or PIOCSFPREG, PI- OCTSFPREG was applied to a process or one of its threads not stopped on an event of interest; an exclusive open(2) was attempted on a process file already open for writing; an open(2) for writing was at- tempted and an exclusive open is in effect on the process file; an at- tempt was made to mount /proc file system when it is already mounted. The calling process does not have appropriate privilege. An attempt was made to perform an unsupported operation by /proc file system In- valid argument was supplied to a system call. A non-exhaustive list of conditions can cause the error includes: an ioctl operation was issued on a file descriptor referring to the /proc directory; the ioctl com- mand is undefined. The operation failed because the traced process has performed an exec(2) of a setuid/setgid object file or of an object file that it cannot read; all further operations (except close(2)) on the file descriptor will fail with this error. A signal was received by the controlling process while waiting for the traced process to stop. An I/O or ioctl request referred to an invalid address in the controlling process. An I/O or ioctl request referred to an invalid address in the traced process. FILES Contains the directory listing of active processes Contains the process image RELATED INFORMATION Functions: intro(2), open(2), close(2), ioctl(2), poll(2), read(2), write(2), sigaction(2), signal(2), siginfo(5). delim off proc(4)