Qp0lSetAttr()--Set Attributes


  Syntax
 #include <Qp0lstdi.h>
 int Qp0lSetAttr
        (Qlg_Path_Name_T     *Path_Name,
         char                *Buffer_ptr,
         uint                 Buffer_Size,
         uint                 Follow_Symlnk, ...);

  Service Program Name: QP0LLIB3

  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes.

The Qp0lSetAttr() function sets one of a set of defined attributes, on each call, for the object that is referred to by the input *Path_Name. The object must exist, the user must have authority to it, and the attribute must be supported by the file system to which the object belongs. When an attribute is not supported by the file system, Qp0lSetAttr() will fail with ENOTSUP. See the Usage Notes for more information.

If the last component of the Path_Name parameter is a symbolic link, the Qp0lSetAttr() either sets the attribute of the symbolic link or sets the attribute of the object that the symbolic link names. This depends on the value of the Follow_Symlnk parameter.

All times that are set by Qp0lSetAttr() are in seconds since the Epoch so that they are consistent with UNIX®-type APIs. The Epoch is the time 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If the system date is set prior to 1970, all time values will be zero.


Parameters

Path_Name
(Input) The path name of the object for which attribute information is set. This path name is in the Qlg_Path_Name_T format. For more information about this structure, see Path name format.

Buffer_ptr
(Input) A pointer to a buffer containing a constant that identifies the attribute and the value for the attribute that Qp0lSetAttr() sets. The number of bytes allocated for this buffer is in the Buffer_Size parameter.

The following table describes the format of the entry in the buffer.

Attribute data. The value to which the attribute is set.

Attribute identification. The constant identifying the attribute being set. Valid values are:

Offset to next attribute entry. (Output) This field is not used by the Qp0lSetAttr() function. It is provided for alignment so that the same buffer format returned from the Qp0lGetAttr() function can be used as input to the Qp0lSetAttr() function.

Reserved. A reserved field. This field must be set to binary zero.

Size of attribute data. The exact size of the data for this attribute. If this size does not match the size that the system stores for this attribute, [EINVAL] is returned.

Buffer_Size
(Input) The size in bytes of the buffer pointed to by the Buffer_ptr parameter.

Follow_Symlnk
(Input) If the last component in the *Path_Name is a symbolic link, Qp0lSetAttr() either acts upon the symbolic link or the path contained in the symbolic link. This depends on the value of the Follow_Symlnk parameter. Valid values are:

Authorities

Note: Adopted authority is not used.







Return Value



Error Conditions

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

Additionally, if interaction with a file server is required to access the object, errno could also indicate one of the following errors:


Error Messages

The following messages may be sent from this function:



