QlgChangeAuthority()--Change Authority (using NLS-enabled path name)


  Syntax
 #include <Qp0lstdi.h>
 int QlgChangeAuthority
   (Qlg_Path_Name_T         *Path_Name,
    uint                     Num_User_Names,
    char                    *User_Names_ptr,
    char                    *Data_Auth_ptr,
    uint                     Num_Object_Auths,
    char                    *Object_Auth_ptr,
    char                    *Auth_List_ptr,
    uint                     Follow_Symlnk);

  Service Program Name: QP0LLIB2

  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes.

The QlgChangeAuthority() function can be used to perform the following operations on an integrated file system object:

  1. Add, remove, or change the authorization list
  2. Change private authorities
  3. Change public authorities

The function can perform only one of the above functions at a time. The object referred to by the input Path_Name must exist, the user must have authority to it, and the specified authority information must be supported by the specific file system or object type.

QlgChangeAuthority() either changes the authority of a symbolic link, or changes the authority of the object that the symbolic link names. This depends upon the value of the Follow_Symlnk parameter.

Parameters

Path_Name
(Input) Specifies the object for which specific authorities are to be given to one or more users or to an authorization list. This path name is in the Qlg_Path_Name_T format. For more information on this structure, see Path name format.

Num_User_Names
(Input) Specifies the number of users in the user name array pointed to by the User_Names_ptr parameter. If this parameter is 0, the Auth_List_ptr parameter must not be a NULL pointer.

User_Names_ptr
(Input) Specifies the users for whom authorities to the object specified by Path_Name are to be changed. If the Num_User_Names parameter is 0, this parameter is ignored. If the Num_User_Names is not 0, this parameter must point to an array of CHAR(10) blank-padded user names. If user names are specified, the authorities are changed specifically for those users. The following special value can be specified as the only entry in the list (Num_User_Names must be 1):
Data_Auth_ptr
(Input) Specifies the data authorities to be given to the users specified for the User_Names_ptr parameter. If the Num_User_Names parameter is 0, this parameter is ignored. If the Num_User_Names is not 0, this parameter must point to a CHAR(10) area that contains one of the following values, blank-padded to 10 bytes:
Num_Object_Auths
(Input) Specifies the number of entries in the object authority array pointed to by the Object_Auth_ptr parameter. If the Num_User_Names parameter is 0, this parameter is ignored. If the Num_User_Names is not 0, this parameter must not be zero. The maximum allowable value is Start of change10End of change.

Object_Auth_ptr
(Input) Specifies the object authorities to be given to the users specified for the User_Names_ptr parameter. If *OBJAUT is specified for the Data_Auth_ptr parameter, this parameter also specifies additional detailed data authorities to be given to the users. If the Num_User_Names parameter is 0, this parameter is ignored. If the Num_User_Names is not 0, this parameter must point to a list of CHAR(10) authority specifiers. The list must contain the number of entries specified in the Num_Object_Auths parameter. Each entry in the list may contain one of the following values, blank-padded to 10 bytes.
Auth_List_ptr
(Input) Specifies the authorization list whose users are to be given authority to the object specified for the Path_Name parameter. If the Num_User_Names parameter is not zero, this parameter must be NULL. If the Num_User_Names parameter is zero, this parameter must point to a CHAR(10) area containing an authorization list name or the following special value:
Follow_Symlnk
(Input) If the last component in the Path_Name is a symbolic link, this parameter determines if the symbolic link or the path contained in the symbolic link is acted upon. Valid values are:

Authorities

Note: Adopted authority is not used.







Return Value



Error Conditions

If QlgChangeAuthority() is not successful, errno indicates one of the following errors:


Error Messages

The following messages may be sent from this function:



