Library: General, File system utilities (OMVFS) Import: omvfs.xmd

Declaration

  export external function describe
                  value stream path
          on      value directory on-dir optional
          into    modifiable stream attributes

Argument definitions

path

The path of the file or directory to be described.

on-dir

A vfs.directory object. If this parameter is specified, the path parameter is interpreted relative to the vfs.directory and must be expressed as a relative URL.

attributes

A variable stream shelf into which the attributes of the file or directory will be placed.

You can use vfs.describe to obtain a description of a file or a directory.

The attributes shelf returned by this function contains the following keyed items.

1. "name" (fully qualified file or directory name)
2. "size" (file size in bytes)
3. "atime"" (last accessed time in OmniMark date format)
4. "mtime" (last modified time in OmniMark date format)
5. "ctime" (last status change time in OmniMark date format)
6. "isdir" (1 if this is a directory, 0 if it is a file)
7. "permissions" (integer representation of file/dir permissions)
8. "owner" (username of owner)
9. "group" (group of file/dir)

The following program prints out the attributes of the specified directory and interprets the "permissions" attribute to determine if user writing is permitted:

  import "omvfs.xmd" prefixed by vfs.

  process
     local stream attr variable
     vfs.describe "c:\foo\bar\" into attr

     repeat over attr
        output key of attr || ": " || attr || "%n"
     again

     do when attr{"isdir"} = 1
        output "This is a directory%n"
     else
        output "This is a file%n"
     done

     output "User write permission: "
     do when attr{"permissions"} mask vfs.permit-user-write > 0
        output "yes%n"
     else
        output "no%n"
     done   

You can determine the value of any one permission by masking the value of the "permissions" attribute with the appropriate vfs permission constant. These constants are described in vfs.change-permissions. If the value returned is 0 then the permission is not set. If a non-zero value is returned, the permission is set.

Exceptions

The following exceptions may occur:

• VFS001 The requested function is not supported for the type of connection
• VFS004 The specified name 'X' exceeds system length limits
• VFS100 The vfsDir object must be connected before it can be used
• VFS105 The path 'X' is not a valid absolute or relative path
• VFS111 The URL 'X' contains invalid encoding
• VFS300 Generic operating system error
• VFS306 The file 'X' does not exist

Troubleshooting

If the drive containing the file or directory being described is a read-only drive (for example, a CD-ROM), the atime may be zero.

If a particular attribute item is not supported by a the file system protocol you are using, it is returned as an empty string.

Related Syntax    vfs.list    vfs.file-name    vfs.file-directory    vfs.directory

Other Library Functions    vfs.change-directory    vfs.change-owner    vfs.change-permissions    vfs.close    vfs.connect    vfs.connect-directory    vfs.copy    vfs.cursor-position    vfs.default-certificates-file    vfs.delete-directory    vfs.delete-file    vfs.describe    vfs.describe-file    vfs.directory    vfs.directory-name    vfs.disconnect    vfs.file    vfs.file-directory    vfs.file-name    vfs.link    vfs.list    vfs.lock    vfs.make-directory    vfs.move    vfs.move-cursor    vfs.omvfs-version    vfs.open    vfs.open-file-system    vfs.open-ftp    vfs.open-http    vfs.open-https    vfs.reader    vfs.set-default-certificates-file    vfs.truncate    vfs.unlock    vfs.writer

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]