Usage Notes

  1. 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
      • QNTC
      • QSYS.LIB
      • Independent ASP QSYS.LIB
      • QOPT
      • Network File System
      • QFileSvr.400

  2. "Root" (/), QOpenSys, and User-Defined File System Differences

    The QP0L_ATTR_CREATE_TIME and QP0L_ATTR_RESET_DATE attributes are supported for objects of type *STMF only. Attempts to set them on other objects will result in the operation failing with errno set to [ENOTSUP].

    The QP0L_ALWSAV_YES value cannot be specified for the QP0L_ATTR_ALWSAV attribute for /dev/null, /dev/zero or objects of type *SOCKET. Attempts to set it on these objects will result in the operation failing with errno set to [ENOTSUP].

    The QP0L_ATTR_SGID attribute of the directory affects what the group ID (GID) is for objects that are created in the directory. If the QP0L_ATTR_SGID attribute of the parent directory is off, the group ID (GID) is set to the effective GID of the thread creating the object. If the QP0L_ATTR_SGID attribute of the parent directory is on, the group ID (GID) of the new object is set to the GID of the parent directory. For all other file systems, the GID of the new object is set to the GID of the parent directory.

    When setting the QP0L_ATTR_RSTDRNMUNL, QP0L_ATTR_SUID, or QP0L_ATTR_SGID attributes on an object that has a primary group, it must match the primary group ID or one of the supplemental group IDs of the caller of this API; otherwise, the QP0L_ATTR_SGID attribute is set to QP0L_SGID_OFF.

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

    The following attributes may be set on objects in these file systems:

    • QP0L_ATTR_CRTOBJAUD
    • QP0L_ATTR_RESET_DATE

      When you set the QP0L_ATTR_RESET_DATE attribute of a database file, all members in that file will have their days used count reset to 0 also.

    Attempting to set any other attribute other than QP0L_ATTR_SUID or QP0L_ATTR_SGID will result in the operation failing with errno set to [ENOTSUP].

    QSYS.LIB and Independent ASP QSYS.LIB do not support setting the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes. They will be ignored if specified.

  4. Network File System Differences

    When you set the following attributes on objects in the Network File System, the operation will fail with the errno set to [ENOTSUP] if the attribute is not set to the following attribute value.

    • If set, QP0L_ATTR_PC_READ_ONLY must be set to an attribute value of QP0L_PC_NOT_READ_ONLY.

    • If set, QP0L_ATTR_PC_HIDDEN must be set to an attribute value of QP0L_PC_NOT_HIDDEN.

    • If set, QP0L_ATTR_PC_SYSTEM must be set to an attribute value of QP0L_PC_NOT_SYSTEM.

    • If set, QP0L_ATTR_PC_ARCHIVE must be set to an attribute value of QP0L_PC_NOT_CHANGED; however, if the object is of type *STMF, the attribute value must be QP0L_PC_CHANGED.

    • If set, QP0L_ATTR_SYSTEM_ARCHIVE must be set to an attribute value of QP0L_SYSTEM_NOT_CHANGED.

    Start of change

    The QP0L_ATTR_CREATE_TIME, QP0L_ATTR_RESET_DATE, QP0L_ATTR_CODEPAGE, QP0L_ATTR_CCSID, QP0L_ATTR_ALWSAV, QP0L_ATTR_ALWCKPWRT, QP0L_ATTR_DISK_STG_OPT, QP0L_ATTR_MAIN_STG_OPT, QP0L_ATTR_CRTOBJAUD, and QP0L_ATTR_INHERIT_ALWCKPWRT attributes cannot be set on objects within the Network File System or they will result in the operation failing with errno set to [ENOTSUP].

    End of change

    The NFS client supports the QP0L_ATTR_SUID, QP0L_ATTR_SGID, and QP0L_ATTR_RSTDRNMUNL attributes by passing them to the server over the network and surfacing them to the caller. Whether a particular network file system supports the setting of these attributes depends on the server. Most servers have the capability of masking off the QP0L_ATTR_SUID and QP0L_ATTR_SGID attributes if the NOSUID option is specified on the export. The default, however, is to support these attributes.

  5. QDLS File System Differences

    The following attributes may be set on objects in this file system:

    • QP0L_ATTR_ACCESS_TIME
    • QP0L_ATTR_CCSID
    • QP0L_ATTR_CODEPAGE
    • QP0L_ATTR_MODIFY_TIME
    • QP0L_ATTR_PC_ARCHIVE
    • QP0L_ATTR_PC_HIDDEN
    • QP0L_ATTR_PC_READ_ONLY
    • QP0L_ATTR_PC_SYSTEM
    • QP0L_ATTR_RESET_DATE (for documents only)

    Attempting to set any other attribute other than the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes will result in the operation failing with errno set to [ENOTSUP].

    QDLS does not support setting the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes. They will be ignored if specified.

  6. QOPT File System Differences

    If you set the QP0L_ALWSAV_YES value for the QP0L_ATTR_ALWSAV attribute, the operation will fail with errno set to [ENOTSUP].

    QOPT does not support setting the QP0L_ATTR_SUID, QP0L_ATTR_SGID, QP0L_ATTR_RSTDRNMUNL, or QP0L_ATTR_CRTOBJAUD attributes for any optical media format.

    If any other attribute is specified, the operation will fail with errno set to [ENOTSUP].

  7. QFileSvr.400 File System Differences

    The following attributes may be set on objects in this file system:

    • QP0L_ATTR_ACCESS_TIME
    • QP0L_ATTR_CCSID
    • QP0L_ATTR_CODEPAGE
    • QP0L_ATTR_CREATE_TIME
    • QP0L_ATTR_CRTOBJAUD
      Note: The QSECOFR user profiles on the source and target system must be enabled, and their passwords must match for the QP0L_ATTR_CRTOBJAUD attribute change to succeed.
    • QP0L_ATTR_CRTOBJSCAN
    • QP0L_ATTR_MODIFY_TIME
    • QP0L_ATTR_PC_ARCHIVE
    • QP0L_ATTR_PC_HIDDEN
    • QP0L_ATTR_PC_READ_ONLY
    • QP0L_ATTR_PC_SYSTEM
    • QP0L_ATTR_SCAN
    • QP0L_ATTR_SYSTEM_ARCHIVE

    Attempting to set any other attribute other than the QP0L_ATTR_SUID, QP0L_ATTR_SGID or QP0L_ATTR_RSTDRNMUNL attributes will result in the operation failing with errno set to [ENOTSUP].

    QFileSvr.400 supports the QP0L_ATTR_SUID, QP0L_ATTR_SGID, and QP0L_ATTR_RSTDRNMUNL attributes by passing them to the server and surfacing them to the caller.

  8. QNTC File System Differences

    The following attributes may be set on objects in this file system:

    • QP0L_ATTR_PC_ARCHIVE
    • QP0L_ATTR_PC_HIDDEN
    • QP0L_ATTR_PC_READ_ONLY
    • QP0L_ATTR_PC_SYSTEM

    Attempting to set any other attribute other than the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes will result in the operation failing with errno set to [ENOTSUP].

    QNTC does not support setting the QP0L_ATTR_SUID or QP0L_ATTR_SGID attributes. They will be ignored if specified.


