getsockopt or setsockopt (BPX1OPT, BPX4OPT) — Get or set options associated with a socket
Function
The getsockopt or setsockopt callable service gets or sets options that are associated with a socket.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | PASN = HASN |
AMODE (BPX1OPT): | 31-bit task or SRB mode |
AMODE (BPX4OPT): | 64-bit task mode only |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
CALL BPX1OPT,(Socket_descriptor,
Operation,
Level,
Option_name,
Option_data_length,
Option_data,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4OPT with the same parameters.
Parameters
- Socket_descriptor
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the socket file descriptor for which the service is to be performed.
- Operation
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the operation option. The value of this field determines whether the service to be performed is getsockopt, setsockopt, or setibmsockopt. See BPXYSOCK — Map SOCKADDR structure and constants for valid Operation values.
- Level
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the level for which the option is set or being set.
- Option_name
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field in which the value of the option name is provided. See BPXYSOCK — Map SOCKADDR structure and constants for valid Option_name values.
- Option_data_length
- Supplied and returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a field that contains the length of Option_data. On return from getsockopt, this field contains the size of the data that was returned in Option_data. The size of this field should be less than 4096 bytes (4KB) in length. The size of the buffer specified should be the maximum length that the option_data could be on output.
- Option_data
- Supplied and returned parameter
- Type:
- Character
- Length:
- Length specified by Option_data_length.
The name of a field that contains the data that is associated with or is to be associated with the socket. On return from getsockopt, this field contains the data that is associated with the socket. For setsockopt, this field provides the data that is to be associated with the socket.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getsockopt or setsockopt service returns one of the following:0
if the request is successful.-1
if the request is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getsockopt or setsockopt service stores the return code. The getsockopt or setsockopt service returns Return_code. only if Return_value is-1
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The getsockopt or setsockopt service can return one of the following values in the Return_code parameter:Return_code Explanation EDOM An argument that is too large was supplied on the call. EINVAL An incorrect argument was supplied on the call. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRLevelNotSupp. ENOBUFS A buffer could not be obtained. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JROutofSocketCells. ENOPROTOOPT An option_name that was specified for getsockopt is not supported. An incorrect value was specified on the Level parameter. SOL_SOCKET must be specified. Consult Reason_code to determine the exact reason the error occurred. The following reason codes can accompany the return code: JRLevelNotSupp, JRInvalOpOpt, JROptNotSupp. ENOSYS For AF_UNIX, setsockopt was specified; it is not supported. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRSetNotSupp. ENOTSOCK Socket_descriptor does not refer to a valid socket descriptor. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JRMustBeSocket. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getsockopt or setsockopt service stores the reason code. The getsockopt or setsockopt service returns Reason_code only if Return_value is
-1
. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- The socket descriptor must refer to an open socket.
- For AF_UNIX sockets, the getsockopt() service supports the following option_names only: so_acceptconn, so_type, and so_secinfo.
- The level of support for this service depends on the particular socket stack you have installed. Some options might not be defined by the BPXYSOCK macro. Refer to the documentation for the product you are using to determine the socket options it supports. For example, see z/OS Communications Server: IPv6 Network and Appl Design Guide for the z/OS® Communications Server socket stack.
- See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
Characteristics and restrictions
There are no restrictions on the use of the getsockopt or setsockopt service.