DEC C
Run-Time Library Reference Manual for OpenVMS Systems

/* Exercise cbreak. */ #include <curses.h> main () { WINDOW *win1; char vert = '.', hor = '.', str[80]; /* Initialize standard screen, turn echo off. */ initscr (); noecho (); /* Define a user window. */ win1 = newwin (22, 78, 1, 1); /* Turn on reverse video and draw a box on border. */ setattr (_REVERSE); box (stdscr, vert, hor); mvwaddstr (win1, 2, 2, "Test cbreak input"); refresh (); wrefresh (win1); /* Set cbreak, do some input, and output it. */ crmode(); getch (); nocrmode(); /* Turn off cbreak. */ mvwaddstr (win1, 5, 5, str); mvwaddstr (win1, 7, 7, "Type something to clear the screen"); wrefresh (win1); /* Get another character, then delete the window. */ getch (); wclear (win1); touchwin (stdscr); endwin (); }

In this example, the first call to getch returns as soon as one character is entered, because crmode was called before getch was called. The second time getch is called, it waits until the Return key is pressed before processing the character entered, because nocrmode was called before getch was called the second time.

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 This function also has variants named _ctermid32 and _ctermid64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 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

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);

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.

ARGUMENT

bintim
A pointer to the time value to be converted.

DESCRIPTION

Successive calls to the ctime or asctime function overwrite any previous time values. 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 .

Return Value

pointer Points to the 26-character ASCII string.

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 This function also has variants named _cuserid32 and _cuserid64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 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 DEC C RTL from other languages or to use the DEC 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();

DESCRIPTION

The following example shows a Pascal program that calls the DEC 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 a DEC 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 DEC 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$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