Related Information


Example

The following example shows a call to the Qp0lSetAttr() and Qp0lGetAttr() APIs.

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>


 int GetAttrObject(
                   Qlg_Path_Name_T *Pathname_ptr,
                   char            *Buffer_ptr,
                   unsigned int    Buffer_size)
 {
  /**************************************************************/
  /*   Local variables                                          */
  /**************************************************************/
   struct attrStruct
   {
     Qp0l_AttrTypes_List_t  attr_struct;
     uint                   AttrTypes[10];
   };
   struct attrStruct  Attr_types_ptr;

   unsigned int buff_size_needed;
   unsigned int num_bytes_returned;
   unsigned int follow_sym;        
   int          rc;

  /**************************************************************/
  /* Start of executable code                                   */
  /**************************************************************/

  /**************************************************************/
  /* Initialize Get Attributes Parameters                       */
  /**************************************************************/
   memset((void *)&Attr_types_ptr, 0x00,sizeof(struct attrStruct));
   Attr_types_ptr.attr_struct.Number_Of_ReqAttrs = 3;
   Attr_types_ptr.AttrTypes[0] = QP0L_ATTR_PC_READ_ONLY;
   Attr_types_ptr.AttrTypes[1] = QP0L_ATTR_PC_HIDDEN;
   Attr_types_ptr.AttrTypes[2] = QP0L_ATTR_CODEPAGE;
   buff_size_needed = 0;
   follow_sym = QP0L_FOLLOW_SYMLNK;

  /**************************************************************/
  /* Call Qp0lGetAttr() to retrieve attributes.                 */
  /**************************************************************/
   rc = Qp0lGetAttr(Pathname_ptr,
                    (Qp0l_AttrTypes_List_t *)&Attr_types_ptr,
                    Buffer_ptr,
                    Buffer_size,
                    &buff_size_needed,
                    &num_bytes_returned,
                    follow_sym);

   if((rc == 0) &&              /* If successful, but           */
      (num_bytes_returned <= 0)) /* Incorrect bytes returned    */
     rc = EUNKNOWN;             /* Unknown error                */

   return(rc);
 }                              /* End GetAttrObject()          */


 int SetAttrObject(
                   Qlg_Path_Name_T *Pathname_ptr,
                   char            *Buffer_ptr,
                   unsigned int    Buffer_size)
 {

  /**************************************************************/
  /*   Local variables                                          */
  /**************************************************************/

   unsigned int       follow_sym;           
   int                rc;
   int                done = 0;
   unsigned int       attrSize;
   Qp0l_Attr_Header_t *attrPtr;

  /**************************************************************/
  /* Start of executable code                                   */
  /**************************************************************/

  /**************************************************************/
  /* Initialize Set Attributes Parameters                       */
  /**************************************************************/
   follow_sym = QP0L_FOLLOW_SYMLNK;

  /**************************************************************/
  /* Qp0lSetAttr() only sets one attribute at a time.  The      */
  /* buffer from Qp0lGetAttr may contain more than one          */
  /* attribute to set.  We may have to call Qp0lSetAttr()       */
  /* multiple times.  The Next_Attr_Offset value is the key.    */
  /* If it is greater than zero, then there is another          */
  /* attribute in the buffer.  Also, it is important to note    */
  /* that the value stored there is the offset from the start   */
  /* of the buffer, not the offset from the start of the        */
  /* current entry.                                             */
  /**************************************************************/
   attrPtr = (Qp0l_Attr_Header_t *)Buffer_ptr;
   while(!done)
   {
       attrSize = attrPtr->Attr_Size +
         sizeof(Qp0l_Attr_Header_t);  /* Calculate attr size    */
       /*********************************************************/
       /* Call Qp0lSetAttr() to set the attribute               */
       /*********************************************************/
       rc=Qp0lSetAttr(Pathname_ptr,
                      (char *)attrPtr,
                      attrSize,
                      follow_sym);
       if(rc != 0)              /* If the function failed       */
         done = 1;              /* End the loop                 */
       else if(attrPtr->Next_Attr_Offset > 0) /* If more data   */
         attrPtr = (Qp0l_Attr_Header_t *) /* Set attribute      */
           (Buffer_ptr + attrPtr->Next_Attr_Offset); /* pointer */
       else                     /* No more data                 */
         done = 1;              /* End the loop                 */
   }
   return(rc);
 }                              /* End SetAttrObject()          */


 int main (int argc, char *argv[])
 {
   #define MYPN "FRED"
   #define MYPN2 "FRED2"
  /**************************************************************/
  /*   Local variables                                          */
  /**************************************************************/
   const char US_const[3] = "US";
   const char Language_const[4] = "ENU";
   const char Path_Name_Del_const[2] = "/";

   typedef struct pnstruct
   {
    Qlg_Path_Name_T  qlg_struct;
    char             pn[sizeof(MYPN)];
   } ;

   typedef struct pnstruct2
   {
    Qlg_Path_Name_T  qlg_struct;
    char             pn[sizeof(MYPN2)];
   } ;

   struct pnstruct pns;
   struct pnstruct2 pns2;
   int rc;

   char  BufferArea[250];
   unsigned int buffer_size = 250;

  /**************************************************************/
  /* Start of executable code                                   */
  /**************************************************************/

  /**************************************************************/
  /* Initialize Pathname for original object                    */
  /**************************************************************/
   memset((void *)&pns, 0, 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));

  /**************************************************************/
  /* Call GetAttrObject to retrieve attributes from the source  */
  /* object.                                                    */
  /**************************************************************/
   rc = GetAttrObject((Qlg_Path_Name_T *)&pns,
                      BufferArea,
                      buffer_size);
   if (rc == 0)                  /* If GetAttr succeeded        */
   {  
    /************************************************************/
    /* Initialize Pathname for target object                    */
    /************************************************************/
     memset((void *)&pns2, 0, sizeof(struct pnstruct2));
     pns2.qlg_struct.CCSID = 37;
     memcpy(pns2.qlg_struct.Country_ID,US_const,2);
     memcpy(pns2.qlg_struct.Language_ID,Language_const,3);;
     pns2.qlg_struct.Path_Type = 0;
     pns2.qlg_struct.Path_Length = sizeof(MYPN2)-1;
     memcpy(pns2.qlg_struct.Path_Name_Delimiter,Path_Name_Del_const,1);
     memcpy(pns2.pn,MYPN2,sizeof(MYPN2));

    /************************************************************/
    /* Call SetAttrObject to set attributes on the target       */
    /* object.                                                  */
    /************************************************************/
     rc=SetAttrObject((Qlg_Path_Name_T *)&pns2,
                       BufferArea,
                       buffer_size);
     if (rc != 0)
     {
       rc = errno;              /* return errno from SetAttrObject */
       printf("Qp0lSetAttr() for %s failed with %i.\n",pns2.pn,rc);
     }
   }                            /* end check GetAttrObject rc      */
   else                         /* GetAttrObject failed            */
   {
     rc = errno;                /* return errno from GetAttrObject */
     printf("Qp0lGetAttr() for %s failed with %s.\n",pns.pn,rc);
   }
   return(rc);
 }                              /* end main                        */

API introduced: V4R4

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