home *** CD-ROM | disk | FTP | other *** search
Text File | 2001-04-17 | 90.2 KB | 1,651 lines
pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) NNNNAAAAMMMMEEEE proc - process (debug) filesystem SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////pppprrrrooooccccffffssss....hhhh>>>> DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN /_p_r_o_c is a filesystem that provides access to the image of each active process in the system. This was historically mounted as /_d_e_b_u_g. /_p_r_o_c does not consume any disk resources. This interface provides a richer set of functionality and replaces the now obsolete _d_b_g(4), _d_e_b_u_g(4) interface. The "files" of this filesystem are of the form /_p_r_o_c/_n_n_n_n_n and /_p_r_o_c/_p_i_n_f_o/_n_n_n_n_n, where _n_n_n_n_n is a decimal number corresponding to the process-ID. These files actually consume no disk space, and are only convenient handles by which a debugger can attach to a process. The owner of each ``file'' is determined by the process's user-ID. Files of the form /_p_r_o_c/_n_n_n_n_n have permission mode 0600 while files of the form /_p_r_o_c/_p_i_n_f_o/_n_n_n_n_n have permission mode 0444. The /_p_r_o_c/_p_i_n_f_o files are intended for use by unprivileged programs that wish to access miscellaneous process information such as that provided by _p_s(1) and _t_o_p(1). The _s_t_a_t_f_s(2) system call will return valid information concerning the pppprrrroooocccc filesystem. The total and free blocks as reported by _d_f(1) respectively represent the total virtual memory (real memory plus swap space) available and currently free. Standard system call interfaces are used to access /_p_r_o_c files: _o_p_e_n(2), _c_l_o_s_e(2), _r_e_a_d(2), _w_r_i_t_e(2), and _i_o_c_t_l(2). Note that _r_e_a_d(2) and _w_r_i_t_e(2) are not allowed for /_p_r_o_c/_p_i_n_f_o files. Furthermore only the PPPPIIIIOOOOCCCCAAAACCCCIIIINNNNFFFFOOOO, PPPPIIIIOOOOCCCCPPPPSSSSIIIINNNNFFFFOOOO, PPPPIIIIOOOOCCCCUUUUSSSSAAAAGGGGEEEE, PPPPIIIIOOOOCCCCGGGGEEEETTTTPPPPTTTTIIIIMMMMEEEERRRR and PPPPIIIIOOOOCCCCCCCCRRRREEEEDDDD commands may be specified to _i_o_c_t_l(2) for /_p_r_o_c/_p_i_n_f_o files. An open for reading and writing enables process control; a read-only open allows inspection but not control. As with ordinary files, more than one process can open the same /_p_r_o_c file at the same time. _E_x_c_l_u_s_i_v_e _o_p_e_n is provided to allow controlling processes to avoid collisions: an _o_p_e_n(2) for writing that specifies O_EXCL fails if the file is already open for writing; if such an exclusive open succeeds, subsequent attempts to open the file for writing, with or without the O_EXCL flag, fail until the exclusively- opened file descriptor is closed. (Exception: a superuser _o_p_e_n(2) that does not specify O_EXCL succeeds even if the file is exclusively opened.) There can be any number of read-only opens, even when an exclusive write open is in effect on the file. On a successful open the inherit-on-fork (PR_FORK) and run-on-last-close (PR_RLC) flags are set by default, if no other process has the file open. On the last close for writing, if the kill-on-last-close (PR_KLC) or the PR_RLC flags are set, then all the controlling flags are cleared and either a SIGKILL is sent to the process or the process is set running again. If neither of the above two flags are set, the controlling flags are not cleared. PPPPaaaaggggeeee 1111 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) Data may be transferred from or to any locations in the traced process's address space by applying _l_s_e_e_k(2) to position the file at the virtual address of interest followed by _r_e_a_d(2) or _w_r_i_t_e(2). The PIOCMAP operation can be applied to determine the accessible areas (mappings) of the address space. A contiguous area of the address space may appear as multiple mappings due to varying read/write/execute permissions. I/O transfers may span contiguous mappings. An I/O request extending into an unmapped area is truncated at the boundary. Information and control operations are provided through _i_o_c_t_l(2). These have the form: #include <sys/types.h> #include <sys/signal.h> #include <sys/fault.h> #include <sys/syscall.h> #include <sys/procfs.h> void *p; retval = ioctl(fildes, code, p); The argument _p is a generic pointer whose type depends on the specific _i_o_c_t_l code. Where not specifically mentioned below, its value should be zero. <_s_y_s/_p_r_o_c_f_s._h> contains definitions of _i_o_c_t_l codes and data structures used by the operations. Process information and control operations involve the use of sets of flags. The set types ssssiiiiggggsssseeeetttt____tttt, ffffllllttttsssseeeetttt____tttt, and ssssyyyysssssssseeeetttt____tttt correspond, respectively, to signal, fault, and system call enumerations defined in <_s_y_s/_s_i_g_n_a_l._h>, <_s_y_s/_f_a_u_l_t._h>, and <_s_y_s/_s_y_s_c_a_l_l._h>. Each set type is large enough to hold flags for its own enumeration. Although they are of different sizes, they have a common structure and can be manipulated by these macros: prfillset(&set); /* turn on all flags in set */ premptyset(&set); /* turn off all flags in set */ praddset(&set, flag); /* turn on the specified flag */ prdelset(&set, flag); /* turn off the specified flag */ r = prismember(&set, flag); /* != 0 iff flag is turned on */ One of pppprrrrffffiiiillllllllsssseeeetttt() or pppprrrreeeemmmmppppttttyyyysssseeeetttt() must be used to initialize sssseeeetttt before it is used in any other operation. ffffllllaaaagggg must be a member of the enumeration corresponding to sssseeeetttt. IIIIOOOOCCCCTTTTLLLL CCCCOOOODDDDEEEESSSS The allowable _i_o_c_t_l codes follow. Certain of these can be used only if the process file descriptor is open for writing; these include all operations that affect process control. Those requiring write access are marked with an asterisk (*). Except where noted, an _i_o_c_t_l to a process that has terminated elicits the error ENOENT. PPPPaaaaggggeeee 2222 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) PPPPIIIIOOOOCCCCSSSSTTTTAAAATTTTUUUUSSSS PIOCSTATUS returns status information for the process; _p is a pointer to a pppprrrrssssttttaaaattttuuuussss structure containing at least the following fields: typedef struct prstatus { long pr_flags; /* Flags */ short pr_why; /* Reason for stop (if stopped) */ short pr_what; /* More detailed reason */ short pr_cursig; /* Current signal */ sigset_t pr_sigpend; /* Set of pending signals */ sigset_t pr_sighold; /* Set of held signals */ struct siginfo pr_info; /* Info associated with signal/fault */ struct sigaltstack pr_altstack; /* Alternate signal stack info */ struct sigaction pr_action;/* Signal action for current signal */ short pr_syscall; /* System call # (if in syscall) */ short pr_nsysarg; /* # of arguments to this syscall */ long pr_errno; /* Error number from system call */ long pr_rval1; /* System call return value 1 */ long pr_rval2; /* System call return value 2 */ long pr_sysarg[PRSYSARGS]; /* Arguments to this syscall */ pid_t pr_pid; /* Process id */ pid_t pr_ppid; /* Parent process id */ pid_t pr_pgrp; /* Process group id */ pid_t pr_sid; /* Session id */ timespec_t pr_utime; /* Process user cpu time */ timespec_t pr_stime; /* Process system cpu time */ timespec_t pr_cutime; /* Sum of children's user times */ timespec_t pr_cstime; /* Sum of children's system times */ char pr_clname[8]; /* Scheduling class name */ long pr_instr; /* Current instruction */ gregset_t pr_reg; /* General registers */ } prstatus_t; pppprrrr____ffffllllaaaaggggssss is a bit-mask holding these flags: PPPPRRRR____SSSSTTTTOOOOPPPPPPPPEEEEDDDD Process is stopped PPPPRRRR____IIIISSSSTTTTOOOOPPPP Process is stopped on an event of interest (see PIOCSTOP). PPPPRRRR____DDDDSSSSTTTTOOOOPPPP Process has a stop directive in effect (see PIOCSTOP). PPPPRRRR____SSSSTTTTEEEEPPPP Process has a single-step directive in effect (see PIOCRUN). PPPPRRRR____AAAASSSSLLLLEEEEEEEEPPPP Process is in an interruptible sleep within a system call. PPPPRRRR____PPPPCCCCIIIINNNNVVVVAAAALLLL Process's current instruction (pppprrrr____iiiinnnnssssttttrrrr) is undefined. PPPPaaaaggggeeee 3333 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) PPPPRRRR____IIIISSSSSSSSYYYYSSSS Process is a system process (see PIOCSTOP). PPPPRRRR____FFFFOOOORRRRKKKK Process has its inherit-on-fork flag set (see PIOCSET). PPPPRRRR____RRRRLLLLCCCC Process has its run-on-last-close flag set (see PIOCSET). PPPPRRRR____KKKKLLLLCCCC Process has its kill-on-last-close flag set (see PIOCSET). PPPPRRRR____PPPPTTTTRRRRAAAACCCCEEEE Process is being traced via _p_t_r_a_c_e(2). pppprrrr____wwwwhhhhyyyy and pppprrrr____wwwwhhhhaaaatttt together describe, for a stopped process, the reason that the process is stopped. Possible values of pppprrrr____wwwwhhhhyyyy are: PPPPRRRR____RRRREEEEQQQQUUUUEEEESSSSTTTTEEEEDDDD The stop occurred in response to a stop directive, normally because PIOCSTOP was applied. pppprrrr____wwwwhhhhaaaatttt is unused in this case. PPPPRRRR____SSSSIIIIGGGGNNNNAAAALLLLLLLLEEEEDDDD The process stopped on receipt of a signal (see PIOCSTRACE); pppprrrr____wwwwhhhhaaaatttt holds the signal number that caused the stop (for a newly-stopped process, the same value is in pppprrrr____ccccuuuurrrrssssiiiigggg). PPPPRRRR____FFFFAAAAUUUULLLLTTTTEEEEDDDD The process stopped on incurring a hardware fault (see PIOCSFAULT); pppprrrr____wwwwhhhhaaaatttt holds the fault number that caused the stop. PPPPRRRR____SSSSYYYYSSSSEEEENNNNTTTTRRRRYYYY and PPPPRRRR____SSSSYYYYSSSSEEEEXXXXIIIITTTT A stop on entry to or exit from a system call (see PIOCSENTRY and PIOCSEXIT); pppprrrr____wwwwhhhhaaaatttt holds the system call number. PPPPRRRR____JJJJOOOOBBBBCCCCOOOONNNNTTTTRRRROOOOLLLL The process stopped due to the default action of a job control stop signal (see _s_i_g_a_c_t_i_o_n(2)); pppprrrr____wwwwhhhhaaaatttt holds the stopping signal number. pppprrrr____ccccuuuurrrrssssiiiigggg names the current signal, that is, the next signal to be delivered to the process. pppprrrr____ssssiiiiggggppppeeeennnndddd identifies any other signals pending for the process. pppprrrr____ssssiiiigggghhhhoooolllldddd identifies those signals whose delivery is being delayed if sent to the process. pppprrrr____iiiinnnnffffoooo, when the process is in a PR_SIGNALLED or PR_FAULTED stop, contains additional information pertinent to the particular signal or fault (see <_s_y_s/_s_i_g_i_n_f_o._h>). pppprrrr____aaaallllttttssssttttaaaacccckkkk contains the alternate signal stack information for the process (see _s_i_g_a_l_t_s_t_a_c_k(2)). pppprrrr____aaaaccccttttiiiioooonnnn contains the signal action information pertaining to the current signal (see _s_i_g_a_c_t_i_o_n(2)); it is undefined if pppprrrr____ccccuuuurrrrssssiiiigggg is zero. PPPPaaaaggggeeee 4444 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) pppprrrr____ssssyyyyssssccccaaaallllllll is the number of the system call, if any, being executed by the traced process; it is non-zero if the process is stopped on PR_SYSENTRY or PR_SYSEXIT, is asleep within a system call (PR_ASLEEP is set), or is stopped on a watchpoint trap incurred within a system call (see PIOCSWATCH). If pppprrrr____ssssyyyyssssccccaaaallllllll is non-zero, pppprrrr____nnnnssssyyyyssssaaaarrrrgggg is the number of arguments to the system call and the pppprrrr____ssssyyyyssssaaaarrrrgggg array contains the actual arguments; pppprrrr____eeeerrrrrrrrnnnnoooo contains the value of eeeerrrrrrrrnnnnoooo returned at the last system call; and pppprrrr____rrrrvvvvaaaallll1111 and pppprrrr____rrrrvvvvaaaallll2222 contain the return values from the last system call. pppprrrr____ppppiiiidddd, pppprrrr____ppppppppiiiidddd, pppprrrr____ppppggggrrrrpppp, and pppprrrr____ssssiiiidddd are, respectively, the process id, the id of the process's parent, the process's process group id, and the process's session id. pppprrrr____uuuuttttiiiimmmmeeee, pppprrrr____ssssttttiiiimmmmeeee, pppprrrr____ccccuuuuttttiiiimmmmeeee, and pppprrrr____ccccssssttttiiiimmmmeeee are, respectively, the user CPU and system CPU time consumed by the process, and the cumulative user CPU and system CPU time consumed by the process's children, in seconds and nanoseconds. pppprrrr____ccccllllnnnnaaaammmmeeee contains the name of the process's scheduling class. pppprrrr____iiiinnnnssssttttrrrr contains the machine instruction to which the program counter refers. The amount of data retrieved from the process is machine- dependent; on SGI machines, it is a 32-bit word. In general, the size is that of the machine's smallest instruction. If PR_PCINVAL is set, pppprrrr____iiiinnnnssssttttrrrr is undefined; this occurs whenever the process is not stopped or when the program counter refers to an invalid address. pppprrrr____rrrreeeegggg is an array holding the contents of the general registers for a stopped process. For SGI machines the structure ggggrrrreeeeggggsssseeeetttt____tttt is defined in <_s_y_s/_u_c_o_n_t_e_x_t._h>. If the process is not stopped, register values are undefined. ****PPPPIIIIOOOOCCCCSSSSTTTTOOOOPPPP PPPPIIIIOOOOCCCCWWWWSSSSTTTTOOOOPPPP PIOCSTOP directs the process to stop and waits until it has stopped; PIOCWSTOP simply waits for the process to stop. These operations complete when the process stops on an event of interest, immediately if already so stopped. If _p is non-zero it points to an instance of pppprrrrssssttttaaaattttuuuussss____tttt to be filled with status information for the stopped process. An ``event of interest'' is either a PR_REQUESTED stop or a stop that has been specified in the process's tracing flags (set by PIOCSTRACE, PIOCSFAULT, PIOCSENTRY, and PIOCSEXIT). A PR_JOBCONTROL stop is specifically not an event of interest. (A process may stop twice due to a stop signal, first showing PR_SIGNALLED if the signal is traced and again showing PR_JOBCONTROL if the process is set running without clearing the signal.) If the process is controlled by _p_t_r_a_c_e(2), it comes to a PR_SIGNALLED stop on receipt of any signal; this is an event of interest only if the signal is in the traced signal set. If PIOCSTOP is applied to a process that is stopped, but not on an event of interest, the stop directive takes effect when the process is restarted by the competing mechanism; at that time the process enters a PR_REQUESTED stop PPPPaaaaggggeeee 5555 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) before executing any user-level code. _i_o_c_t_l()s are interruptible by signals so that, for example, an _a_l_a_r_m(2) can be set to avoid waiting forever for a process that may never stop on an event of interest. If PIOCSTOP is interrupted, the stop directive remains in effect even though the _i_o_c_t_l() returns an error. A system process (indicated by the PR_ISSYS flag) never executes at user level, has no user-level address space visible through /_p_r_o_c, and cannot be stopped. Applying PIOCSTOP or PIOCWSTOP to a system process elicits the error EBUSY. ****PPPPIIIIOOOOCCCCRRRRUUUUNNNN The traced process is made runnable again after a stop. If _p is non-zero it points to a pppprrrrrrrruuuunnnn structure describing additional actions to be performed. The pppprrrrrrrruuuunnnn structure contains at least the following fields: typedef struct prrun { long pr_flags; /* Flags */ sigset_t pr_trace; /* Set of signals to be traced */ sigset_t pr_sighold; /* Set of signals to be held */ fltset_t pr_fault; /* Set of faults to be traced */ caddr_t pr_vaddr; /* Virtual address at which to resume */ } prrun_t; pppprrrr____ffffllllaaaaggggssss is a bit-mask describing optional actions; the remainder of the entries are meaningful only if the appropriate bits are set in pppprrrr____ffffllllaaaaggggssss. Flag definitions: PPPPRRRRCCCCSSSSIIIIGGGG Clears the current signal, if any (see PIOCSSIG). PPPPRRRRCCCCFFFFAAAAUUUULLLLTTTT Clears the current fault, if any (see PIOCCFAULT). PPPPRRRRSSSSTTTTRRRRAAAACCCCEEEE Sets the traced signal set to pppprrrr____ttttrrrraaaacccceeee (see PIOCSTRACE). PPPPRRRRSSSSHHHHOOOOLLLLDDDD Sets the held signal set to pppprrrr____ssssiiiigggghhhhoooolllldddd (see PIOCSHOLD). PPPPRRRRSSSSFFFFAAAAUUUULLLLTTTT Sets the traced fault set to pppprrrr____ffffaaaauuuulllltttt (see PIOCSFAULT). PPPPRRRRSSSSVVVVAAAADDDDDDDDRRRR Sets the address at which execution resumes to pppprrrr____vvvvaaaaddddddddrrrr. PPPPRRRRSSSSTTTTEEEEPPPP Directs the process to single-step, that is, to run and to execute a single machine instruction. On completion of the instruction, a trace trap occurs. If FLTTRACE is being traced, the process stops, otherwise it is sent SIGTRAP; if SIGTRAP is being traced and not held, the process stops. This operation requires hardware and operating system PPPPaaaaggggeeee 6666 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) support and may not be implemented on all processors. It is implemented on SGI machines. PPPPRRRRCCCCSSSSTTTTEEEEPPPP Cancels any outstanding single-step directive and any PPPPRRRRSSSSTTTTEEEEPPPP directive set in the current request. PPPPRRRRSSSSAAAABBBBOOOORRRRTTTT Meaningful only if the process is in a PR_SYSENTRY stop or is marked PR_ASLEEP; it instructs the process to abort execution of the system call (see PIOCSENTRY, PIOCSEXIT). PPPPRRRRSSSSTTTTOOOOPPPP Directs the process to stop again as soon as possible after resuming execution (see PIOCSTOP). In particular if the process is stopped on PR_SIGNALLED or PR_FAULTED, the next stop will show PR_REQUESTED, no other stop will have intervened, and the process will not have executed any user- level code. PIOCRUN fails (EBUSY) if applied to a process that is not stopped on an event of interest. Once PIOCRUN has been applied, the process is no longer stopped on an event of interest even if, due to a competing mechanism, it remains stopped. ****PPPPIIIIOOOOCCCCSSSSTTTTRRRRAAAACCCCEEEE This 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 via an instance of ssssiiiiggggsssseeeetttt____tttt addressed by _p. Receipt of SIGKILL cannot be traced. 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 PIOCSHOLD or the PRSHOLD option of PIOCRUN. PPPPIIIIOOOOCCCCGGGGTTTTRRRRAAAACCCCEEEE The current traced signal set is returned in an instance of ssssiiiiggggsssseeeetttt____tttt addressed by _p. ****PPPPIIIIOOOOCCCCSSSSSSSSIIIIGGGG The current signal and its associated signal information are set according to the contents of the ssssiiiiggggiiiinnnnffffoooo structure addressed by _p (see <_s_y_s/_s_i_g_i_n_f_o._h>). If the specified signal number is zero or if _p is zero, the current signal is cleared. Setting the current signal to SIGKILL terminates the process immediately, even if it is stopped. All other signals will be sent after the process is made runnable, if it is currently stopped. ****PPPPIIIIOOOOCCCCKKKKIIIILLLLLLLL A signal is sent to the process with semantics identical to those of _k_i_l_l(2). _p points to an _i_n_t naming the signal. Sending SIGKILL PPPPaaaaggggeeee 7777 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) terminates the process immediately. ****PPPPIIIIOOOOCCCCUUUUNNNNKKKKIIIILLLLLLLL A signal is deleted, that is, it is removed from the set of pending signals. The current signal (if any) is unaffected. _p points to an _i_n_t naming the signal. It is an error to attempt to delete SIGKILL. PPPPIIIIOOOOCCCCGGGGHHHHOOOOLLLLDDDD ****PPPPIIIIOOOOCCCCSSSSHHHHOOOOLLLLDDDD PIOCGHOLD returns the set of held signals (signals whose delivery will be delayed if sent to the process) in an instance of ssssiiiiggggsssseeeetttt____tttt addressed by _p. PIOCSHOLD correspondingly sets the held signal set but does not allow SIGKILL or SIGSTOP to be held. PPPPIIIIOOOOCCCCMMMMAAAAXXXXSSSSIIIIGGGG PPPPIIIIOOOOCCCCAAAACCCCTTTTIIIIOOOONNNN These operations provide information about the signal actions associated with the traced process (see _s_i_g_a_c_t_i_o_n(2)). PIOCMAXSIG returns, in the _i_n_t addressed by _p, the maximum signal number understood by the system. This can be used to allocate storage for use with the PIOCACTION operation, which returns the traced process's signal actions in an array of ssssiiiiggggaaaaccccttttiiiioooonnnn structures addressed by _p. 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. ****PPPPIIIIOOOOCCCCSSSSFFFFAAAAUUUULLLLTTTT This defines a set of hardware faults to be traced: on incurring one of these faults the traced process stops. The set is defined via an instance of ffffllllttttsssseeeetttt____tttt addressed by _p. Fault names are defined in <_s_y_s/_f_a_u_l_t._h> and include the following. Some of these may not occur on all processors; there may be processor-specific faults in addition to these. FFFFLLLLTTTTIIIILLLLLLLL illegal instruction FFFFLLLLTTTTPPPPRRRRIIIIVVVV privileged instruction FFFFLLLLTTTTBBBBPPPPTTTT breakpoint trap FFFFLLLLTTTTTTTTRRRRAAAACCCCEEEE trace trap FFFFLLLLTTTTWWWWAAAATTTTCCCCHHHH watchpoint trap FFFFLLLLTTTTKKKKWWWWAAAATTTTCCCCHHHH kernel watchpoint trap FFFFLLLLTTTTAAAACCCCCCCCEEEESSSSSSSS memory access fault FFFFLLLLTTTTBBBBOOOOUUUUNNNNDDDDSSSS memory bounds violation FFFFLLLLTTTTIIIIOOOOVVVVFFFF integer overflow FFFFLLLLTTTTIIIIZZZZDDDDIIIIVVVV integer zero divide FFFFLLLLTTTTFFFFPPPPEEEE floating-point exception FFFFLLLLTTTTSSSSTTTTAAAACCCCKKKK unrecoverable stack fault FFFFLLLLTTTTPPPPAAAAGGGGEEEE recoverable page 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 PIOCRUN. FLTPAGE and FLTKWATCH are exceptions; no signal is posted. There may be additional processor-specific faults like this. pppprrrr____iiiinnnnffffoooo in the pppprrrrssssttttaaaattttuuuussss structure identifies the signal to be sent and contains machine-specific PPPPaaaaggggeeee 8888 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) information about the fault. PPPPIIIIOOOOCCCCGGGGFFFFAAAAUUUULLLLTTTT The current traced fault set is returned in an instance of ffffllllttttsssseeeetttt____tttt addressed by _p. ****PPPPIIIIOOOOCCCCCCCCFFFFAAAAUUUULLLLTTTT The current fault (if any) is cleared; the associated signal is not sent to the process. ****PPPPIIIIOOOOCCCCSSSSEEEENNNNTTTTRRRRYYYY ****PPPPIIIIOOOOCCCCSSSSEEEEXXXXIIIITTTT These operations instruct the process to stop on entry to or exit from specified system calls. The set of system calls to be traced is defined via an instance of ssssyyyysssssssseeeetttt____tttt addressed by _p. When entry to a system call is being traced, the traced process stops after having begun the call to the system but before the system call arguments have been fetched from the process. When exit from a system call is being traced, the traced process stops on completion of the system call just prior to checking for signals and returning to user level. At this point all return values have been stored into the traced process's registers. If the traced process is stopped on entry to a system call (PR_SYSENTRY) or when sleeping in an interruptible system call (PR_ASLEEP is 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 user level showing error EINTR. PPPPIIIIOOOOCCCCGGGGEEEENNNNTTTTRRRRYYYY PPPPIIIIOOOOCCCCGGGGEEEEXXXXIIIITTTT These return the current traced system call entry or exit set in an instance of ssssyyyysssssssseeeetttt____tttt addressed by _p. PPPPIIIIOOOOCCCCNNNNWWWWAAAATTTTCCCCHHHH PIOCNWATCH returns, in the _i_n_t addressed by _p, the number of watched areas supported by the system. This can be used to allocate storage for use with the PIOCSWATCH and PIOCGWATCH operations, each of which must provide an array whose number of elements equals the supported number of watched areas. ****PPPPIIIIOOOOCCCCSSSSWWWWAAAATTTTCCCCHHHH PIOCSWATCH establishes or clears a set of watched areas in the traced process; _p points to pppprrrrwwwwaaaattttcccchhhh structure containing at least the following fields: typedef struct prwatch { caddr_t pr_vaddr; /* Virtual address of watched area */ u_long pr_size; /* Size of watched area in bytes */ long pr_wflags; /* Watch type flags */ } prwatch_t; pppprrrr____vvvvaaaaddddddddrrrr specifies the virtual address of an area of memory to be watched PPPPaaaaggggeeee 9999 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) in the traced process. pppprrrr____ssssiiiizzzzeeee specifies the size of the area, in bytes. pppprrrr____wwwwffffllllaaaaggggssss specifies the type of memory access to be monitored as a bit- mask of one or more of the following flags (see also PIOCMAP): MMMMAAAA____RRRREEEEAAAADDDD read access MMMMAAAA____WWWWRRRRIIIITTTTEEEE write access MMMMAAAA____EEEEXXXXEEEECCCC execution access An entry with a zero value for pppprrrr____ssssiiiizzzzeeee clears any previously-established watched area starting at the specified virtual address. An entry with a non-empty pppprrrr____wwwwffffllllaaaaggggssss bit-mask establishes a watched area for the virtual address range specified by pppprrrr____vvvvaaaaddddddddrrrr and pppprrrr____ssssiiiizzzzeeee. An entry with an empty pppprrrr____wwwwffffllllaaaaggggssss bit-mask is ignored. A watchpoint is triggered when the traced process makes a memory reference that covers at least one byte of a watched area and the memory reference is a mode of interest as specified in pppprrrr____wwwwffffllllaaaaggggssss. When a watchpoint is triggered, the process incurs a watchpoint trap. If FLTWATCH is being traced, the process stops; otherwise it is sent SIGTRAP; if SIGTRAP is being traced and not held, the process stops. If the access is a write access, the memory is not modified. If the process stops, its program counter refers to the instruction that triggered the watchpoint. pppprrrr____iiiinnnnffffoooo in the pppprrrrssssttttaaaattttuuuussss structure contains information pertinent to the watchpoint trap. In particular, the ssssiiii____aaaaddddddddrrrr field contains the virtual address of the memory reference that triggered the watchpoint and the ssssiiii____ccccooooddddeeee field contains one of MMMMAAAA____RRRREEEEAAAADDDD, MMMMAAAA____WWWWRRRRIIIITTTTEEEE, or MMMMAAAA____EEEEXXXXEEEECCCC, indicating read, write or execute access, respectively. A watchpoint may be triggered while executing a system call that makes reference to the traced process's memory. Such a system call completes normally; a kernel watchpoint fault is taken after the system call completes but before the process returns to user level. If more than one watchpoint would be triggered by the system call, the first one encountered is the one reported. PIOCSWATCH fails with EINVAL if an attempt is made to specify overlapping watched areas or to specify a watchpoint whose virtual address range includes invalid virtual addresses in the traced process. PIOCSWATCH fails with E2BIG if an attempt is made to establish more than the supported number of watched areas and with ESRCH if an attempt is made to delete a non-existent watchpoint. An attempt to delete watchpoints on a running process could result in failure with errno set to EBUSY. This is a temporary condition that occurs when the kernel is stepping over a watchpoint and a later subsequent attempt should succeed. This does not happen if the process is stopped. Access to a process's memory through /_p_r_o_c will not trigger a watchpoint, even if the access is from the process itself (which must have opened its own /_p_r_o_c entry). PPPPaaaaggggeeee 11110000 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) PPPPIIIIOOOOCCCCGGGGWWWWAAAATTTTCCCCHHHH PIOCGWATCH returns, in the array of pppprrrrwwwwaaaattttcccchhhh structures addressed by _p, the set of watched areas currently in effect. Elements beyond the number of actually established watched areas are filled with zeros. ****PPPPIIIIOOOOCCCCSSSSEEEETTTT ****PPPPIIIIOOOOCCCCRRRREEEESSSSEEEETTTT PIOCSET sets one or more modes of operation for the traced process. PIOCRESET resets these modes. The modes to be set or reset are specified by flags in a _l_o_n_g addressed by _p: PPPPRRRR____FFFFOOOORRRRKKKK (inherit-on-fork) When set, the process's tracing flags are inherited by the child of a _f_o_r_k(2). When reset, child processes start with all tracing flags cleared. PPPPRRRR____RRRRLLLLCCCC (run-on-last-close) When set and the last writable /_p_r_o_c file descriptor referring 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, it is set running as though PIOCRUN had been applied to it. When reset, the process's tracing flags are retained and the process is not set running on last close. PPPPRRRR____KKKKLLLLCCCC (kill-on-last-close) When set and the last writable /_p_r_o_c file descriptor referring to the traced process is closed, the process is terminated with SIGKILL. It is an error (EINVAL) to specify flags other than those described above or to apply these operations to a system process. The current modes are reported in the pppprrrrssssttttaaaattttuuuussss structure (see PIOCSTATUS). Note that a processes using /_p_r_o_c can not assume any default settings for these flags, as some other process may have attached to the target earlier and reset the flags and then detached. PPPPIIIIOOOOCCCCGGGGRRRREEEEGGGG ****PPPPIIIIOOOOCCCCSSSSRRRREEEEGGGG These operations respectively get and set the process general registers into or out of an array addressed by _p; the array has type ggggrrrreeeeggggsssseeeetttt____tttt. Register contents are accessible using a set of predefined indices (see PIOCSTATUS). No bits of the processor-status register (PSR) or other privileged registers can be modified by PIOCSREG. PIOCSREG fails (EBUSY) if applied to a process that is not stopped on an event of interest. If the process is not stopped, the register values returned by PIOCGREG are undefined. PPPPIIIIOOOOCCCCGGGGFFFFPPPPRRRREEEEGGGG ****PPPPIIIIOOOOCCCCSSSSFFFFPPPPRRRREEEEGGGG These operations respectively get and set the process floating-point registers into or out of a structure addressed by _p; the structure has type ffffpppprrrreeeeggggsssseeeetttt____tttt. An error (EINVAL) is returned if there is no floating- PPPPaaaaggggeeee 11111111 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) point hardware on the machine. PIOCSFPREG fails (EBUSY) if applied to a process that is not stopped on an event of interest. If the process is not stopped, the register values returned by PIOCGFPREG are undefined. ****PPPPIIIIOOOOCCCCNNNNIIIICCCCEEEE The traced process's _n_i_c_e(2) priority is incremented by the amount contained in the _i_n_t addressed by _p. Only the superuser may better a process's priority in this way, but any user may make the priority worse. PPPPIIIIOOOOCCCCPPPPSSSSIIIINNNNFFFFOOOO This returns miscellaneous process information such as that reported by _p_s(1). _p is a pointer to a pppprrrrppppssssiiiinnnnffffoooo structure containing at least the following fields: typedef struct prpsinfo { char pr_state; /* numeric process state (see pr_sname) */ char pr_sname; /* printable character 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; /* pid of process group leader */ pid_t pr_sid; /* session id */ caddr_t pr_addr; /* physical address of process */ long pr_size; /* size of process image in pages */ long pr_rssize; /* resident set size in pages */ long pr_pagesize; /* system page size, in bytes */ caddr_t pr_wchan; /* wait addr for sleeping process */ timespec_t pr_start; /* process start time, sec+nsec since epoch */ timespec_t pr_time; /* usr+sys cpu time for this process */ long pr_pri; /* priority, high value is high priority */ char pr_oldpri; /* pre-SVR4, low value is high priority */ char pr_cpu; /* pre-SVR4, cpu usage for scheduling */ dev_t pr_ttydev; /* controlling tty device (PRNODEV if none) */ char pr_clname[8]; /* Scheduling class name */ char pr_fname[PRCOMSIZ]; /* last component of exec()ed pathname */ char pr_psargs[PRARGSZ]; /* initial characters of arg list */ u_int pr_pset; /* associated processor set name */ cpuid_t pr_sonproc; /* processor running on */ timespec_t pr_ctime; /* usr+sys cpu time for all children */ } prpsinfo_t; Some of the entries in pppprrrrppppssssiiiinnnnffffoooo, such as pppprrrr____ssssttttaaaatttteeee and pppprrrr____ffffllllaaaagggg, are system-specific and should not be expected to retain their meanings across different versions of the operating system. pppprrrr____aaaaddddddddrrrr is a vestige of the past and has no real meaning in current systems. PPPPaaaaggggeeee 11112222 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) PIOCPSINFO can be applied to a _z_o_m_b_i_e process (one that has terminated but whose parent has not yet performed a _w_a_i_t(2) on it). PPPPIIIIOOOOCCCCNNNNMMMMAAAAPPPP PPPPIIIIOOOOCCCCMMMMAAAAPPPP These operations provide information about the memory mappings (virtual address ranges) associated with the traced process. PIOCNMAP returns, in the _i_n_t addressed by _p, the number of mappings that are currently active. The PIOCMAP operation may be used to obtain the list of currently active mappings, which is an array of structures of type pppprrrrmmmmaaaapppp____tttt. The PIOCNMAP may be used to determine the minimum amount of storage that needs to be allocated to receive these structures, but the programmer should not assume that it is the maximum amount needed. If the PIOCNMAP and PIOCMAP calls are made on a process that is not stopped, the number of maps could change between the two ioctl calls and caller could fault if too few maps were allocated to hold the results of PIOCMAP. Note: for a better interface, see PIOCMAP_SGI below. For PIOCMAP, _p addresses an array of elements of type pppprrrrmmmmaaaapppp____tttt; one array element (one structure) is returned for each mapping, plus an additional element containing all zeros to mark the end of the list. The pppprrrrmmmmaaaapppp structure contains at least the following fields: typedef struct prmap { caddr_t pr_vaddr; /* Virtual address */ 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 */ } prmap_t; pppprrrr____vvvvaaaaddddddddrrrr is the virtual address of the mapping within the traced process and pppprrrr____ssssiiiizzzzeeee is its size in bytes. pppprrrr____ooooffffffff is the offset within the mapped object (if any) to which the virtual address is mapped. pppprrrr____mmmmffffllllaaaaggggssss is a bit-mask of protection and attribute flags: MMMMAAAA____RRRREEEEAAAADDDD mapping is readable by the traced process MMMMAAAA____WWWWRRRRIIIITTTTEEEE mapping is writable by the traced process MMMMAAAA____EEEEXXXXEEEECCCC mapping is executable by the traced process MMMMAAAA____SSSSHHHHAAAARRRREEEEDDDD mapping changes are shared by the mapped object MMMMAAAA____BBBBRRRREEEEAAAAKKKK mapping is grown by the _b_r_k(2) system call MMMMAAAA____SSSSTTTTAAAACCCCKKKK mapping is grown automatically on stack faults MMMMAAAA____PPPPHHHHYYYYSSSS mapping corresponds to a physical device mapping PPPPIIIIOOOOCCCCMMMMAAAAPPPP____SSSSGGGGIIII This operation provides detailed information about the memory mappings (virtual address ranges) associated with the traced process. In effect it performs both a PIOCNMAP and a PIOCMAP call (with additional information) with one ioctl. The PIOCMAP_SGI operation may be used to obtain the list of currently active mappings, which is an array of structures of type pppprrrrmmmmaaaapppp____ssssggggiiii____tttt. The user must preallocate an array of the maximum number of mapping structures they are willing to receive. One array element (one structure) is returned for each mapping, plus an additional element containing all zeros that also marks the end of the PPPPaaaaggggeeee 11113333 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) list. There is an upper limit to the number of memory mappings that can be returned by this call, which is defined as PRMAPMAX in the procfs.h header file. Attempts to request more than the PRMAPMAX number of mappings results in only PRMAPMAX mappings returned. PIOCMAP_SGI returns either -1 or the number of mappings that are currently active. For PIOCMAP_SGI, _p addresses a pointer to a structure called pppprrrrmmmmaaaapppp____ssssggggiiii____aaaarrrrgggg____tttt. It contains the following fields: typedef struct prmap_sgi_arg { caddr_t pr_vaddr; /* Base of map buffer */ ulong_t pr_size; /* Size of buffer in bytes */ } prmap_sgi_arg_t; pppprrrr____vvvvaaaaddddddddrrrr is the virtual address of the buffer to hold the mappings for the traced process and pppprrrr____ssssiiiizzzzeeee is its size in bytes. The pppprrrrmmmmaaaapppp____ssssggggiiii____tttt structure contains at least the following fields: typedef struct prmap_sgi { caddr_t pr_vaddr; /* Virtual base address */ ulong_t pr_size; /* Size of mapping in bytes */ off_t pr_off; /* Offset into mapped object, if any */ ulong_t pr_mflags; /* Protection and attribute flags */ pgno_t pr_vsize; /* # valid pages in this segment */ pgno_t pr_psize; /* # private pages in this segment */ pgno_t pr_wsize; /* Cost for this proc weighted base 256 */ pgno_t pr_rsize; /* # referenced pages in this segment */ pgno_t pr_msize; /* # modified pages in this segment */ dev_t pr_dev; /* Device # of segment iff mapped */ ino_t pr_ino; /* Inode # of segment iff mapped */ } prmap_sgi_t; pppprrrr____vvvvaaaaddddddddrrrr is the virtual address of the mapping within the traced process and pppprrrr____ssssiiiizzzzeeee is its size in bytes. pppprrrr____ooooffffffff is the offset within the mapped object (if any) to which the virtual address is mapped. pppprrrr____vvvvssssiiiizzzzeeee, pppprrrr____ppppssssiiiizzzzeeee, pppprrrr____wwwwssssiiiizzzzeeee, pppprrrr____rrrrssssiiiizzzzeeee, pppprrrr____mmmmssssiiiizzzzeeee are page counts for the virtual mapping. pppprrrr____ddddeeeevvvv and pppprrrr____ddddeeeevvvv identify the filesystem resident object from which the mapping originates (if one exists). pppprrrr____mmmmffffllllaaaaggggssss is a bit-mask of protection and attribute flags: MMMMAAAA____RRRREEEEAAAADDDD mapping is readable by the traced process MMMMAAAA____WWWWRRRRIIIITTTTEEEE mapping is writable by the traced process MMMMAAAA____EEEEXXXXEEEECCCC mapping is executable by the traced process MMMMAAAA____SSSSHHHHAAAARRRREEEEDDDD mapping changes are shared by the mapped object MMMMAAAA____BBBBRRRREEEEAAAAKKKK mapping is grown by the _b_r_k(2) system call MMMMAAAA____SSSSTTTTAAAACCCCKKKK mapping is grown automatically on stack faults MMMMAAAA____PPPPHHHHYYYYSSSS mapping corresponds to a physical device mapping MMMMAAAA____PPPPRRRRIIIIMMMMAAAARRRRYYYY mapping is one of the processes core segments MMMMAAAA____CCCCOOOOWWWW mapping corresponds to a copy on write segment PPPPaaaaggggeeee 11114444 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) MMMMAAAA____NNNNOOOOTTTTCCCCAAAACCCCHHHHEEEEDDDD mapped address segment is not cached MMMMAAAA____SSSSHHHHMMMMEEEEMMMM mapping corresponds to a shared memory mapping MMMMAAAA____RRRREEEEFFFFCCCCNNNNTTTT____SSSSHHHHIIIIFFFFTTTT amount to shift right mflags to get reference count PPPPIIIIOOOOCCCCPPPPGGGGDDDD____SSSSGGGGIIII This operation provides information about the interior of a memory mappings (virtual address ranges) associated with the traced process. The PIOCPGD_SGI operation is be used to obtain the list of page descriptors, which is an array of structures of type ppppggggdddd____tttt. The PIOCMAP_SGI ioctl may be used to determine the amount of storage that needs to be allocated to receive these structures. For PIOCPGD_SGI, _p addresses a pointer to a pppprrrrppppggggdddd____ssssggggiiii____tttt structure that contains an array of elements of type pppprrrrppppggggdddd____tttt. The ppppggggdddd____tttt structure contains at least the following fields: typedef struct pgd { /* per-page data */ short pr_flags; /* flags */ short pr_value; /* page count/fault offset */ } pgd_t; The pppprrrrppppggggdddd____ssssggggiiii____tttt structure contains at least the following fields: typedef struct prpgd_sgi { caddr_t pr_vaddr; /* virtual base address of region to stat */ pgno_t pr_pglen; /* number of pages in data list... */ pgd_t pr_data[1]; /* variable length array of page flags */ } prpgd_sgi_t; pppprrrr____vvvvaaaaddddddddrrrr is the virtual address of the mapping within the traced process and pppprrrr____ppppgggglllleeeennnn is length of the pppprrrr____ddddaaaattttaaaa array. The pppprrrr____ffffllllaaaaggggssss field for each page contains the following flags: PPPPGGGGFFFF____RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEEDDDD page is currently valid in system page table PPPPGGGGFFFF____GGGGLLLLOOOOBBBBAAAALLLL page is marked global in system page table PPPPGGGGFFFF____WWWWRRRRIIIITTTTEEEEAAAABBBBLLLLEEEE page is currently writeable in system page table PPPPGGGGFFFF____NNNNOOOOTTTTCCCCAAAACCCCHHHHEEEEDDDD page is marked non-cacheable in system page table PPPPGGGGFFFF____IIIISSSSVVVVAAAALLLLIIIIDDDD page is marked valid for this process PPPPGGGGFFFF____IIIISSSSDDDDIIIIRRRRTTTTYYYY page is marked dirty for this process PPPPGGGGFFFF____PPPPRRRRIIIIVVVVAAAATTTTEEEE page is marked private to this process PPPPGGGGFFFF____FFFFAAAAUUUULLLLTTTT the pr_value field contains a fault offset PPPPGGGGFFFF____UUUUSSSSRRRRHHHHIIIISSSSTTTTOOOORRRRYYYY accumulating history flag for caller PPPPGGGGFFFF____RRRREEEEFFFFHHHHIIIISSSSTTTTOOOORRRRYYYY page has been marked referenced PPPPGGGGFFFF____WWWWRRRRTTTTHHHHIIIISSSSTTTTOOOORRRRYYYY page has been marked dirty PPPPGGGGFFFF____VVVVAAAALLLLHHHHIIIISSSSTTTTOOOORRRRYYYY page has been marked valid PPPPGGGGFFFF____CCCCLLLLEEEEAAAARRRR clear valid & writeable bits in page table The pppprrrr____vvvvaaaalllluuuueeee field for each page contains either a reference count or a fault offset value if the PPPPGGGGFFFF____CCCCLLLLEEEEAAAARRRR operation was set on a previous call. This can be used to determine what function or variable inside a page that the process references or writes frequently. PPPPaaaaggggeeee 11115555 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) PPPPIIIIOOOOCCCCOOOOPPPPEEEENNNNMMMM The return value _r_e_t_v_a_l provides a read-only file descriptor for a mapped object associated with the traced process. If _p is zero the traced process's _e_x_e_c(2)ed file is found. This enables a debugger to find the object file symbol table without having to know the pathname of the executable file. If _p is non-zero it points to a ccccaaaaddddddddrrrr____tttt containing a virtual address within the traced process and the mapped object, if any, associated with that address is found; this can be used to get a file descriptor for a shared library that is attached to the process. On error (invalid address, physical device mapping, or no mapped object for the designated address), -1 is returned and errno is set to EINVAL. PPPPIIIIOOOOCCCCCCCCRRRREEEEDDDD Fetch the set of credentials associated with the process. _p points to an instance of pppprrrrccccrrrreeeedddd____tttt that is filled by the operation. The pppprrrrccccrrrreeeedddd structure contains at least the following fields: typedef struct prcred { uid_t pr_euid; /* Effective user id */ uid_t pr_ruid; /* Real user id */ uid_t pr_suid; /* Saved user id (from exec) */ gid_t pr_egid; /* Effective group id */ gid_t pr_rgid; /* Real group id */ gid_t pr_sgid; /* Saved group id (from exec) */ u_int pr_ngroups; /* Number of supplementary groups */ } prcred_t; PPPPIIIIOOOOCCCCGGGGRRRROOOOUUUUPPPPSSSS Fetch the set of supplementary group IDs associated with the process. _p points to an array of elements of type ggggiiiidddd____tttt, that will be filled by the operation. PIOCCRED can be applied beforehand to determine the number of groups (pppprrrr____nnnnggggrrrroooouuuuppppssss) that will be returned and the amount of storage that should be allocated to hold them. PPPPIIIIOOOOCCCCTTTTLLLLBBBBMMMMIIIISSSSSSSS Enable special user TLB handling. The TLB is a hardware coprocessor that makes virtual-to-physical address translations. _p points to an integer that specifies the handling desired. If the value is TTTTLLLLBBBB____CCCCOOOOUUUUNNNNTTTT, a record will be kept of every virtual-address TLB refill that occurs while the process mapped by _f_i_l_d_e_s is running. If the value is TTTTLLLLBBBB____SSSSTTTTDDDD, counting will be disabled (the default mode). It is important to note that monitoring TLB efficiency can be a useful tool, but the performance of the code that refills the TLB will be degraded. The TLB refill counts can be obtained by PPPPIIIIOOOOCCCCUUUUSSSSAAAAGGGGEEEE. The ssssttttrrrruuuucccctttt pppprrrruuuussssaaaaggggeeee field ppppuuuu____uuuuttttllllbbbb accounts for TLB refills that occurred while the process was running in user mode, and the field ppppuuuu____kkkkttttllllbbbb accounts for refills that occurred while executing system calls on behalf of the user or while handling hardware interrupt code while the user process was scheduled. PPPPaaaaggggeeee 11116666 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) PPPPIIIIOOOOCCCCUUUUSSSSAAAAGGGGEEEE PIOCUSAGE returns process usage information. _p points to a pppprrrruuuussssaaaaggggeeee structure that is filled by the operation. The fields in a pppprrrruuuussssaaaaggggeeee structure are implementation dependent; no application can assume portability in this area. See <_s_y_s/_p_r_o_c_f_s._h> for the exact definition for a particular implementation. The SGI implementation supports the following fields: typedef struct prusage { timespec_t pu_tstamp; /* time stamp */ timespec_t pu_starttime; /* process start time */ timespec_t pu_utime; /* user CPU time */ timespec_t pu_stime; /* system CPU time */ u_long pu_minf; /* minor (mapping) page faults */ u_long pu_majf; /* major (disk) page faults */ u_long pu_utlb; /* user TLB misses */ u_long pu_nswap; /* number of swaps */ u_long pu_gbread; /* gigabytes ... */ u_long pu_bread; /* and bytes read */ u_long pu_gbwrit; /* gigabytes ... */ u_long pu_bwrit; /* and bytes written */ u_long pu_sigs; /* signals received */ u_long pu_vctx; /* voluntary context switches */ u_long pu_ictx; /* involuntary context switches */ u_long pu_sysc; /* system calls */ u_long pu_syscr; /* read() system calls */ u_long pu_syscw; /* write() system calls */ u_long pu_syscps; /* poll() or select() system calls */ u_long pu_sysci; /* ioctl() system calls */ u_long pu_graphfifo; /* graphics pipeline stalls */ u_long pu_graph_req[8]; /* graphics resource requests */ u_long pu_graph_wait[8]; /* graphics resource waits */ u_long pu_size; /* size of swappable image in pages */ u_long pu_rss; /* resident size of swappable image */ u_long pu_inblock; /* block input operations */ u_long pu_oublock; /* block output operations */ u_long pu_vfault; /* total number of vfaults */ u_long pu_ktlb; /* kernel TLB misses */ } prusage_t; PPPPIIIIOOOOCCCCGGGGEEEETTTTPPPPTTTTIIIIMMMMEEEERRRR PIOCGETPTIMER returns an array of timers indicating the amount of time the process has spent in each of the following states: #include <time.h> #include <sys/timers.h> struct timespec ptime[MAX_PROCTIMER]; PPPPaaaaggggeeee 11117777 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) AAAASSSS____UUUUSSSSRRRR____RRRRUUUUNNNN running in user mode AAAASSSS____SSSSYYYYSSSS____RRRRUUUUNNNN running in system mode AAAASSSS____IIIINNNNTTTT____RRRRUUUUNNNN running in interrupt mode AAAASSSS____BBBBIIIIOOOO____WWWWAAAAIIIITTTT waiting for block I/O AAAASSSS____MMMMEEEEMMMM____WWWWAAAAIIIITTTT waiting for memory AAAASSSS____SSSSEEEELLLLEEEECCCCTTTT____WWWWAAAAIIIITTTT waiting in select AAAASSSS____JJJJCCCCLLLL____WWWWAAAAIIIITTTT stopped because of job control AAAASSSS____RRRRUUUUNNNNQQQQ____WWWWAAAAIIIITTTT waiting to run on run queue AAAASSSS____SSSSLLLLEEEEEEEEPPPP____WWWWAAAAIIIITTTT waiting for resource AAAASSSS____SSSSTTTTRRRRMMMMOOOONNNN____WWWWAAAAIIIITTTT waiting for the stream monitor AAAASSSS____PPPPHHHHYYYYSSSSIIIIOOOO____WWWWAAAAIIIITTTT waiting for raw I/O _p is a pointer to an array of MMMMAAAAXXXX____PPPPRRRROOOOCCCCTTTTIIIIMMMMEEEERRRR ttttiiiimmmmeeeessssppppeeeecccc structures. PPPPIIIIOOOOCCCCOOOOPPPPEEEENNNNPPPPDDDD PIOCOPENPD is not currently implemented on SGI machines. It is under consideration for future releases. The return value _r_e_t_v_a_l provides a read-only file descriptor for a ``page data file'', enabling tracking of address space references and modifications on a per-page basis. A _r_e_a_d(2) of the page data file descriptor returns structured page data and atomically clears the page data maintained for the file by the system. That is to say, each read returns data collected since the last read; the first read returns data collected since the file was opened. When the call completes, the read buffer contains the following structure as its header and thereafter contains a number of variable length structures that must be accessed by walking linearly through the buffer. typedef struct prpageheader { timespec_t tstamp; /* real time time stamp */ u_long nmap; /* number of address space mappings */ u_long npage; /* total number of pages */ } prpageheader_t; The header is followed by nnnnmmmmaaaapppp variable-length pppprrrraaaassssmmmmaaaapppp structures: typedef struct prasmap { caddr_t vaddr; /* virtual address */ u_long npage; /* number of pages in mapping */ u_char data[1]; /* referenced, modified, present flags */ } prasmap_t; The ddddaaaattttaaaa[[[[]]]] array is of variable length, with one entry for each page in the mapping, nnnnppppaaaaggggeeee entries altogether, rounded up with empty entries at the end so that the structure size is an integral numbers of long's. ddddaaaattttaaaa[[[[]]]] entries may contain these flags: PPPPGGGG____PPPPRRRREEEESSSSEEEENNNNTTTT page is resident in memory now PPPPaaaaggggeeee 11118888 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) PPPPGGGG____RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEEDDDD page has been referenced since last read PPPPGGGG____MMMMOOOODDDDIIIIFFFFIIIIEEEEDDDD page has been modified since last read If the read buffer is not large enough to contain all of the page data, the read fails with E2BIG and the page data is not cleared. The required size of the read buffer can be determined through _f_s_t_a_t(2). Application of _l_s_e_e_k(2) to the page data file descriptor is ineffective. Closing the page data file terminates the system overhead associated with collecting the data. PPPPIIIIOOOOCCCCGGGGEEEETTTTPPPPRRRR PPPPIIIIOOOOCCCCGGGGEEEETTTTUUUU These operations copy, respectively, the traced process's _p_r_o_c structure and _u_s_e_r _a_r_e_a into the buffer addressed by _p. They are provided for completeness but it should be unnecessary to access either of these structures directly since relevant status information is available through other control operations. Their use is discouraged because a program making use of them is tied to a particular version of the operating system. PIOCGETPR can be applied to a _z_o_m_b_i_e process (see PIOCPSINFO). PPPPIIIIOOOOCCCCAAAACCCCIIIINNNNFFFFOOOO PIOCACINFO returns the currently accumulated accounting information for the process. _p points to a pppprrrraaaacccciiiinnnnffffoooo structure that is filled in by the operation. The fields in pppprrrraaaacccciiiinnnnffffoooo are implementation dependent; no application can assume portability in this area. See <_s_y_s/_p_r_o_c_f_s._h> and <_s_y_s/_e_x_t_a_c_c_t._h> for the exact definition of a particular implementation. The SGI implementation supports the following fields: typedef struct pracinfo { char pr_version; /* Accounting data version */ char pr_flag; /* Miscellaneous flags */ char pr_nice; /* Nice value */ unchar pr_sched; /* Scheduling discipline */ /* (see sys/schedctl.h) */ __int32_t pr_spare1; /* reserved */ ash_t pr_ash; /* Array session handle */ prid_t pr_prid; /* Project ID */ time_t pr_btime; /* Begin time (in secs since 1970)*/ time_t pr_etime; /* Elapsed time (in HZ) */ __int32_t pr_spare2[2]; /* reserved */ struct acct_timers pr_timers; /* Assorted timers: see extacct.h */ struct acct_counts pr_counts; /* Assorted counters: (ditto) */ __int64_t pr_spare3[8]; /* reserved */ } pracinfo_t; PPPPIIIIOOOOCCCCGGGGEEEETTTTSSSSNNNN0000EEEEXXXXTTTTRRRREEEEFFFFCCCCNNNNTTTTRRRRSSSS PPPPIIIIOOOOCCCCGGGGEEEETTTTSSSSNNNN0000RRRREEEEFFFFCCCCNNNNTTTTRRRRSSSS PIOCGETSN0EXTREFCNTRS returns the extended memory reference counter values in an Origin system for a specified virtual address space range. See refcnt(5). PPPPaaaaggggeeee 11119999 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) The third argument is used to specify the virtual address space range and the user buffer where to store the counter values. This argument is of type sn0_refcnt_args_t, as defined in <sys/SN/hwcntrs.h>: typedef struct sn0_refcnt_args { caddr_t vaddr; long len; sn0_refcnt_buf_t* buf; } sn0_refcnt_args_t; The first field vvvvaaaaddddddddrrrr is the base of the virtual address space range, the field lllleeeennnn is the corresponding length in bytes, and the field bbbbuuuuffff is a pointer to a user buffer where the system will store the counter values and additional information. This buffer is an array of elements of type sn0_refcnt_buf_t, where each element corresponds to the counter information associated with one hardware page: typedef struct sn0_refcnt_buf { sn0_refcnt_set_t refcnt_set; __uint64_t paddr; __uint64_t page_size; cnodeid_t cnodeid; } sn0_refcnt_buf_t; The field rrrreeeeffffccccnnnntttt____sssseeeetttt contains the set of counters associated with the virtual address passed via ssssnnnn0000____rrrreeeeffffccccnnnntttt____aaaarrrrggggssss, ppppaaaaddddddddrrrr is the address of the physical page associated with this virtual address, ppppaaaaggggeeee____ssssiiiizzzzeeee is the page size being used to map it, and ccccnnnnooooddddeeeeiiiidddd is the physical page home node, expressed in terms of _C_o_m_p_a_c_t _N_o_d_e _I_d_e_n_t_i_f_i_e_r_s which can be mapped back to node names using the command topology(1). The rrrreeeeffffccccnnnntttt____sssseeeetttt type is defined by typedef struct sn0_refcnt_set { refcnt_t refcnt[SN0_REFCNT_MAX_COUNTERS]; __uint64_t flags; } sn0_refcnt_set_t; The field rrrreeeeffffccccnnnntttt is the actual set of counters (one counter per node), and ffffllllaaaaggggssss is a state vector reserved for future use. The counters in rrrreeeeffffccccnnnntttt are ordered according to the _C_o_m_p_a_c_t _N_o_d_e _I_d_e_n_t_i_f_i_e_r_s, also known as ccccnnnnooooddddeeeeiiiiddddssss (numa(5)). PIOCGETSN0REFCNTRS instructs the system to return the actual hardware counter values instead of the extended software counter values returned by PIOCGETSN0EXTREFCNTRS. PPPPaaaaggggeeee 22220000 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) The following section of code shows an example of use for this interface: #include <sys/types.h> #include <stdio.h> #include <malloc.h> #include <sys/stat.h> #include <fcntl.h> #include <sys/prctl.h> #include <procfs/procfs.h> #include <sys/syssgi.h> #include <sys/sysmp.h> #include <sys/SN/hwcntrs.h> /* * This routine makes two assumptions that may not * be true in all systems: * Length of hardware page (counter granularity): 0x1000 bytes * Length of base software page (smallest mappable memory area): 0x4000 bytes */ void print_refcounters(char* vaddr, int len) { pid_t pid = getpid(); char pfile[256]; int fd; sn0_refcnt_buf_t* refcnt_buffer; sn0_refcnt_buf_t* direct_refcnt_buffer; sn0_refcnt_args_t* refcnt_args; int npages; int gen_start; int numnodes; int page; int node; sprintf(pfile, "/proc/%05d", pid); if ((fd = open(pfile, O_RDONLY)) < 0) { fprintf(stderr,"Can't open /proc/%d", pid); exit(1); } vaddr = (char *)( (unsigned long)vaddr & ~0xfff ); npages = (len + 0xfff) >> 12; if ((refcnt_buffer = malloc(sizeof(sn0_refcnt_buf_t) * npages)) == NULL) { perror("malloc refcnt_buffer"); exit(1); } if ((direct_refcnt_buffer = malloc(sizeof(sn0_refcnt_buf_t) * npages)) == NULL) { perror("malloc refcnt_buffer"); exit(1); PPPPaaaaggggeeee 22221111 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) } if ((refcnt_args = malloc(sizeof(sn0_refcnt_args_t))) == NULL) { perror("malloc refcnt_args"); exit(1); } refcnt_args->vaddr = vaddr; refcnt_args->len = len; refcnt_args->buf = refcnt_buffer; if ((gen_start = ioctl(fd, PIOCGETSN0EXTREFCNTRS, (void *)refcnt_args)) < 0) { perror("ioctl PIOCGETSN0EXTREFCNTRS returns error"); exit(1); } refcnt_args->vaddr = vaddr; refcnt_args->len = len; refcnt_args->buf = direct_refcnt_buffer; if ((gen_start = ioctl(fd, PIOCGETSN0REFCNTRS, (void *)refcnt_args)) < 0) { perror("ioctl PIOCGETSN0REFCNTRS returns error"); exit(1); } if ((numnodes = sysmp(MP_NUMNODES)) < 0) { perror("sysmp MP_NUMNODES"); exit(1); } for (page = 0; page < npages; page++) { printf("page[%05d, 0x%lx, 0x%llx (0x%llx)]:", page, vaddr + page*0x1000, refcnt_buffer[page].paddr, refcnt_buffer[page].paddr >> 14); for (node = 0; node < numnodes; node++) { printf(" %05lld (%06lld)", refcnt_buffer[page].refcnt_set.refcnt[node], direct_refcnt_buffer[page].refcnt_set.refcnt[node]); } printf("0); } close(fd); free(refcnt_args); free(refcnt_buffer); } PPPPIIIIOOOOCCCCGGGGEEEETTTTIIIINNNNOOOODDDDEEEE PIOCGETINODE returns information about an open file for the process. _p points to a pppprrrriiiinnnnooooddddeeeeiiiinnnnffffoooo structure containing the file descriptor of PPPPaaaaggggeeee 22222222 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) interest (in ppppiiii____ffffdddd). On return ppppiiii____ddddeeeevvvv, ppppiiii____iiiinnnnuuuummmm, and ppppiiii____ggggeeeennnn contain the filesystem device, inode number, and inode generation number respectively. Further information about the file can then be obtained through _s_y_s_s_g_i(SSSSGGGGIIII____FFFFSSSS____BBBBUUUULLLLKKKKSSSSTTTTAAAATTTT), for instance. The ppppiiii____ddddeeeevvvv value matches that returned by _s_t_a_t_v_f_s (ffff____ffffssssiiiidddd) and _s_t_a_t (sssstttt____ddddeeeevvvv). Bad values for ppppiiii____ffffdddd result in EBADF errors; if the referenced file is actually a socket then errno is set to EINVAL. Filesystems other than XFS and EFS return 0 for the ppppiiii____ggggeeeennnn value. NNNNOOOOTTTTEEEESSSS Each operation (_i_o_c_t_l or I/O) is guaranteed to be atomic with respect to the traced process, except when applied to a system process. To wait for one or more of a set of processes to stop, /_p_r_o_c file descriptors can be used in a _p_o_l_l(2) system call. On successful return, the polling event POLLPRI indicates that the process has stopped on an ``event of interest'' (see PPPPIIIIOOOOCCCCSSSSTTTTOOOOPPPP above). Although they cannot be requested, the polling events POLLHUP, POLLERR and POLLNVAL may be returned. 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 referring to either itself or a system process (see PIOCSTOP). /_p_r_o_c file descriptors may also be used in a _s_e_l_e_c_t(2) system call. Selecting for an exceptional event has the same semantics as polling for POLLPRI. Selecting for reading or writing or polling for POLLIN or POLLOUT will always return true. See the _p_o_l_l(2) and _s_e_l_e_c_t(2) man pages for further details. _p_o_l_l() or _s_e_l_e_c_t() may not be used on the /proc directory itself. For security reasons, except for the superuser, an open of a /_p_r_o_c file fails unless both the user-ID and group-ID of the caller match those of the traced process and the process's object file is readable by the caller. Files corresponding to setuid and setgid processes can be opened only by the superuser. Even if held by the superuser, an open process file descriptor becomes invalid if the traced process performs an _e_x_e_c() of a setuid/setgid object file or an object file that it cannot read. Any operation performed on an invalid file descriptor, except _c_l_o_s_e(2), fails with EAGAIN. In this situation, if any tracing flags are set and the process file descriptor is open for writing, the process will have been directed to stop and its run-on-last-close flag will have been set (see PIOCSET). This enables a controlling process (if it has permission) to reopen the process file to get a new valid file descriptor, close the invalid file descriptor, and proceed. Just closing the invalid file descriptor causes the traced process to resume execution with no tracing flags set. Any process not currently open for writing via /_p_r_o_c but that has left-over tracing flags from a previous open and that _e_x_e_cs a setuid/setgid or unreadable object file will not be stopped but will have all its tracing flags cleared. PPPPaaaaggggeeee 22223333 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) Descriptions of structures in this document include only interesting structure elements, not filler and padding fields, and may show elements out of order for descriptive clarity. The actual structure definitions are contained in <_s_y_s/_p_r_o_c_f_s._h>. For reasons of symmetry and efficiency there are more control operations than strictly necessary. Programs compiled with the old 32-bit abi calling convention can perform ioctls on programs compiled with the new 32-bit abi or 64-bit abi calling conventions by "or'ing" the ioctl with PIOC_IRIX5_N32 or PIOC_IRIX5_64, respectively, and passing in a pointer to a buffer that is big enough to hold the larger structure. FFFFIIIILLLLEEEESSSS /proc directory (list of active processes) /proc/_n_n_n_n_n process image SSSSEEEEEEEE AAAALLLLSSSSOOOO mntproc(1M), ioctl(2), open(2), poll(2), ptrace(2), sigaction(2), signal(2), stat(2), statvfs(2), syssgi(2), siginfo(5), signal(5). DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS Errors that can occur in addition to the errors normally associated with filesystem access: ENOENT The traced process has terminated after being opened. EIO I/O was attempted at an illegal address in the traced process. ENXIO I/O was attempted to an isolated processes address space. EBADF An I/O or _i_o_c_t_l operation requiring write access was attempted on a file descriptor not open for writing; PIOCGETINODE was applied to a process file which was not open. EBUSY PIOCSTOP or PIOCWSTOP was applied to a system process; an exclusive _o_p_e_n(2) was attempted on a process file already open for writing; an _o_p_e_n(2) for writing was attempted and an exclusive open is in effect on the process file; PIOCRUN, PIOCSREG or PIOCSFPREG was applied to a process not stopped on an event of interest; an attempt was made to mount /_p_r_o_c when it is already mounted. EPERM Someone other than the superuser attempted to better a process's priority by issuing PIOCNICE. ENOSYS An attempt was made to perform an unsupported operation (such as create, remove, link, or unlink) on an entry in /_p_r_o_c. PPPPaaaaggggeeee 22224444 pppprrrroooocccc((((4444)))) pppprrrroooocccc((((4444)))) EFAULT An I/O or _i_o_c_t_l request referred to an invalid address in the controlling process. EINVAL In general this means that some invalid argument was supplied to a system call. The list of conditions eliciting this error includes: the _i_o_c_t_l code is undefined; the _i_o_c_t_l code is not implemented; an _i_o_c_t_l operation was issued on a file descriptor referring to the /_p_r_o_c directory; an out-of-range signal number was specified with PIOCSSIG, PIOCKILL, or PIOCUNKILL; SIGKILL was specified with PIOCUNKILL; an illegal virtual address was specified in a PIOCOPENM request; overlapping watched areas were specified in a PIOCSWATCH request; an attempt was made to establish more than the supported number of watched areas in a PIOCSWATCH request; PIOCGFPREG or PIOCSFPREG was issued on a machine without floating-point hardware; the file specified to PIOCGETINODE is a socket. E2BIG Data to be returned in a _r_e_a_d(2) of the page data file exceeds the size of the read buffer provided by the caller. EINTR A signal was received by the controlling process while waiting for the traced process to stop via PIOCSTOP or PIOCWSTOP. EAGAIN The traced process has performed an _e_x_e_c of a setuid/setgid object file or of an object file that it cannot read; all further operations on the process file descriptor (except _c_l_o_s_e(2)) elicit this error. BBBBUUUUGGGGSSSS When a signal is sent to the target process, but it is cleared (either by PIOCUNKILL or by using the PRCSIG flag to PIOCRUN), most system calls complete normally and do not return EINTR. However, the specific system calls _m_s_g_s_n_d(2), _m_s_g_r_c_v(2), _s_e_m_o_p(2), _u_s_p_s_e_m_a(3P), _p_o_l_l(2) and _i_o_c_t_l(2) to the _i_m_o_n(7M) device are interrupted and do return EINTR. PPPPaaaaggggeeee 22225555 
