Name
hw_Stat -- examine a file system object (V6.0)
Synopsis
int ok = hw_Stat(STRPTR name, ULONG flags, struct hwos_StatStruct *st,
                     struct hwTagList *tags);
Function
This function examines the file system object specified in parameter 1 and writes information about it to the structure pointer passed in parameter 3. struct hwos_StatStruct looks like this:

 
struct hwos_StatStruct
{
    int Type;                               // [out]
    DOSINT64 Size;                          // [out]
    ULONG Flags;                            // [out]
    struct hwos_DateStruct Time;            // [out]
    struct hwos_DateStruct LastAccessTime;  // [out]
    struct hwos_DateStruct CreationTime;    // [out]
    STRPTR FullPath;                        // [out]
    STRPTR Comment;                         // [out]
    int LinkMode;                           // [out]
    STRPTR Container;                       // [out]
};

The following information is written to the individual structure members:

Type:
This will be set to one of the following types:

HWSTATTYPE_FILE:
The file system object examined is a file.

HWSTATTYPE_DIRECTORY:
The file system object examined is a directory.

Size:
Size of object in bytes if it is a file, 0 for directories. Note that this can also be set to -1 in case the file size isn't know, for example because the file is being streamed from a network source.

Flags:
Combination of flags describing the file system object attributes. See File attributes for a list of supported attributes.

Time:
Time stamp indicating when this file system object was last modified.

LastAccessTime:
Time stamp indicating when this file system object was last accessed.

CreationTime:
Time stamp indicating when this file system object was created.

FullPath:
Fully qualified path to the file system object. The string pointer used here will stay valid until the next call to hw_Stat(). If you set the HWSTATFLAGS_ALLOCSTRINGS flag, hw_Stat() will not use a static string buffer but allocate a new private string pointer for this structure member. You will have to call hw_TrackedFree() on this string when you're done with it in that case. This is useful if you need to use hw_Stat() in a multithreaded environment.

Comment:
Comment stored for this object in the file system. The string pointer returned here will stay valid until the next call to hw_Stat(). This may be NULL if the file system does not support comments for its objects. If you set the HWSTATFLAGS_ALLOCSTRINGS flag, hw_Stat() will not use a static string buffer but allocate a new private string pointer for this structure member. You will have to call hw_TrackedFree() on this string when you're done with it in that case. This is useful if you need to use hw_Stat() in a multithreaded environment.

LinkMode:
Currently unused. May contain random data.

Container:
Currently unused. May contain random data.

The following flags are supported by hw_Stat():

HWSTATFLAGS_NOFILEADAPTER:
If this flag is set, Hollywood will skip all file adapters and use its inbuilt file handler for examining this file system object. Use only if you have a good reason for overriding file adapters.

HWSTATFLAGS_ALLOCSTRINGS:
If you set this flag, hw_Stat() will not use static string buffers for the FullPath and Comment structure members but allocate new private string buffers for them. You will have to call hw_TrackedFree() on these buffers once you're done with them in that case. This flag is useful if you need to use hw_Stat() in a multithreaded environment.

hw_Stat() returns True on success or False on failure.

hw_Stat() can be used to find out whether a certain file system object is a file or a directory or to resolve relative file name specifications into absolute, fully-qualified paths.

This function is only thread-safe if you set the HWSTATFLAGS_ALLOCSTRINGS flag.

Designer compatibility
Supported since Designer 4.5

Inputs
name
name of file system object to examine
flags
combination of flags (see above)
st
pointer to a struct hwos_StatStruct for storing information about the file system object
tags
reserved for future use (pass NULL)
Results
ok
True on success, False otherwise

Show TOC