|
RequirementsOperation |
Environment |
---|
Authorization: |
Supervisor state or problem state; any PSW key |
Dispatchable unit mode: |
Task |
Cross memory mode: |
Any |
AMODE: |
31-bit |
ASC mode: |
Any |
Interrupt status: |
Enabled for interrupts |
Locks: |
Unlocked |
Control parameters: |
All parameters must be addressable by the caller and in the
primary address space. |
FormatCALL osi_kmsgctl,(Message_Queue_ID,
Command,
Buffer,
Return_value,
Return_code,
Reason_code)
Parameters- Message_Queue_ID
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
Specifies the message queue identifier.
- Command
- Supplied parameter
- Type:
- Integer
- Character set:
- N/A
- Length:
- Fullword
The name of a fullword field that indicates the
message command that is to be executed. For the structure that contains
these constants, see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference.
The values for Command are: - Ipc_STAT
- This command obtains status information about the message queue
that is identified by the Message_Queue_ID parameter, if the current
process has read permission. This information is stored in the
area that is pointed to by argument Buffer and mapped by area MSQID_DS
data structure. For the data structure, see MSQID_DS DSECT.
- Ipc_SET
- Set the value of the IPC_UID, IPC_GID, IPC_MODE and MSG_QBYTES
for associated Message_queue_ID. The values that are to be set are
taken from the MSQID_DS data structure that is pointed to by argument
Buffer. Any value for IPC_UID and IPC_GID may be specified. Only mode
bits that are defined by BPX1QGT under the Message_Flag argument may
be specified in the IPC_MODE field. This Command can only be executed
by a task that has an effective user ID equal to either that of a
task with appropriate privileges, or the value of IPC_CUID or IPC_UID
in the MSQID_DS data structure that is associated with Message_Queue_ID.
This information is taken from the buffer that is pointed to by the
Buffer parameter. For the data structure, see MSQID_DS DSECT.
- Ipc_RMID
- Remove the message identifier that is specified by Message_Queue_ID
from the system, and destroy the message queue and MSQID_DS data structure
that are associated with it. This Command can only be executed by
a process that has an effective user ID equal to either that of a
process with appropriate privileges, or the value of IPC_CUID or IPC_UID
in the MSQID_DS data structure that is associated with Message_Queue_ID.
- Buffer
- Parameter supplied and returned
- Type:
- Address
- Length:
- Fullword
The name of the fullword that contains the address
of the buffer into which or from which the message queue information
is to be copied. This buffer is mapped by MSQID_DS.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the osi_kmsgctl
service returns -1 or 0.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the osi_kmsgctl
service stores the return code. The osi_kmsgctl 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 osi_kmsgctl
service can return one of the following values in the Return_code
parameter: Return_code |
Explanation |
---|
EACCES |
The command specified was Ipc_STAT, and the calling process
does not have read permission. The following reason code can accompany
the return code: JRIpcDenied. |
EINVAL |
One of the following errors occurred:- Message_Queue_ID is not a valid Message queue identifier
- The Command parameter is not a valid command.
- The mode bits were not valid (SET).
The following reason codes can accompany the return code: JRIpcBadFlags,
JRMsqQBytes, or JRIpcBadID. |
EPERM |
The command specified was Ipc_RMID or Ipc_SET, and the effective
user ID of the caller is not that of a process with appropriate privileges,
and is not the value of IPC_CUID or IPC_UID in the MSQID_DS data structure
that is associated with Message_Queue_ID. The command
specified was Ipc_SET, and an attempt is being made to increase MSG_QBYTES.
The effective user ID of the caller does not have superuser privileges.
The following reason codes can accompany the return code: JRIpcDenied
or JRMsqQBytes.
|
EFAULT |
The Buffer parameter specified an address that caused the syscall
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 osi_kmsgctl
service stores the reason code. The osi_kmsgctl 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- Changing the access permissions only affects message queue syscall
invocations that occur after msgctl has returned. msgsnd and msgrcv,
which are waiting while the permission bits are changed by msgctl,
are not affected.
- Ipc_SET can change permissions, and might affect the ability of
a thread to use the next message queue syscall.
- Quiescing a message queue stops additional messages from being
added, while allowing existing messages to be received. A message
queue can be quiesced by clearing (Ipc_SET) write permission bits.
- A message queue can also be quiesced by reducing MSG_QBYTES (Ipc_SET)
to zero. (Note: it would take superuser authority to reraise the limit.)
Requesters are told EAGAIN or wait.
- When a message queue ID is removed (Ipc_RMID) from the system,
all waiting threads regain control with RV=-1, RC=EIDRM, and RC=JRIpcRemoved.
- If you do not want to change all the fields, first initialize
(Ipc_STAT) the buffer, change the desired fields, and then make the
change (Ipc_SET).
- For Command Ipc_RMID, the remove is complete by the time control
is returned to the caller.
Characteristics and restrictionsThis service
is invoked only from a colony address space.
The caller is restricted
by ownership, read, and read/write permissions that are defined by
OSI_kmsgget and OSI_kmsgctl Ipc_SET.
|