Usage Notes

  1. The following file systems do not support QlgChangeAuthority():
    • Network File System
    • QFileSvr.400
    • QNTC

    In addition, only the authority of optical volumes may be changed in the QOPT file system.


  2. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
    • Where multiple threads exist in the job.
    • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
      • "Root" (/)
      • QOpenSys
      • User-defined
      • QSYS.LIB
      • Independent ASP QSYS.LIB

  3. User profile names, authorization list names, and all special values for the User_Names_ptr, Data_Auth_ptr, Object_Auth_ptr, and Auth_List_ptr parameters are expected to be in coded character set ID 37.

  4. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

    QlgChangeAuthority() cannot be used to change the authority attributes of a physical file member. Such a request will fail with an errno of ENOTSUP.

    This command must get an exclusive lock on a database file before read or object operational authority can be given to a user.

    If a user requests authority for another specified user to a device currently in use by another authorized user, authority to the device is not given.

    This API should not be used to change the authority for an authorization list object (/QSYS.LIB/authorization-list-name.AUTL).

    Before you give authorities to use a device, controller, or line description, its associated device, controller, or line must be varied on.

  5. Start of changeThe descriptions for the *READ, *ADD, *UPD, *DLT, and *EXECUTE values of the Object_Auth_ptr parameter specify that the values confer only "partial" authority to perform various functions on the object. This partial authority is sufficient to perform certain operations in the QSYS.LIB, independent ASP QSYS.LIB, and QDLS file systems, but only when using interfaces outside the integrated file system. In effect, you can use QlgChangeAuthority() to grant users the same authorities to these objects as the "Grant Object Authority (GRTOBJAUT)" and "Add DLO Authority (ADDDLOAUT)" commands.

    However, when using integrated file system interfaces, these user-defined combinations of authorities are mapped to the standard data authorities (*RWX) according to the following:

    • *OBJOPR and *READ is equivalent to *R data authority
    • *OBJOPR, *ADD, *UPD, and *DLT is equivalent to *W data authority
    • *OBJOPR and *EXECUTE is equivalent to *X data authority

    Unless a user has all of the detail data authorities that map to the standard data authority, the user does not have that standard data authority through integrated file system interfaces. For example, granting a user *READ detail data authority does not actually grant the user the same access to an integrated file system object as granting *R data authority. To get the equivalent authority, the user must be granted *OBJOPR and *READ. A user that had every one of the detail data authorities except for *OBJOPR would have no data authority to perform any operation on an object through integrated file system interfaces.End of change


Related Information


Example

The following example shows a call to QlgChangeAuthority().

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

/*****************************************************************/
#include "Qp0lstdi.h"
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <sys/types.h>
#include <qusec.h>
#include <time.h>

int main (int argc, char *argv[])
{
#define MYPN "ADIR/ASTMF"
  const char US_const[3]= "US";
  const char Language_const[4]="ENU";
  const char Path_Name_Del_const[2] = "/";
  const char Data_Auth[11] = "*OBJAUT   ";
  const char Object_Auths[41] =
    "*OBJALTER *OBJREF   *OBJOPR   *READ     ";
  const char User_Names[21] = "USERA     USERB     ";

  struct pnstruct
  {
    Qlg_Path_Name_T  qlg_struct;
    char             pn[100];
  };
  struct pnstruct pns;
  struct pnstruct *pns_ptr = NULL;

  unsigned int follow_sym;
  int done=0;
  int rc;

  /**************************************************************/
  /* Initialize Change Authority Parameters                     */
  /**************************************************************/
  memset((void*)&pns, 0x00, sizeof(struct pnstruct));
  pns.qlg_struct.CCSID = 37;
  memcpy(pns.qlg_struct.Country_ID,US_const,2);
  memcpy(pns.qlg_struct.Language_ID,Language_const,3);
  pns.qlg_struct.Path_Type = 0;
  pns.qlg_struct.Path_Length = sizeof(MYPN)-1;
  memcpy(pns.qlg_struct.Path_Name_Delimiter,Path_Name_Del_const,1);
  memcpy(pns.pn,MYPN,sizeof(MYPN));
  pns_ptr = &pns;
  follow_sym = QP0L_FOLLOW_SYMLNK;

  /**************************************************************/
  /* Call the QlgChangeAuthority() API to change the authority  */
  /* of "ADIR/ASTMF".                                           */
  /**************************************************************/
  rc = QlgChangeAuthority((Qlg_Path_Name_T *)&pns,
                          2,
                          User_Names,
                          Data_Auth,
                          4,
                          Object_Auths,
                          (char *)NULL,
                          follow_sym);
  if (rc != 0)                      /* check API return code */
  {
    rc = errno;
    printf("ERROR on QlgChangeAuthority(): error = %d\n", rc);
    perror("Error message");
  }
  return(rc);
} /* end main */

API introduced: IBM® i 7.2

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