United States

Compaq C

# Compaq 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, ...); (DEC 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 this function that is equivalent to the behavior before OpenVMS Version 7.0.

## 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_t` that is defined in the `<stat.h>` header file.

> The argument receives information about the particular file. The members of the structure pointed to by buffer are described as follows:

> 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
> `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.

> 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

> ### ...

> 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

> This 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.

> The physical device name string referred to by the `st_dev` member of the `stat` structure is overwritten by the next `stat` call.

> Note (ALPHA ONLY) On OpenVMS Alpha 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.

# 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

> This 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 Values

> 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.

# strcat

> Concatenates str_2, including the terminating null character, to the end of str_1.

## Format

> #include <string.h>

> char *strcat (char *str_1, const char *str_2);

Function Variants This function also has variants named `_strcat32` and `_strcat64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### str_1, str_2

> Pointers to null-terminated character strings.

## Description

> See also `strncat` in this section.

## Return Value

> x | The address of the first argument, str_1, which is assumed to be large enough to hold the concatenated result.

## Example

>     #include <string.h>
>     #include <stdio.h>

>     /* This program concatenates two strings using the strcat       */
>     /* function, and then manually compares the result of strcat    */
>     /* to the expected result.                                      */

>     #define S1LENGTH 10
>     #define S2LENGTH 8

>     main()
>     {
>         static char s1buf[S1LENGTH + S2LENGTH] = "abcmnexyz";
>         static char s2buf[] = " orthis";
>         static char test1[] = "abcmnexyz orthis";

>         int i;
>         char *status;

>         /* Take static buffer s1buf, concatenate static buffer      */
>         /* s2buf to it, and compare the answer in s1buf with the    */
>         /* static answer in test1.                                  */

>         status = strcat(s1buf, s2buf);
>         for (i = 0; i <= S1LENGTH + S2LENGTH - 2; i++) {
>             /* Check for correct returned string.   */

>             if (test1[i] != s1buf[i])
>                 printf("error in strcat");
>         }
>     }

# strchr

> Returns the address of the first occurrence of a given character in a null-terminated string. The terminating null character is considered to be part of the string.

## Format

> #include <string.h>

> char *strchr (const char *str, int character);

Function Variants This function also has variants named `_strchr32` and `_strchr64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### str

> A pointer to a null-terminated character string.

> ### character

> An object of type `int` .

## Description

> See also `strrchr` in this section.

## Return Values

> x | The address of the first occurrence of the specified character.
> NULL | Indicates that the character does not occur in the string.

## Example

>     #include <stdio.h>
>     #include <string.h>

>     main()
>     {

>         static char s1buf[] = "abcdefghijkl lkjihgfedcba";

>         int i;

>         char *status;

>         /*  This program checks the strchr function by incrementally   */
>         /*  going through a string that ascends to the middle and then */
>         /*  descends towards the end.                                  */

>         for (i = 0; s1buf[i] != '\0' && s1buf[i] != ' '; i++) {
>             status = strchr(s1buf, s1buf[i]);

>             /* Check for pointer to leftmost character - test 1. */

>             if (status != &s1buf[i])
>                 printf("error in strchr");
>         }
>     }

# strcmp

> Compares two ASCII character strings and returns a negative, 0, or positive integer, indicating that the ASCII values of the individual characters in the first string are less than, equal to, or greater than the values in the second string.

## Format

> #include <string.h>

> int strcmp (const char *str_1, const char *str_2);

## Arguments

> ### str_1, str_2

> Pointers to character strings.

## Description

> The strings are compared until a null character is encountered or until the strings differ.

## Return Values

> < 0 | Indicates that str_1 is less than str_2.
> = 0 | Indicates that str_1 equals str_2.
> > 0 | Indicates that str_1 is greater than str_2.

# strcoll

> Compares two strings and returns an integer that indicates if the strings differ and how they differ. The function uses the collating information in the LC_COLLATE category of the current locale to determine how the comparison is performed.

## Format

> #include <string.h>

> int strcoll (const char *s1, const char *s2);

## Arguments

> ### s1, s2

> Pointers to character strings.

## Description

> This function, unlike `strcmp` , compares two strings in a locale-dependent manner. Because no value is reserved for error indication, the application must check for one by setting `errno` to 0 before the function call and testing it after the call.

> See also the `strxfrm` function is this section.

## Return Values

> < 0 | Indicates that s1 is less than s2.
> = 0 | Indicates that the strings are equal.
> > 0 | Indicates that s1 is greater than s2.

# strcpy

> Copies all of source, including the terminating null character, into dest.

## Format

> #include <string.h>

> char *strcpy (char *dest, const char *source);

Function Variants This function also has variants named `_strcpy32` and `_strcpy64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### dest

