HP OpenVMS Systems Documentation

HP C

HP C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

ctermid

Returns a character string giving the equivalence string of SYS$COMMAND. This is the name of the controlling terminal.

Format

#include <stdio.h>
char *ctermid (char *str);

Function Variants The ctermid function has variants named _ctermid32 and _ctermid64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.

Argument

str
Must be a pointer to an array of characters. If this argument is NULL, the file name is stored internally and might be overwritten by the next ctermid call. Otherwise, the file name is stored beginning at the location indicated by the argument. The argument must point to a storage area of length L_ctermid (defined by the <stdio.h> header file).

Return Value

pointer Points to a character string.

ctime, ctime_r

Converts a time in seconds, since 00:00:00 January 1, 1970, to an ASCII string in the form generated by the asctime function.

Format

#include <time.h>
char *ctime (const time_t *bintim);
char *ctime_r (const time_t *bintim, char *buffer); (ISO POSIX-1)

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

bintim
A pointer to a variable that specifies the time value (in seconds) to be converted.
buffer
A pointer to a character array that is at least 26 bytes long. This array is used to store the generated date-and-time string.

Description

The ctime and ctime_r functions convert the time pointed to by bintim into a 26-character string, and return a pointer to the string.
The difference between the ctime_r and ctime functions is that the former puts its result into a user-specified buffer. The latter puts its result into thread-specific static memory allocated by the HP C RTL, which can be overwritten by subsequent calls to ctime or asctime ; you must make a copy if you want to save it.
On success, ctime returns a pointer to the string; ctime_r returns its second argument. On failure, these functions return the NULL pointer.
The type time_t is defined in the <time.h> header file as follows:
typedef long int time_t
The ctime function behaves as if it called tzset .

Note
Generally speaking, UTC-based time functions can affect in-memory time-zone information, which is processwide data. However, if the system time zone remains the same during the execution of the application (which is the common case) and the cache of timezone files is enabled (which is the default), then the _r variant of the time functions asctime_r , ctime_r , gmtime_r , and localtime_r , is both thread-safe and AST-reentrant.

If, however, the system time zone can change during the execution of the application or the cache of timezone files is not enabled, then both variants of the UTC-based time functions belong to the third class of functions, which are neither thread-safe nor AST-reentrant.

Return Values

x A pointer to the 26-character ASCII string, if successful.

NULL Indicates failure.

cuserid

Returns a pointer to a character string containing the name of the user initiating the current process.

Format

#include <unistd.h> (X/OPEN, POSIX-1)
#include <stdio.h> (X/OPEN)
char *cuserid (char *str);

Function Variants The cuserid function has variants named _cuserid32 and _cuserid64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.

Argument

str
If this argument is NULL, the user name is stored internally. If the argument is not NULL, it points to a storage area of length L_cuserid (defined by the <stdio.h> header file), and the name is written into that storage. If the user name is a null string, the function returns NULL.

Return Values

pointer Points to a string.

NULL If the user name is a null string.

DECC$CRTL_INIT

Allows you to call the HP C RTL from other languages or to use the HP C RTL when your main function is not in C. It initializes the run-time environment and establishes both an exit and condition handler. VAXC$CRTL_INIT is a synonym for DECC$CRTL_INIT . Either name invokes the same routine.

Format

#include <signal.h>
void DECC$CRTL_INIT(void);

Description

The following example shows a Pascal program that calls the HP C RTL using the DECC$CRTL_INIT function:
$ PASCAL EXAMPLE1 $ LINK EXAMPLE1 $ TY EXAMPLE1.PAS PROGRAM TESTC(input, output); PROCEDURE DECC$CRTL_INIT; extern; BEGIN DECC$CRTL_INIT; END
A shareable image need only call this function if it contains an HP C function for signal handling, environment variables, I/O, exit handling, a default file protection mask, or if it is a child process that should inherit context.
Although many of the initialization activities are performed only once, DECC$CRTL_INIT can safely be called multiple times. On OpenVMS VAX systems, DECC$CRTL_INIT establishes the HP C RTL internal OpenVMS exception handler in the frame of the routine that calls DECC$CRTL_INIT each time DECC$CRTL_INIT is called.
At least one frame in the current call stack must have that handler established for OpenVMS exceptions to get mapped to UNIX signals.

decc$feature_get_index

Returns an index for accessing feature values.

Format

int decc$feature_get_index (char *name);

Argument

name
Pointer to a character string passed as a name in the list of supported features.

Description

The decc$feature_get_index function looks up the string passed as name in the list of supported features. If the name is found, decc$feature_get_index returns a (nonnegative) index that can be used to set or retrieve the values for the feature. The comparison for name is case insensitive.
On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_get_name , decc$feature_get_value , and decc$feature_set_value .

Return Values

n A nonnegative index that can be used to set or retrieve the specified values for the feature.