This routine converts an OpenVMS binary system time (a 64-bit quadword containing the number of 10-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 DEC C RTL routines, such as ctime and localtime .

Return Values

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

Example

#include <unixlib.h> #include <stdio.h> main() { /* LOCALS */ unsigned int current_vms_time[2]; */ quadword for OpenVMS time */ unsigned int number_of_seconds; */ number of seconds */ /* PROCEDURE */ /* 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 DEC 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

This 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

#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 DEC 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

This 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

#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

This function is specific to OpenVMS systems and should not be used when writing portable applications.
The decc$record_read function is functionally 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.

decc$record_write

Writes a record to a file.

Format

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

ARGUMENTS

fp
A file pointer. The specified file pointer must refer to a file currently opened for writing or updating.
buffer
The address of contiguous storage from which the output data is taken.
nbytes
The maximum number of bytes involved in the write operation.

DESCRIPTION

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

Return Values

x The number of bytes written.

--1 Indicates errors, including undefined file descriptors, illegal buffer addresses, and physical I/O errors.

decc$set_reentrancy

Controls the type of reentrancy that reentrant DEC C RTL routines will exhibit.

Format

#include <reentrancy.h>
int decc$set_reentrancy (int type);

ARGUMENT

type
The type of reentrancy desired. Use one of the following values:

C$C_MULTITHREAD --- Designed to be used in conjunction with the DECthreads product. It performs DECthreads locking and never disables ASTs. DECthreads must be available on your system to use this form of reentrancy.
C$C_AST --- Uses the _BBSSI (VAX ONLY) or __TESTBITSSI (ALPHA ONLY) built-in function to perform simple locking around critical sections of RTL code, and it may additionally disable asynchronous system traps (ASTs) in locked regions of code. This type of locking should be used when AST code contains calls to DEC C RTL I/O routines, or when the user application disables ASTs.
C$C_TOLERANT --- Uses the _BBSSI (VAX ONLY) or __TESTBITSSI (ALPHA ONLY) built-in function to perform simple locking around critical sections of RTL code, but ASTs are not disabled. This type of locking should be used when ASTs are used and must be delivered immediately. TOLERANT is the default reentrancy type.
C$C_NONE --- Gives optimal performance in the DEC C RTL, but does absolutely no locking around critical sections of RTL code. It should only be used in a single-threaded environment when there is no chance that the thread of execution will be interrupted by an AST that would call the DEC C RTL.

The reentrancy type can be raised but never lowered. The ordering of reentrancy types from low to high is C$C_NONE, C$C_TOLERANT, C$C_AST and C$C_MULTITHREAD. For example, once an application is set to multithread, a call to set the reentrancy to AST is ignored. A call to decc$set_reentrancy that attempts to lower the reentrancy type returns a value of --1.

DESCRIPTION

Use this function to change the type of reentrancy exhibited by reentrant routines.
decc$set_reentrancy must be called exclusively at the non-AST level.
In an application using DECthreads, DECthreads automatically sets the reentrancy to multithread.

Return Value

type The type of reentrancy used before this call.

--1 The reentrancy was set to a lower type.

decc$to_vms

Converts UNIX style file specifications to OpenVMS file specifications.

Format

#include <unixlib.h>
int decc$to_vms (const char *unix_style_filespec, int (*action_routine)(char *unix_style_filespec, int type_of_file), int allow_wild, int no_directory);

ARGUMENTS

unix_style_filespec
The address of a null-terminated string containing a name in UNIX style file specification format.
action_routine
The address of a routine that accepts the following arguments:

A pointer to a null-terminated string that contains the UNIX style file name to be translated to a valid OpenVMS file name
An integer that has one of the following values:

Value Translation

0 (DECC$K_FOREIGN) A file on a remote system that is not running the OpenVMS or VAXELN operating system.

2 (DECC$K_DIRECTORY) The OpenVMS translation of the UNIX style file name is a directory.

1 (DECC$K_FILE) The translation is a file.

These values can be defined symbolically with the symbols DECC$K_FOREIGN, DECC$K_DIRECTORY, and DECC$K_FILE. See the example for more information.

If action_routine returns a nonzero value (TRUE), file translation continues. If it returns a 0 value (FALSE), no further file translation takes place.
allow_wild
Either 0 or 1, passed by value. If a 0 is specified, wildcards found in unix_style_filespec are not expanded. Otherwise, wildcards are expanded and each one is passed to action_routine. Only expanded file names that correspond to existing OpenVMS files are included.
no_directory
An integer that has one of the following values:

Value Translation

0 Directory is not allowed.

1 Prevent expansion of the string as a directory name.

2 Forced to be a directory name.

Value	Translation
0 (DECC$K_FOREIGN)	A file on a remote system that is not running the OpenVMS or VAXELN operating system.
2 (DECC$K_DIRECTORY)	The OpenVMS translation of the UNIX style file name is a directory.
1 (DECC$K_FILE)	The translation is a file.

Value	Translation
0	Directory is not allowed.
1	Prevent expansion of the string as a directory name.
2	Forced to be a directory name.

DESCRIPTION

This routine converts the given UNIX style file specification into the equivalent OpenVMS file specification (in all uppercase letters). It allows you to specify UNIX style wildcards, which are translated into a list of corresponding OpenVMS files.

Return Value

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

Example

#include <unixlib.h> #include <stdio.h> int print_name( char *, int ); int main(int argc, char *argv[]) { int number_found; /* number of files found */ printf( "Translating: %s\n", argv[1]); number_found = decc$to_vms( argv[1], print_name, 1, 0); printf( "%d files found\n", number_found ); } /* action routine that prints name and type on each line */ int print_name( char *name, int type ) { if( type == DECC$K_DIRECTORY ) printf( "directory: %s\n", name); else if( type == DECC$K_FOREIGN) printf( "remote non-VMS: %s\n", name); else printf( "file: %s\n", name); /* Translation continues as long as success status is returned */ return(1); }

This example shows how to use the decc$to_vms routine in DEC C. It takes a UNIX style file specification argument and displays, in OpenVMS file specification format, the name of each existing file that matches it.

decc$translate_vms

Translates OpenVMS file specifications to UNIX style file specifications.

Format

#include <unixlib.h>
char *decc$translate_vms (const char *vms_filespec);

ARGUMENT

vms_filespec
The address of a null-terminated string containing a name in OpenVMS file specification format.

DESCRIPTION

This routine translates the given OpenVMS file specification into the equivalent UNIX style file specification, whether or not the file exists. This routine differs from the decc$from_vms routine, which does the conversion for existing files only.

Return Values

x The address of a null-terminated string containing a name in UNIX style file specification format.

0 Indicates that the file name is null or syntactically incorrect.

--1 Indicates that the file specification contains an ellipsis (for example, [...]a.dat), but is otherwise correct. You cannot translate the OpenVMS ellipsis syntax into a valid UNIX style file specification.

Example

#include <unixlib.h> #include <stdio.h> int main(int argc, char *argv[]) { char *ptr; /* translation result */ ptr = decc$translate_vms( argv[1] ); if (ptr == 0 || ptr == -1) printf( "could not translate %s\n", argv[1]); else printf( "%s is translated to %s\n", argv[1], ptr ); }

[w]delch

Delete the character on the specified window at the current position of the cursor. The delch function operates on the stdscr window.

Format

#include <curses.h>
int delch();
int wdelch (WINDOW *win);

ARGUMENT

win
A pointer to the window.

DESCRIPTION

All of the characters to the right of the cursor on the same line are shifted to the left, and a blank character is appended to the end of the line.

Return Values

OK Indicates success.

ERR Indicates an error.

delete

Deletes a file.

Format

#include <unixio.h>
int delete (const char *file_spec);

ARGUMENT

file_spec
A pointer to the string that is an OpenVMS or UNIX style file specification. The file specification can include a wildcard in its version number (but not in any other part of the file spec). So, for example, files of the form filename.txt;* can be deleted.

DESCRIPTION

If you specify a directory in the file name and it is a search list that contains an error, DEC C for OpenVMS Systems interprets it as a file error.
The remove and delete functions are functionally equivalent in the DEC C RTL.
See also remove in this section.

Note
The delete routine is not available to C++ programmers because it conflicts with the C++ reserved word delete . C++ programmers should use the ANSI/ISO C standard function remove instead.

Return Values

0 Indicates success.

nonzero value Indicates that the operation has failed.

[w]deleteln

Delete the line at the current position of the cursor. The deleteln function acts on the stdscr window.

Format

#include <curses.h>
int deleteln();
int wdeleteln (WINDOW *win);

ARGUMENT

win
A pointer to the window.

DESCRIPTION

Every line below the deleted line moves up, and the bottom line becomes blank. The current (y,x) coordinates of the cursor remain unchanged.

Return Values

OK Indicates success.

ERR Indicates an error.

delwin

Deletes the specified window from memory.

Format

#include <curses.h>
int delwin (WINDOW *win);

ARGUMENT

win
A pointer to the window.

DESCRIPTION

If the window being deleted contains a subwindow, the subwindow is invalidated. Delete subwindows before deleting their parent. The delwin function refreshes all windows covered by the deleted window.

Return Values

OK Indicates success.

ERR Indicates an error.

difftime

Computes the difference, in seconds, between the two times specified by the time1 and time2 arguments.

Format

#include <time.h>
double difftime (time_t time2, time_t time1);

ARGUMENTS

time2
A time value of type time_t .
time1
A time value of type time_t .

DESCRIPTION

The type time_t is defined in the <time.h> header file as follows:

Previous Next Contents Index

pointer	Points to a string.
NULL	If the user name is a null string.

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

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.

x	The number of bytes written.
--1	Indicates errors, including undefined file descriptors, illegal buffer addresses, and physical I/O errors.

type	The type of reentrancy used before this call.
--1	The reentrancy was set to a lower type.

x	The address of a null-terminated string containing a name in UNIX style file specification format.
0	Indicates that the file name is null or syntactically incorrect.
--1	Indicates that the file specification contains an ellipsis (for example, [...]a.dat), but is otherwise correct. You cannot translate the OpenVMS ellipsis syntax into a valid UNIX style file specification.

0	Indicates success.
nonzero value	Indicates that the operation has failed.

DEC CRun-Time Library Reference Manual for OpenVMS Systems

ctermid

Format

ARGUMENT

str

Return Value

ctime

Format

ARGUMENT

bintim

DESCRIPTION

Return Value

cuserid

Format

ARGUMENT

str

Return Values

DECC$CRTL_INIT

Format

DESCRIPTION

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

fp

buffer

nbytes

DESCRIPTION

Return Values

decc$record_write

Format

ARGUMENTS

fp

buffer

nbytes

DESCRIPTION

Return Values

decc$set_reentrancy

Format

ARGUMENT

type

DESCRIPTION

Return Value

decc$to_vms

Format

ARGUMENTS

unix_style_filespec

action_routine

allow_wild

no_directory

DESCRIPTION

Return Value

Example

decc$translate_vms

Format

ARGUMENT

vms_filespec

DEC C
Run-Time Library Reference Manual for OpenVMS Systems