HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


stat

Accesses information about the specified file.

Format

#include <stat.h>

int stat (const char *file_spec, struct stat *buffer); (ISO POSIX-1)

int stat (const char *file_spec, struct stat *buffer, ...); (HP C EXTENSION)

Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to the stat function that is equivalent to the behavior before OpenVMS Version 7.0.

Compiling with the _USE_STD_STAT feature-test macro defined enables a variant of the stat function that uses an X/Open standard-compliant definition of the stat structure. The _USE_STD_STAT feature-test macro is mutually exclusive with the _DECC_V4_SOURCE and _VMS_V6_SOURCE macros.


Arguments

file_spec

A valid OpenVMS or UNIX style file specification (no wildcards). Read, write, or execute permission of the named file is not required, but you must be able to reach all directories listed in the file specification leading to the file. For more information about UNIX style file specifications, see Chapter 1.

buffer

A pointer to a structure of type stat . For convenience, a typedef stat_t is defined as struct stat in the <stat.h> header file.

This argument receives information about the particular file. The members of the structure pointed to by buffer are described in the Description section.

...

An optional default file-name string.

This is the only optional RMS keyword that can be specified for the stat function. See the description of the creat function for the full list of optional RMS keywords and their values.


Description

When the _USE_STD_STAT feature-test macro is not enabled, the legacy stat structure is used. When _USE_STD_STAT is enabled, the X/Open standard-compliant stat structure is used.

Legacy stat Structure

With the _USE_STD_STAT feature-test macro defined to DISABLE, the following legacy stat structure is used:
Member Type Definition
st_dev dev_t Pointer to the physical device name
st_ino[3] ino_t Three words to receive the file ID
st_mode mode_t File "mode" (prot, dir,...)
st_nlink nlink_t For UNIX system compatibility only
st_uid uid_t Owner user ID
st_gid gid_t Group member: from st_uid
st_rdev dev_t UNIX system compatibility -- always 0
st_size off_t File size, in bytes. For st_size to report a correct value, you need to flush both the C RTL and RMS buffers.
st_atime time_t File access time; always the same as st_mtime
st_mtime time_t Last modification time
st_ctime time_t File creation time
st_fab_rfm char Record format
st_fab_rat char Record attributes
st_fab_fsz char Fixed header size
st_fab_mrs unsigned Record size

The types dev_t , ino_t , off_t , mode_t , nlink_t , uid_t , gid_t , and time_t , are defined in the <stat.h> header file. However, when compiling for compatibility (/DEFINE=_DECC_V4_SOURCE), only dev_t , ino_t , and off_t are defined.

The off_t data type is either a 32-bit or 64-bit integer. The 64-bit interface allows for file sizes greater than 2 GB, and can be selected at compile time by defining the _LARGEFILE feature-test macro as follows:


CC/DEFINE=_LARGEFILE 

As of OpenVMS Version 7.0, times are given in seconds since the Epoch (00:00:00 GMT, January 1, 1970).

The st_mode structure member is the status information mode defined in the <stat.h> header file. The st_mode bits are described as follows:
Bits Constant Definition
0170000 S_IFMT Type of file
0040000 S_IFDIR Directory
0020000 S_IFCHR Character special
0060000 S_IFBLK Block special
0100000 S_IFREG Regular
0030000 S_IFMPC Multiplexed char special
0070000 S_IFMPB Multiplexed block special
0004000 S_ISUID Set user ID on execution
0002000 S_ISGID Set group ID on execution
0001000 S_ISVTX Save swapped text even after use
0000400 S_IREAD Read permission, owner
0000200 S_IWRITE Write permission, owner
0000100 S_IEXEC Execute/search permission, owner

The stat function does not work on remote network files.

If the file is a record file, the st_size field includes carriage-control information. Consequently, the st_size value will not correspond to the number of characters that can be read from the file.

Also be aware that for st_size to report a correct value, you need to flush both the C RTL and RMS buffers.

Standard-Compliant stat Structure

With OpenVMS Version 8.2, the _USE_STD_STAT feature-test macro and standard-compliant stat structure are introduced in support of UNIX compatibility.

With _USE_STD_STAT defined to ENABLE, you get the following behavior:

Note (INTEGRITY SERVERS, ALPHA)

On OpenVMS Alpha and Integrity server systems, the stat , fstat , utime , and utimes functions have been enhanced to take advantage of the new file-system support for POSIX compliant file timestamps.

This support is available only on ODS-5 devices on OpenVMS Alpha systems beginning with a version of OpenVMS Alpha after Version 7.3.

Before this change, the stat and fstat functions were setting the values of the st_ctime , st_mtime , and st_atime fields based on the following file attributes:
st_ctime - ATR$C_CREDATE (file creation time)
st_mtime - ATR$C_REVDATE (file revision time)
st_atime - was always set to st_mtime because no support for file access time was available


