Retrieve an Interprocess Communication Object (QP0ZRIPC) API

The Retrieve an Interprocess Communication Object (QP0ZRIPC) API lets you generate detailed information about a single interprocess communication (IPC) object. The object is identified by the format name and the identifier that is passed in.

The QP0ZRIPC API places the information about the object in the receiver variable. The information that is written to the receiver variable is dependent on the format name parameter.

Authorities and Locks

Job Authority

Service special authority (*SERVICE) is needed to call this API.

For additional information about this authority, see the Security reference topic collection.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is used to return the IPC object information that you requested.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The format of the information to be returned in the receiver variable. This parameter will determine the object type (either message queues, semaphore sets, or shared memory) to retrieve the list for. You must use one of the following format names:

RSST0100	This format is described in RSST0100 Format.
RMSQ0100	This format is described in RMSQ0100 Format.
RSHM0100	This format is described in RSHM0100 Format.

Identifier

INPUT; BINARY(4)

The identifier of the IPC object that you would like to retrieve information about. This identifier is returned from the APIs semget(), shmget(), msgget(), or QP0ZOLIP.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

RSST0100 Format

This format name is used to return information for a single semaphore set. The following table shows the information returned in the receiver variable for the RSST0100 format. For a detailed description of each field, see Field Descriptions.

RMSQ0100 Format

This format name is used to return information about a single message queue. The following table shows the information returned in the receiver variable for the RMSQ0100 format. For a detailed description of each field, see Field Descriptions.

RSHM0100 Format

This format name is used to return information for a single shared memory object. The following table shows the information returned in the receiver variable for the RSHM0100 format. For a detailed description of each field, see Field Descriptions.

Field Descriptions

Attached qualified job identifier. The job name, the job user profile, and the job number of a job that is attached to the shared memory segment. The 26 characters are:

Authorized to delete. This value determines if the caller has the authority to delete this IPC object. Possible values follow:

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Creator. The name of the user profile that created this IPC object.

Creator's group. The name of the group profile that created this IPC object. A special value can be returned:

Damaged. Whether the IPC object has suffered internal damage. Possible values follow:

General read permission. Whether any user other than the owner and group owner has read authority to the IPC object. Possible values follow:

General write permission. Whether any user other than the owner and group owner has write authority to the IPC object. Possible values follow:

Group owner. The name of the group profile that owns this IPC object. A special value can be returned:

Group read permission. Whether the group owner has read authority to the IPC object. Possible values follow:

Group write permission. Whether the group owner has write authority to the IPC object. Possible values follow:

Identifier. The unique IPC object identifier.

Key. The key of the IPC object. If this value is zero, this IPC object has no key associated with it.

Last administration change date and time. The date and time of the last change to the IPC object for the owner, group owner, or permissions. The 16 characters are:

Last attach or detach process identifier. The process identifier of the thread that performed the last successful attachment or detachment from the shared memory segment. If no thread has attached or detached from the shared memory segment, this field will be zero.

Last attach or detach qualified job identifier. The job name, the job user profile, and the job number of the thread that performed the last successful attachment or detachment from the shared memory segment. The 26 characters are:

These fields will be all blanks if any of the following are true:

• No thread has performed an attachment or detachment on the shared memory.
  
  
• The last process that did an attachment or detachment on the shared memory has ended.
  
  
• The last process that did an attachment or detachment on the shared memory is not initialized for signals.

Last detach date and time. The date and time of the last detachment from the shared memory segment. If no thread has performed a successful detachment, this value will be set to all zeros. The 16 characters are:

Last msgrcv() date and time. The date and time of the last successful msgrcv() call. If no thread has performed a successful msgrcv() call, this value will be set to all zeros. The 16 characters are:

Last msgrcv() process identifier. The process identifier of the thread that performed the last successful msgrcv(). If no thread has done a msgrcv(), this field will be zero.

Last msgrcv() qualified job identifier. The job name, the job user profile, and the job number of the thread that performed the last successful msgrcv(). The 26 characters are:

These fields will be all blanks if any of the following are true:

• No thread has received a message on this message queue.
  
  
• The last process to receive a message has ended.
  
  
• The last process to receive a message has not been initialized for signals.

