DosSetPathInfo

Description

Sets information for a file or directory.

Syntax

#define INCL_DOSFILEMGR
#include <os2.h>

PSZ    pszPathName; /* Address of the ASCIIZ full path name of the file or subdirectory. */
ULONG  ulInfoLevel; /* The level of file directory information being defined. */
PVOID  pInfoBuf;    /* Address of the storage area containing the file information being set. */
ULONG  cbInfoBuf;   /* The length, in bytes, of pInfoBuf. */
ULONG  flOptions;   /* Information on how the set operation is to be performed. */
APIRET ulrc;        /* Return Code. */

ulrc = DosSetPathInfo(pszPathName, ulInfoLevel,
         pInfoBuf, cbInfoBuf, flOptions);

Parameters

pszPathName (PSZ) - input

Address of the ASCIIZ full path name of the file or subdirectory.

Global file-name characters are not permitted.

DosQuerySysInfo is called by an application during initialization to determine the maximum path length allowed by the operating system.

ulInfoLevel (ULONG) - input

The level of file directory information being defined.

A value of 1 or 2 can be specified, as shown in the following list.

1 FIL_STANDARD Level 1 file information

2 FIL_QUERYEASIZE Level 2 file information

The structures described in pInfoBuf indicate the information being set for each of these levels.

pInfoBuf (PVOID) - input

Address of the storage area containing the file information being set.

Level 1 File Information (ulInfoLevel == FIL_STANDARD)
    pInfoBuf contains the FILESTATUS3 data structure.

Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE)
    pInfoBuf contains an EAOP2 data structure.

Level 2 sets a series of extended attribute (EA) name/value pairs.

Input : pInfoBuf contains an EAOP2 data structure. fpGEA2List is ignored. fpFEA2List points to a data area where the relevant FEA2 list is to be found. oError is ignored. The FEA2 data structures must be aligned on a doubleword boundary. Each oNextEntryOffset field must contain the number of bytes from the beginning of the current entry to the beginning of the next entry in the FEA2 list. The oNextEntryOffset field in the last entry of the FEA2 list must be zero.

Output : fpGEA2List and fpFEA2List are unchanged. The area that fpFEA2List points to is unchanged. If an error occurred during the set, oError is the offset of the FEA2 entry where the error occurred. The return code is the error code corresponding to the condition that caused the error. If no error occurred, oError is undefined.

cbInfoBuf (ULONG) - input

The length, in bytes, of pInfoBuf.

flOptions (ULONG) - input

Information on how the set operation is to be performed.

If flOptions is 0x00000010 (DSPI_WRTTHRU), then all the information, including extended attributes (EAs), must be written to the disk before returning to the application. This guarantees that the EAs have been written to the disk. All other bits are reserved, and must be zero.

Return Code

ulrc (APIRET) - returns Return Code.

DosSetPathInfo returns one of the following values:

• 0 NO_ERROR
• 2 ERROR_FILE_NOT_FOUND
• 3 ERROR_PATH_NOT_FOUND
• 32 ERROR_SHARING_VIOLATION
• 87 ERROR_INVALID_PARAMETER
• 124 ERROR_INVALID_LEVEL
• 206 ERROR_FILENAME_EXCED_RANGE
• 122 ERROR_INSUFFICIENT_BUFFER
• 254 ERROR_INVALID_EA_NAME
• 255 ERROR_EA_LIST_INCONSISTENT

Remarks

To use DosSetPathInfo to set any level of file information for a file or subdirectory, a process must have exclusive write access to the closed file object. Thus, if the file object is already accessed by another process, any call to DosSetPathInfo will fail.

A value of 0 in the date and time components of a field causes that field to be left unchanged. For example, if both "last write date" and "last write time" are specified as 0 in the Level 1 information structure, then both attributes of the file are left unchanged. If either "last write date" or "last write time" are other than 0, then both attributes of the file are set to the new values.

For data integrity purposes, the Write-Through bit in flOptions should be used only to write the extended attributes to the disk immediately, instead of caching them and writing them later. Having the Write-Through bit set constantly can degrade performance.

In the FAT file system, only the dates and times of the last write can be modified. Creation and last-access dates and times are not affected.

The last-modification date and time will be changed if the extended attributes are modified.

Example Code

This example creates a directory named "HIDEME", makes it hidden, and finally deletes it.

#define INCL_DOSFILEMGR   /* File Manager values */
#define INCL_DOSERRORS    /* DOS Error values    */
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(VOID) {
   UCHAR       achNewDir[256]  = "\\HIDEME";           /* Directory name    */
   FILESTATUS3 fsts3PathInfo   = {{0}};                /* Directory info    */
   ULONG       ulBufferSize    = sizeof(FILESTATUS3);  /* Buffer size       */
   APIRET      rc              = NO_ERROR;             /* Return code       */

   rc = DosCreateDir(achNewDir, (PEAOP2) NULL);        /* Create directory
                                                          with no EAs       */
   if (rc != NO_ERROR) {
      printf("DosCreateDir error: return code = %u\n", rc);
      return 1;
   } else {
      printf("Directory %s created.\n",achNewDir);
   }

   rc = DosQueryPathInfo(achNewDir, FIL_STANDARD,
                        &fsts3PathInfo, ulBufferSize); /* Get standard info */
   if (rc != NO_ERROR) {
      printf("DosQueryPathInfo error: return code = %u\n", rc);
      return 1;
   }

   fsts3PathInfo.attrFile  = FILE_HIDDEN;   /* Add HIDDEN attribute to path */

   rc = DosSetPathInfo(achNewDir,           /* Change directory info on     */
                       FIL_STANDARD,        /* the disk using the buffer    */
                       &fsts3PathInfo,      /* we just updated.             */
                       ulBufferSize,
                       DSPI_WRTTHRU );      /* Write data before returning  */
   if (rc != NO_ERROR) {
       printf("DosSetPathInfo error: return code = %u\n", rc);
       return 1;
   } else {
       printf("Directory %s hidden.\n",achNewDir);
   }
       /* Delete the hidden directory.  If this step is omitted, the directory
          can still be manipulated by standard OS/2 commands like CHDIR and
          RMDIR, it will just not be displayed in a DIR command without the
          /AH display option specified.                                     */

   rc = DosDeleteDir (achNewDir);
   if (rc != NO_ERROR) {
       printf ("DosDeleteDir error : return code = %u\n", rc);
       return 1;
   } else {
       printf("Directory %s deleted.\n",achNewDir);
   }

   return NO_ERROR;
}

Related Functions

• DosEnumAttribute
• DosQueryFileInfo
• DosQueryPathInfo
• DosQuerySysInfo
• DosSetFileInfo