> Pointer to the destination character string.

> ### source

> Pointer to the source character string.

## Description

> This function copies source into dest, and stops after copying source's null character.

> The behavior of this function is undefined if the area pointed to by dest overlaps the area pointed to by source.

## Return Value

> x | The address of dest.

# strcspn

> Returns the length of the prefix of a string that consists entirely of characters not in a specified set of characters.

## Format

> #include <string.h>

> size_t strcspn (const char *str, const char *charset);

## Arguments

> ### str

> A pointer to a character string. If this character string is a null string, 0 is returned.

> ### charset

> A pointer to a character string containing the set of characters.

## Description

> This function scans the characters in the string, stops when it encounters a character found in charset, and returns the length of the string's initial segment formed by characters not found in charset.

> If none of the characters match in the character strings pointed to by str and charset, `strcspn` returns the length of string.

## Return Value

> x | The length of the segment.

# strdup

> Finds and points to a duplicate string.

## Format

> #include <string.h>

> char *strdup (const char *s1);

Function Variants This function also has variants named `_strdup32` and `_strdup64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### s1

> The first of two strings to compare.

## Description

> This function returns a pointer to a string that is an exact duplicate of the string pointed to by s1. The `malloc` function is used to allocate space for the new string. The strdup function is provided for compatibility with existing systems.

## Return Values

> x | A pointer to the resulting string.
> NULL | Indicates an error.

# strerror

> Maps the error number in error_code to a locale-dependent error message string.

## Format

> #include <string.h>

> char *strerror (int error_code); (ANSI C)

> char *strerror (int error_code[, int vms_error_code]); (DEC C EXTENSION)

## Arguments

> ### error_code

> An error code.

> ### vms_error_code

> An OpenVMS error code.

## Description

> This function uses the error number in error_code to retrieve the appropriate locale-dependent error message. The contents of the error message strings are determined by the LC_MESSAGES category of the program's current locale.

> When a program is not compiled with any standards-related feature-test macros (see Section 1.5.1), `strerror` has a second argument (vms_error_code), which is used in the following way:

> - If error_code is EVMSERR and there is a second argument, then that second argument is used as the `vaxc$errno` value.
> - If error_code is EVMSERR and there is no second argument, look at `vaxc$errno` to get the OpenVMS error condition.

> See the `strerror` example.

> Use of the second argument is not included in the ANSI C definition of `strerror` and is, therefore, not portable.

> Because no return value is reserved to indicate an error, applications should set the value of `errno` to 0, call `strerror` , and then test the value of `errno` ; a nonzero value indicates an error condition.

## Return Values

> x | A pointer to a buffer containing the appropriate error message. Do not modify this buffer in your programs. Moreover, calls to the `strerror` function may overwrite this buffer with a new message.

## Example

>     #include <stdio.h>
>     #include <errno.h>
>     #include <string.h>
>     #include <stdlib.h>
>     #include <ssdef.h>

>     main()
>     {
>         puts(strerror(EVMSERR));
>         errno = EVMSERR;
>         vaxc$errno = SS$_LINKEXIT;
>         puts(strerror(errno));
>         puts(strerror(EVMSERR, SS$_ABORT));
>         exit(1);
>     }

Running this example produces the following output:

    non-translatable vms error code: <none>
    network partner exited
    abort

Previous | Next | Contents | Index

privacy and legal statement