- 1 Indicates an error; errno is set.

Example

The following sample module sets default values for an application. The module can be compiled separately from the application and included in the image during link:

  static int set_feature_default(char *name, int value)
  {
      int index = decc$feature_get_index(name);

      if (index == -1 ||
          decc$feature_set_value(index, 0, value) == -1)
      {
          perror(name);
          return -1;
      }
      return 0;
  }

  static void my_init( void)
  {
     set_feature_default("DECC$POSIX_SEEK_STREAM_FILE" , TRUE);
     set_feature_default("DECC$ARGV_CASE_PARSE_STYLE"  , TRUE);
     set_feature_default("DECC$EFS_CASE_PRESERVE"      , TRUE);
     set_feature_default("DECC$FILE_SHARING"           , TRUE);
  }

  #pragma nostandard
    globaldef { "LIB$INITIALIZ" } readonly _align (LONGWORD)
               int spare[8] = {0};
    globaldef { "LIB$INITIALIZE" } readonly _align (LONGWORD)
                void (*x_my_init)() = my_init;
  #pragma standard

decc$feature_get_name

Returns a feature name.

Format

char *decc$feature_get_name (int index);

Argument

index
An integer value from 0 to the highest allocated feature.

Description

The decc$feature_get_name function returns a pointer to a null-terminated string containing the name of the feature for the entry specified by index. The index value can be 0 to the highest allocated feature. If there is no feature corresponding to the index value, then the function returns a NULL pointer.
On error, NULL is returned and errno is set to indicate the error.
See also decc$feature_get_index , decc$feature_get_value , and decc$feature_set_value .

Return Values

x Pointer to a null-terminated string containing the name of the feature for the entry specified by index.

NULL Indicates an error; errno is set.

Example

See decc$feature_get_index for an example of retrieving and setting C RTL features.

decc$feature_get_value

Returns a feature value depending on the mode argument.

Format

int decc$feature_get_value (int index, int mode);

Arguments

index
An integer value from 0 to the highest allocated feature.
mode
An integer indicating which feature value to return. The values for mode are:
0 Default value
1 Current value
2 Minimum value
3 Maximum value
4 Initialization state

Description

The decc$feature_get_value function retrieves a value for the feature specified by index. The mode determines which value is returned.
The default value is what is used if not set by a logical name or overidden by a call to decc$feature_set_value .
If mode = 4, then the initialization state is returned. Values for the initialization state are:
0 not initialized
1 set by logical name
2 forced by decc$feature_set_value
- 1---initialized to default value

On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_get_index , decc$feature_get_name , and decc$feature_set_value .

Return Values

n An integer corresponding to the specified index and mode arguments.

- 1 Indicates an error; errno is set.

Example

See decc$feature_get_index for an example of retrieving and setting C RTL features.

decc$feature_set_value

Sets the default value or the current value for the feature specified by index.

Format

int decc$feature_set_value (int index, int mode, int value);

Arguments

index
An integer value from 0 to the highest allocated feature.
mode
An integer indicating whether to set the default or current feature value. The values for mode are:
0 default value
1 current value

value
The feature value to be set.

Description

The decc$feature_set_value function sets the default value or the current value (as determined by the mode argument) for the feature specified by index.
If this function is successful, it returns the previous value.
On error, - 1 is returned and errno is set to indicate the error.
See also decc$feature_get_index , decc$feature_get_name , and decc$feature_get_value .

Return Values

n The previous feature value.

- 1 Indicates an error; errno is set.

Example

See decc$feature_get_index for an example of retrieving and setting C RTL features.

decc$fix_time

Converts OpenVMS binary system times to UNIX binary times.

Format

#include <unixlib.h>
unsigned int decc$fix_time (void *vms_time);

Argument

vms_time
The address of a quadword containing an OpenVMS binary time:
unsigned int quadword[2]; unsigned int *vms_time = quadword;

Description

The decc$fix_time routine converts an OpenVMS binary system time (a 64-bit quadword containing the number of 100-nanosecond ticks since 00:00 November 17, 1858) to a UNIX binary time (a longword containing the number of seconds since 00:00 January 1, 1970). This routine is useful for converting binary times returned by OpenVMS system services and RMS services to the format used by some HP C RTL routines, such as ctime and localtime .

Return Values

x A longword containing the number of seconds since 00:00 January 1, 1970.

( unsigned int )( - 1) Indicates an error. Be aware, that a return value of ( unsigned int )( - 1) can also represent a valid date of Sun Feb 7 06:28:15 2106.

Example

#include <unixlib.h>
#include <stdio.h>
#include <starlet.h>  /* OpenVMS specific SYS$ routines)  */

main()
{
unsigned int current_vms_time[2]; /*quadword for OpenVMS time*/
unsigned int number_of_seconds;   /* number of seconds     */

/* first get the current system time */
sys$gettim(&current_vms_time[0]);

/* fix the time */
number_of_seconds = decc$fix_time(&current_vms_time[0]);

printf("Number of seconds since 00:00 January 1, 1970 = %d",
        number_of_seconds);
}

