# GETFILEINFOQQ

Portability Function: Returns information about the specified file. File names can contain wildcards (* and ?).

## Module

USE IFPORT

result = GETFILEINFOQQ (files,buffer,handle)

files | (Input) Character*(*). Name or pattern of files you are searching for. Can include a full path and wildcards (* and ?).
buffer | (Output) Derived type `FILE$INFO` or derived type `FILE$INFOI8`. Information about a file that matches the search criteria in files. The derived type `FILE$INFO` is defined in `IFPORT.F90` as follows:
    TYPE FILE$INFO
      INTEGER(4) CREATION             ! CREATION TIME (-1 on FAT)
      INTEGER(4) LASTWRITE            ! LAST WRITE TO FILE
      INTEGER(4) LASTACCESS           ! LAST ACCESS (-1 on FAT)
      INTEGER(4) LENGTH               ! LENGTH OF FILE
      INTEGER(4) PERMIT               ! FILE ACCESS MODE
      CHARACTER(255) NAME             ! FILE NAME
    END TYPE FILE$INFO
The derived type `FILE$INFOI8` is defined in `IFPORT.F90` as follows:
    TYPE FILE$INFOI8
      INTEGER(4) CREATION             ! CREATION TIME (-1 on FAT)
      INTEGER(4) LASTWRITE            ! LAST WRITE TO FILE
      INTEGER(4) LASTACCESS           ! LAST ACCESS (-1 on FAT)
      INTEGER(8) LENGTH               ! LENGTH OF FILE
      INTEGER(4) PERMIT               ! FILE ACCESS MODE
      CHARACTER(255) NAME             ! FILE NAME
    END TYPE FILE$INFOI8
handle | (Input; output) INTEGER(4) on IA-32 architecture; INTEGER(8) on Intel® 64 architecture. Control mechanism. One of the following constants, defined in `IFPORT.F90`: FILE$FIRST - First matching file found. FILE$LAST - Previous file was the last valid file. FILE$ERROR - No matching file found.

## Results

The result type is INTEGER(4). The result is the nonblank length of the file name if a match was found, or 0 if no matching files were found.

To get information about one or more files, set the handle to FILE$FIRST and call GETFILEINFOQQ. This will return information about the first file which matches the name and return a handle. If the program wants more files, it should call GETFILEINFOQQ with the handle. GETFILEINFOQQ must be called with the handle until GETFILEINFOQQ sets handle to FILE$LAST, or system resources may be lost.

The derived-type element variables FILE$INFO%CREATION, FILE$INFO%LASTWRITE, and FILE$INFO%LASTACCESS contain packed date and time information that indicates when the file was created, last written to, and last accessed, respectively.

To break the time and date into component parts, call UNPACKTIMEQQ. FILE$INFO%LENGTH contains the length of the file in bytes. FILE$INFO%PERMIT contains a set of bit flags describing access information about the file as follows:

Bit flag | Access information for the file
--- | ---
FILE$ARCHIVE | Marked as having been copied to a backup device.
FILE$DIR | A subdirectory of the current directory. Each MS-DOS* directory contains two special files, "." and "..". These are directory aliases created by MS-DOS for use in relative directory notation. The first refers to the current directory, and the second refers to the current directory's parent directory.
FILE$HIDDEN | Hidden. It does not appear in the directory list you request from the command line, the Microsoft* visual development environment browser, or File Manager.
FILE$READONLY | Write-protected. You can read the file, but you cannot make changes to it.
FILE$SYSTEM | Used by the operating system.
FILE$VOLUME | A logical volume, or partition, on a physical disk drive. This type of file appears only in the root directory of a physical device.

You can use the constant FILE$NORMAL to check that all bit flags are set to 0. If the derived-type element variable FILE$INFO%PERMIT is equal to FILE$NORMAL, the file has no special attributes. The variable FILE$INFO%NAME contains the short name of the file, not the full path of the file.

If an error occurs, call GETLASTERRORQQ to retrieve the error message, such as:

- ERR$NOENT: The file or path specified was not found.

- ERR$NOMEM: Not enough memory is available to execute the command, the available memory has been corrupted, or an invalid block exists, indicating that the process making the call was not allocated properly.

## Example

    USE IFPORT
    USE IFCORE
      CALL SHOWPERMISSION( )
    END

    ! SUBROUTINE to demonstrate GETFILEINFOQQ
    SUBROUTINE SHOWPERMISSION( )
    USE IFPORT
      CHARACTER(80) files
      INTEGER(KIND=INT_PTR_KIND( )) handle
      INTEGER(4) length
      CHARACTER(5) permit
      TYPE (FILE$INFO) info
        WRITE (*, 900) ' Enter wildcard of files to view: '
        900 FORMAT (A, \)

        length = GETSTRQQ(files)
        handle = FILE$FIRST

        DO WHILE (.TRUE.)
          length = GETFILEINFOQQ(files, info, handle)
          IF ((handle .EQ. FILE$LAST) .OR. &
              (handle .EQ. FILE$ERROR)) THEN
             SELECT CASE (GETLASTERRORQQ( ))
               CASE (ERR$NOMEM)
                 WRITE (*,*) 'Out of memory'
               CASE (ERR$NOENT)
                 EXIT
               CASE DEFAULT
                 WRITE (*,*) 'Invalid file or path name'
             END SELECT
          END IF

          permit = ' '
          IF ((info%permit .AND. FILE$HIDDEN) .NE. 0) &
             permit(1:1) = 'H'
          IF ((info%permit .AND. FILE$SYSTEM) .NE. 0) &
             permit(2:2) = 'S'
          IF ((info%permit .AND. FILE$READONLY) .NE. 0) &
             permit(3:3) = 'R'
          IF ((info%permit .AND. FILE$ARCHIVE) .NE. 0) &
             permit(4:4) = 'A'
          IF ((info%permit .AND. FILE$DIR) .NE. 0) &
             permit(5:5) = 'D'
          WRITE (*, 9000) info%name, info%length, permit
          9000 FORMAT (1X, A5, I9, ' ',A6)
        END DO
    END SUBROUTINE

Parent topic: G

## See Also

SETFILEACCESSQQ
SETFILETIMEQQ
UNPACKTIMEQQ