PROCINFO

NM and CM callable.

Provides access to process information.

Syntax

             I16    I16  I16V
   PROCINFO(infoerror1,infoerror2,pin
                I16V   *
            [,itemnum1,item1] [...] [,itemnum6,item6]);




	NOTE: You can specify up to six `itemnum,item` pairs.

Parameters

error1

16-bit signed integer by reference (required)

Returns a value indicating the success or failure of the intrinsic call. Refer to Table 9-1 “PROCINFO Error1, Error2 Values”.

error2

16-bit signed integer by reference (required)

Returns a value that supplies additional error information in error1. Refer to Table 9-1 “PROCINFO Error1, Error2 Values”.

pin

16-bit signed integer by value (required)

Passes the process identification number (PIN) of the process for which information is to be returned in the item parameter. A zero returns information about the calling process.

This parameter is not compatible with the pin parameter of the GETPROCINFO intrinsic.

itemnum

16-bit signed integer by value (optional)

Passes the item number of an information option, as defined in Table 9-2 “PROCINFO Itemnum/Item Values”.

item

type varies (optional)

Returns information about the process specified by pin, as specified in Table 9-2 “PROCINFO Itemnum/Item Values”

Table 9-1 PROCINFO Error1, Error2 Values

Error1	Description	Error2
0	Successful	0
1	Insufficient capability	Index of offending `itemnum`
3	Required parameter address (other than `error1`) out of bounds	Not used
4	Illegal array size	Array size passed to `PROCINFO`
5	Invalid `itemnum`	Index of offending `itemnum`
6	Invalid PIN; no information returned	-1
7	Unassigned PIN	-1
8	Unpaired `itemnum,item` parameters	Index of offending `itemnum,item` parameters
9	Invalid access to information	-1
10	Invalid address entered for item	Index of offending `itemnum,item` parameters
11	The process name cannot be represented using the desired syntax	Index of offending `itemnum,item` parameters




	NOTE: The process aborts if the `error1` parameter address is illegal. If an error condition is detected while processing an information request, the index of the `itemnum`, where the offending option was located, is stored in `error2`.

Table 9-2 PROCINFO Itemnum/Item Values

Itemnum	Mnemonic	Item Description
1	I16	Process identification number (PIN) of calling process
2	I16	Process identification number (PIN) of the parent of the process specified by `pin`. If the calling process is executing in privileged mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process. Information returned for descendants below children (grandchildren, great-grandchildren, and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.
3	I16	Number of children of the process specified by `pin`. If the calling process is executing in privileged mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process. Information returned for descendants below children (grandchildren, great-grandchildren, and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.
4	I16	Number of descendants (children, grandchildren, and so on) of the process specified by `pin`. If the calling process is executing in privileged mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process. Information returned for descendants below children (grandchildren, great-grandchildren, and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.
5	I16	Number of generations (number of levels in the process tree substructure), including itself, of the process specified by `pin`. If the calling process is executing in privileged mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process. Information returned for descendants below children (grandchildren, great-grandchildren, and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.
6	I16A	Process identification numbers (PINs) of all children of the process specified by `pin`. A variable number of PINs are returned; `item` must be a 16-bit signed integer array. The first element of the array must be set by the calling process to indicate the array size. The array size should include the array size element (for example, for four PINs, the first entry that contains the array size should be 5). PINs are stored into the array, one PIN per element, starting with the second element and continuing until the array is filled or all PINs are returned. If the array is not filled, the remaining unused elements are padded with zeros. If the calling process is executing in privileged mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process. Information returned for descendants below children (grandchildren, great-grandchildren, and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.
7	I16A	Process identification numbers (PINs) of all descendants below children, grandchildren, and so on) of the process specified by `pin`. A variable number of PINs are returned; `item` must be a 16-bit signed integer array. The first element of the array must be set by the calling process to indicate the array size. The array size should include the array size element (for example, for four PINs, the first entry that contains the array size should be 5). PINs are stored into the array, one PIN per element, starting with the second element and continuing until the array is filled or all PINs are returned. If the array is not filled, the remaining unused elements are padded with zeros. If the calling process is executing in privileged mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process. Information returned for descendants below children (grandchildren, great-grandchildren, and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.
8	I16	Priority number in the master queue of the process specified by `pin` (same as Bits (0:16) returned by `GETPROCINFO` intrinsic).
9	I16	State and activation information of the process specified by `pin` (same as Bits (16:16) returned by `GETPROCINFO` intrinsic).
10	CA	Program name that the process specified by `pin` is currently executing. The character array for the program name must be a minimum of 28 bytes long. The name is returned in the form `file.group.account`, where `file` is the local file name, `group` is the group name, and `account` is the account name of the file containing the program that the specified process is currently executing. The name is returned left-justified with the unused locations filled with blanks. If the calling process is executing in privileged mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process. Information returned for descendants below children (grandchildren, great-grandchildren and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.
12		Returns a null-terminated HFS-syntax absolute pathname that the process specified by pin is currently executing. On input, the first four bytes of the buffer are interpreted as a signed integer specifying the maximum bufffer size in bytes. The maximum buffer size does not include the four bytes used to represent the size. On output, the first four bytes of the buffer represent the pathname length excluding the null-terminator as a signed integer. The pathname is returned in the bytes following the pathname length. Bytes beyond the null-terminator should be considered undefined. If the maximum buffer length is not correct on input, variables allocated near the buffer can be overwritten, or an error occurs. If the process name is not expressed using HFS syntax, an error is returned in the first four bytes of the buffer. If the calling process is executing in privilege mode, requests for information are honored for any process. Otherwise, requests are honored as follows: Complete information is returned for children of the calling process itself. Information returned for descendants below children (grandchildren, great-grandchildren, and so on) and processes directly above the calling process is limited to `itemnum`s 2 through 7, 10, and 12 only. Process handling capability is required for any user mode call unless the calling process is requesting information about itself.

Condition Codes

CCE (2): Request granted. Error1 and error2 return zero.
CCG (0): Not returned.
CCL (1): Request denied. Error codes set and returned in error1 and error2.

Related Information

Manual: Process Management Programmer's Guide

PROCINFO

Technical documentation

» Table of Contents

» Index

Syntax

Parameters

Condition Codes

Related Information