This example shows how to use the decc$fix_time routine in HP C. It also shows the use of the SYS$GETTIM system service.

decc$from_vms

Converts OpenVMS file specifications to UNIX style file specifications.

Format

#include <unixlib.h>
int decc$from_vms (const char *vms_filespec, int action_routine, int wild_flag);

Arguments

vms_filespec
The address of a null-terminated string containing a name in OpenVMS file specification format.
action_routine
The address of a routine that takes as its only argument a null-terminated string containing the translation of the given OpenVMS file name to a valid UNIX style file name.
If the action_routine returns a nonzero value (TRUE), file translation continues. If it returns a zero value (FALSE), no further file translation takes place.
wild_flag
Either 0 or 1, passed by value. If a 0 is specified, wildcards found in vms_filespec are not expanded. Otherwise, wildcards are expanded and each one is passed to action_routine. Only expanded file names that correspond to existing UNIX style files are included.

Description

The decc$from_vms routine converts the given OpenVMS file specification into the equivalent UNIX style file specification. It allows you to specify OpenVMS wildcards, which are translated into a list of corresponding existing files in UNIX style file specification format.

Return Value

x The number of file names that result from the specified OpenVMS file specification.

Example

/* This example must be run as a foreign command */ /* and be supplied with an OpenVMS file specification. */ #include <unixlib.h> #include <stdio.h> int main(int argc, char *argv[]) { int number_found; /* number of files found */ int print_name(); /* name printer */ printf("Translating: %s\n", argv[1]); number_found = decc$from_vms(argv[1], print_name, 1); printf("\n%d files found", number_found); } /* print the name on each line */ print_name(char *name) { printf("\n%s", name); /* will continue as long as success status is returned */ return (1); }
This example shows how to use the decc$from_vms routine in HP C. It produces a simple form of the ls command that lists existing files that match an OpenVMS file specification supplied on the command line. The matching files are displayed in UNIX style file specification format.

decc$match_wild

Matches a string to a pattern.

Format

#include <unixlib.h>
int decc$match_wild (char *test_string, char *string_pattern);

Arguments

test_string
The address of a null-terminated string.
string_pattern
The address of a string containing the pattern to be matched. This pattern can contain wildcards (such as asterisks (*), question marks (?), and percent signs (%) as well as regular expressions (such as the range [a-z]).

Description

The decc$match_wild routine determines whether the specified test string is a member of the set of strings specified by the pattern.

Return Values

1 (TRUE) The string matches the pattern.

0 (FALSE) The string does not match the pattern.

Example

/* Define as a foreign command and then provide */
/* two arguments: test_string, string_pattern.  */

#include <unixlib.h>
#include <stdio.h>
int main(int argc, char *argv[])
{
    if (decc$match_wild(argv[1], argv[2]))
        printf("\n%s matches %s", argv[1], argv[2]);
    else
        printf("\n%s does not match %s", argv[1], argv[2]);
}

decc$record_read

Reads a record from a file.

Format

#include <stdio.h>
int decc$record_read (FILE *fp, void *buffer, int nbytes);

Arguments

fp
A file pointer. The specified file pointer must refer to a file currently opened for reading.
buffer
The address of contiguous storage in which the input data is placed.
nbytes
The maximum number of bytes involved in the read operation.

Description

The decc$record_read function is specific to OpenVMS systems and should not be used when writing portable applications.
This function is equivalent to the read function, except that the first argument is a file pointer, not a file descriptor.

Return Values

x The number of characters read.

- 1 Indicates a read error, including physical input errors, illegal buffer addresses, protection violations, undefined file descriptors, and so forth.

Contents

Index

HP OpenVMS Systems Documentation

HP CRun-Time Library Reference Manual for OpenVMS Systems

ctermid

Format

Argument

str

Return Value

ctime, ctime_r

Format

Arguments

bintim

buffer

Description

Return Values

cuserid

Format

Argument

str

Return Values

DECC$CRTL_INIT

Format

Description

decc$feature_get_index

Format

Argument

name

Description

Return Values

Example

decc$feature_get_name

Format

Argument

index

Description

Return Values

Example

decc$feature_get_value

Format

Arguments

index

mode

Description

Return Values

Example

decc$feature_set_value

Format

Arguments

index

mode

value

Description

Return Values

Example

decc$fix_time

Format

Argument

vms_time

Description

Return Values

Example

decc$from_vms

Format

Arguments

vms_filespec

action_routine

wild_flag

Description

Return Value

Example

decc$match_wild

Format

Arguments

test_string

string_pattern

Description

Return Values

Example

decc$record_read

Format

Arguments

HP C
Run-Time Library Reference Manual for OpenVMS Systems