Last msgsnd() date and time. The date and time of the last successful msgsnd() call. If no thread has performed a successful msgsnd() call, this value will be set to all zeros. The 16 characters are:

Last msgsnd() process identifier. The process identifier of the thread that performed the last successful msgsnd(). If no thread has done a msgsnd(), this field will be zero.

Last msgsnd() qualified job identifier. The job name, the job user profile, and the job number of the thread that performed the last successful msgsnd(). The 26 characters are:

These fields will be all blanks if any of the following are true:

• No thread has sent a message to this message queue.
  
  
• The last process to send a message has ended.
  
  
• The last process to send a message has not been initialized for signals.

Last semop() date and time. The date and time of the last successful semop() call. If no thread has performed a successful semop() call, this value will be set to all zeros. The 16 characters are:

Last shmat() date and time. The date and time of the last successful shmat(). If no thread has performed a successful shmat() call, this value will be set to all zeros. The 16 characters are:

Marked to be deleted. Whether the shared memory is marked to be deleted when the number attached becomes zero. Possible values follow:

Maximum size of all messages on queue. The maximum byte size of all messages that can be on the queue at one time.

Message receive qualified job identifier. The job name, the job user profile, and the job number of the thread that is waiting to receive a message. The 26 characters are:

Message send qualified job identifier. The job name, the job user profile, and the job number of the thread that is waiting to send a message. The 26 characters are:

Message size. The message size of a message that is currently on the queue.

Message type. The message type of a message that is currently on the queue.

Message wait size. The message size of a message that a thread is currently waiting to put on the queue.

Message wait type. The message type that a thread is currently waiting to receive.

Number attached. The number of times any thread has done a shmat() without doing a detach. One process can be attached multiple times to the same shared memory segment.

Number of attach entries. The number of entries in the variable length section of RSHM0100.

Number of threads to receive message. The number of threads that are currently waiting to receive a message.

Number of threads to send message. The number of threads that are currently waiting to send a message.

Number of messages on queue. The number of messages that are currently on the message queue.

Number of semaphores. The number of semaphores in the semaphore set.

Offset to message type. The offset in characters (bytes) from the beginning of the RMSQ0100 record to the message type field.

Offset to times attached. The offset in characters (bytes) from the beginning of the RSHM0100 record to the times attached field.

Offset to wait size. The offset in characters (bytes) from the beginning of the RMSQ0100 record to the wait size field.

Offset to wait type. The offset in characters (bytes) from the beginning of the RMSQ0100 record to the wait type field.

Owner. The name of the user profile that owns this IPC object.

Owner read permission. Whether the owner has read authority to the IPC object. Possible values follow:

Owner write permission. Whether the owner has write authority to the IPC object. Possible values follow:

Page size. The page size (in bytes) of the storage backing the shared memory segment.

Reserved. A reserved field.

Resize. Whether the shared memory object may be resized. Possible values follow:

Segment size. The size of the shared memory segment represented in an UNSIGNED BINARY(4) data type. If the size cannot be fully represented in an UNSIGNED BINARY(4) data type, this field will be set to x'FFFFFFFF' and the Segment size 64 field must be used to get the size of the shared memory segment.

Segment size 64. The size of the shared memory segment represented in an UNSIGNED BINARY(8) data type. This field is set in addition to the value set in the Segment size field. The Segment size field can also be used to obtain the size for shared memory segments whose size can be fully represented in an UNSIGNED BINARY(4) data type.

Size of all messages on queue. The size, in bytes, of all of the messages that are currently on the queue.

Size of attach entry. The size, in bytes, of each attach entry in the array of attach entries.

Size of message information record. The size, in bytes, of each message information record.

Size of message receive record. The size, in bytes, of the record that is used to store information about a thread waiting to receive a message.

Size of message send record. The size, in bytes, of the record that is used to store information about a thread waiting to send a message.

Teraspace. Whether the shared memory object is attachable only to a process's teraspace. Possible values follow:

Times attached. The number of times that this process is attached to the shared memory.

Error Messages

[ Back to top | UNIX-Type APIs | APIs by category ]