osi_getcred — Obtain SAF UIDs, GIDs and supplementary GIDs

Function

The osi_getcred obtains the real, effective, and saved user IDs; group IDs; and supplementary group IDs from SAF.

Requirements

Operation	Environment
Authorization:	Supervisor 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, except for the Getcred_Parms and area for the supplemental GIDs, must be in the primary address space.

Format

     osi_getcred(OSI_structure,
              Workarea,
              Alet,
              Getcred_Parms,
              Return_value,
              Return_code,
              Reason_code);

Parameters

OSI_structure

Supplied parameter

Type:: Structure
Length:: Specified by the Osilen field

OSI_structure contains information that is used by the OSI operations. The PFS receives this structure on each PFS interface operation.

Refer to Interface structures for C language servers and clients for a full description of this structure.

Workarea

Supplied parameter

Type:: Char
Length:: 3072 bytes

Workarea is a buffer of 3072 bytes (3K), aligned on a doubleword boundary, that is to be used by this OSI operation.

Alet

Supplied parameter

Type:: Integer
Length:: Fullword

The Alet for the Getcred_Parms structure and the supplementary GID list that is pointed to by Getcred_Parms.

Getcred_parms

Supplied parameter

Type:: Structure
Length:: Specified by sizeof(OGCDPRM)

An area that contains the osi_getcred parameters. The entries in this area are mapped by the OGCDPRM typedef, which is defined in the BPXYPFSI header.

Refer to Interface structures for C language servers and clients for a full description of this structure. Following is a description of the parameters in this structure:

oc_hdr: A header that contains an eyecatcher and length. It can be initialized using OGCDPRM_HDR.
oc_real_uid: The real UID, returned by the security product.
oc_effective_uid: The effective UID, returned by the security product.
oc_saved_uid: The saved UID, returned by the security product.
oc_real_gid: The real GID, returned by the security product.
oc_effective_gid: The effective GID, returned by the security product.
oc_saved_gid: The saved GID, returned by the security product.
oc_maxsgids: Set by the invoker to the maximum number of supplementary GIDs that will fit in the area that is pointed to by oc_gid_list. If there is not enough room for all available GIDs, this maximum is returned. In this case, this field is updated, on return to the caller, to indicate the total number of GIDs which could have been returned had there been room for all.
oc_numsgids: The number of supplementary GIDs returned by the security product.
oc_gid_list: A pointer to an area to contain the array of supplementary GIDs.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the osi_getcred service returns the results of the service, as one of the following:

Return_value: Meaning
-1: The operation was not successful. The Return_code and Reason_code parameters contain the values returned by the service.
0: The operation was successful, and there was room for all supplementary GIDs in the caller-provided area.
+1: The operation was successful, but there were more supplementary GIDs than could fit in the caller-provided area. A partial list of GIDs has been returned. The oc_maxsgids field has been updated with the actual number of supplementary GIDs that are available. The oc_maxsgids field should be reset to the proper value, if necessary, before the Getcred_Parms structure is used again on a subsequent call.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the osi_getcred service stores the return code. The osi_getcred service returns Return_code only if Return_value is -1. For a complete list of supported return code values, see z/OS UNIX System Services Messages and Codes.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the osi_getcred service stores the reason code. The osi_getcred service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. The reason codes are described in z/OS UNIX System Services Messages and Codes.

Note that if the Return_code that is returned by osi_getcred is EMVSSAF2ERR, the low-order two bytes of the Reason_code will be the RACF® return and reason codes.

Usage notes

The osi_getcred calls SAF to obtain the UID and GID information.
If there is not room in the supplementary GID area, SAF returns as many as will fit. A return value of 1 indicates that this has occurred. In this case, the oc_maxsgids field is updated with the number that would have been returned had there been room for all supplementary GIDs. The caller should not depend upon those GIDs that are returned when there is not enough room for all supplementary GIDs. The subset of the available GIDs that is returned may differ among various security products, or even from call to call for some security products.
The OSI_structure contains an area that is pointed to by osi_workarea, which may be passed to this service as the Workarea parameter.

Related services

None.

Characteristics and restrictions

None.