w_getipc (BPX1GET, BPX4GET) — Query interprocess communications

Function

The w_getipc service queries shared memory, messages, semaphores, and map service objects for the next or specified member to which the invoker has read access.

Requirements

Parameters

Ipc_Token

Supplied parameter

Type:

Integer

Length:

Word

Specifies a token that corresponds to a message queue, shared memory segment, or semaphore member ID. Zero represents the first member ID. The token to be used in the next invocation is passed back in Return_value. Ipc_Token is ignored when Ipc_OVER is specified.

Ipc_Member_ID

Supplied parameter

Type:

Integer

Length:

Word

Specifies a message queue ID, semaphore ID, or shared member ID.

Buffer_address

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

Address of the buffer structure defined by IPCQ. For the structure describing this buffer, see BPXYIPCQ — Map w_getipc structure.

Buffer_Length

Supplied parameter

Type:

Address

Length:

Fullword

Length of the structure defined by IPCQ. Set to IPCQ#LENGTH. Field IPCQLENGTH will differ from IPCQ#LENGTH when the system call is at a different level than the included IPCQ. An error will be returned if this length is less than 4. The buffer will be filled to the lesser of IPCQ#LENGTH or the value specified here.

Command

Supplied parameter

Type:

Integer

Length:

Fullword

Command	Description
Ipcq#ALL	Retrieve next shared memory, message and semaphore member.
Ipcq#MSG	Retrieve next message member.
Ipcq#SEM	Retrieve next semaphore member.
Ipcq#SHM	Retrieve next shared memory member.
Ipcq#OVER	Overview of system variables. Ignores the value of the first operand (Ipc_Token).
Ipcq#MAP	Retrieve mapped memory objects.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the w_getipc service returns the next Ipc_Token (a negative number), 0, or -1 (error). If Ipc_Token is specified, 0 indicates end of file. If Ipc_Member_ID is specified, 0 indicates success.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the w_getipc service stores the return code. The w_getipc service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The w_getipc service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	Operation permission (read) is denied to the calling process for the Ipc_Member_ID specified. The following reason code can accompany the return code: JRIpcDenied.
EINVAL	The Ipc_Member_ID is not valid for the command specified: The Command parameter is not a valid command. The buffer pointer was zero or the buffer length was less than 4. The following reason codes can accompany the return code: JRBuffTooSmall, JRIpcBadID, or JRBadEntryCode.
EFAULT	An input parameter specified an address that caused the callable service to program check. The following reason code can accompany the return code: JRBadAddress.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the w_getipc service stores the reason code. The w_getipc service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

1. With Ipc_Token, return_values should be tested for 0 (end of file) or -1 (error). Other values are negative and will be the next Ipc_Token.
2. With Ipc_Member_ID, return_values should be tested for -1 (error).
3. A member's accessibility can change if the permissions are changed.
4. A given Ipc_Token may not always retrieve the same member.
5. If a specific member is desired and has been found using Ipc_Token, subsequent requests may place it at that token or later (never earlier).
6. The Ipc_BINSEM, Ipc_MEGA, Ipc_RcvTypePID, Ipc_SndTypePID, Ipc_PLO1, and Ipc_PLO2 bits in the S_MODE field in IpcqIpcp show the values that were requested on the original get request.
7. The Ipc_PLOinUse bit in the S_MODE field in IpcqIpcp shows actual usage of the PLO (Perform Lock Operation) instruction for serialization.
8. When the message queue serialization uses latches, all activity is stopped for the duration of the w_getipc request, and the values that are returned show a snapshot in time.
9. When the message queue serialization uses the PLO instruction (see Ipc_PLOinUse), msgsnd and msgrcv activity continues during the w_getipc request. This can cause misleading results. For example, while the w_getipc service is counting messages on the queue, elements can be added and removed, causing a number that is too high or too low. In the same way, with the msgrcv and msgsnd waiters, a waiter's PID could appear twice in the list.
10. When the Ipcq#MAP command is specified, the w_getipc service returns information about a map service object each time it is called. It also returns a token, which the caller can use on the next call to provide information for the system to find the next map service object.

    With Ipcq#MAP, the w_getipc service may, and likely will, return information about a particular map service object multiple times – once for each process that is using it. If the caller wishes to provide summary information, it is the caller's responsibility to associate the responses for the same map service object with each other. This can be done using the creator PID, because any one process can create only one object, and descendants of that process cannot create a map service object at all. Map service objects are inherited from the parent process.

    The following information is returned for Ipcq#MAP:

    • The creating process's PID. You can use this information to tie together the data returned from other w_getipc calls.
    • The PID of a process that is using this object.
    • The UID of a process that is using this object.
    • The GID of a process that is using this object.
    • The shutdown indicator.
    • The size of the blocks.
    • The number of blocks in the map area.
    • The number of blocks in use.
    • The number of blocks mapped by this process.

    Note: Some of these fields, which are always the same for all processes that are using a particular map service object at any one moment, may differ from one call to another. This is because they may have changed since the w_getipc call for an earlier process. The shutdown indicator, the number of blocks in the map area, and the number of blocks in use, in particular, may show this behavior.

Related services

• shmget (BPX1MGT, BPX4MGT) — Create/find a shared memory segment
• msgget (BPX1QGT, BPX4QGT) — Create or find a message queue
• semget (BPX1SGT, BPX4SGT) — Create or find a set of semaphores

Characteristics and restrictions

There are no restrictions on the use of the w_getipc service.