Also, for the file-modification time, utime and utimes were modifying the ATR$C_REVDATE file attribute, and ignoring the file-access-time argument.

After the change, for a file on an ODS-5 device, the stat and fstat functions set the values of the st_ctime , st_mtime , and st_atime fields based on the following new file attributes:
st_ctime - ATR$C_ATTDATE (last attribute modification time)
st_mtime - ATR$C_MODDATE (last data modification time)
st_atime - ATR$C_ACCDATE (last access time)


If ATR$C_ACCDATE is zero, as on an ODS-2 device, the stat and fstat functions set st_atime to st_mtime .

For the file-modification time, the utime and utimes functions modify both the ATR$C_REVDATE and ATR$C_MODDATE file attributes. For the file-access time, these functions modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device has no effect.

For compatibility, the old behavior of stat , fstat , utime , and utimes remains the default, regardless of the kind of device.

The new behavior must be explicitly enabled by defining the DECC$EFS_FILE_TIMESTAMPS logical name to ENABLE before invoking the application. Setting this logical does not affect the behavior of stat , fstat , utime , and utimes for files on an ODS-2 device.

Return Values

0 Indicates success.
- 1 Indicates an error other than a privilege violation; errno is set to indicate the error.
- 2 Indicates a privilege violation.

statvfs (INTEGRITY SERVERS, ALPHA)

Gets information about a device containing the specified file.

Format

#include <statvfs.h>

int statvfs (const char *restrict path, struct statvfs *restrict buffer);


Arguments

path

Any file on a mounted device.

buffer

Pointer to a statvfs structure to hold the returned information.

Description

The statvfs function returns descriptive information about the device containing the specified file. Read, write, or execute permission of the specified file is not required. The returned information is in the format of a statvfs structure, which is defined in the <statvfs.h> header file and contains the following members:
unsigned long f_bsize - Preferred block size.

unsigned long f_frsize - Fundamental block size.

fsblkcnt_t f_blocks - Total number of blocks in units of f_frsize .

fsblkcnt_t f_bfree - Total number of free blocks. If f_bfree would assume a meaningless value due to the misreporting of free block count by $GETDVI for a DFS disk, then f_bfree is set to the maximum block count.

fsblkcnt_t f_bavail - Number of free blocks available. Set to the unused portion of the caller's disk quota.

fsfilcnt_t f_files - Total number of file serial numbers (for example, inodes).

fsfilcnt_t f_ffree - Total number of free file serial numbers. For OpenVMS systems, this value is calculated as freeblocks/clustersize.

fsfilcnt_t f_favail - Number of file serial numbers available to a non-privileged process (0 for OpenVMS systems).

unsigned long f_fsid - File system identifier. This identifier is based on the allocation-class device name. This gives a unique value based on device, as long as the device is locally mounted.

unsigned long f_flag - Bit mask representing one or more of the following flags:
ST_RONLY - The volume is read-only.
ST_NOSUID - The volume has protected subsystems enabled.


unsigned long f_namemax - Maximum length of a filename.
char f_basetype[64] - Device-type name.
char f_fstr[64] - Logical volume name.
char __reserved[64] - Media type name.

Upon successful completion, statvfs returns 0 (zero). Otherwise, it returns - 1 and sets errno to indicate the error.

See also fstatvfs .


Return Value

0 Successful completion.
- 1 Indicates an error. errno is set to one of the following:
  • EACCES - Search permission is denied for a component of the path prefix.
  • EIO - An I/O error occurred while reading the device.
  • EINTR - A signal was intercepted during execution of the function.
  • EOVERFLOW - One of the values to be returned cannot be represented correctly in the structure pointed to by buffer.
  • ENAMETOOLONG - The length of a component of the path parameter exceeds NAME_MAX, or the length of the path parameter exceeds PATH_MAX.
  • ENOENT - A component of path does not name an existing file, or path is an empty string.
  • ENOTDIR - A component of the path prefix of the path parameter is not a directory.

strcasecmp

Does a case-insensitive comparison of two 7-bit ASCII strings.

Format

#include <strings.h>

int strcasecmp (const char *s1, const char *s2);


Arguments

s1

The first of two strings to compare.

s2

The second of two strings to compare.

Description

The strcasecmp function is case-insensitive. The returned lexicographic difference reflects a conversion to lowercase.

The strcasecmp function works for 7-bit ASCII compares only. Do not use this function for internationalized applications.


Return Value

n An integer value greater than, equal to, or less than 0 (zero), depending on whether the s1 string is greater than, equal to, or less than the s2 string.


Previous Next Contents Index