In addition to these options, any option that takes a key value (such as "fop" or "rat") can be negated by prefixing the value with "no". For example, specify "fop=notmp" to clear the "tmp" bit in the "fop" field.

For more information on these options, see the OpenVMS Record Management Services Reference Manual manual.

Description

The Compaq C RTL opens the new file for reading and writing, and returns the corresponding file descriptor.

If the file exists:

• A version number one greater than any existing version is assigned to the newly created file.
• By default, the new file inherits certain attributes from the existing version of the file unless those attributes are specified in the creat call. The following attributes are inherited:
  • Record format (fab$b_rfm)
  • Maximum record size (fab$w_mrs)
  • Carriage control (fab$b_rat)
  • File protection

If the file did not previously exist:

• It is given the file protection that results from performing a bitwise AND on the mode argument and the complement of the current protection mask.
• It defaults to stream format with line-feed record separator and implied carriage-return attributes.

See also open , close , read , write , and lseek in this section.

Return Values

n	A file descriptor.
--1	Indicates errors, including protection violations, undefined directories, and conflicting file attributes.

In the UNIX system environment, the crmode and nocrmode functions set and unset the terminal from cbreak mode. In cbreak mode, a single input character can be processed without pressing Return. This mode of single-character input is only supported with the Curses input routine getch .

Format

#include <curses.h>

crmode()

nocrmode()

Example

/* Program to demonstrate the use of crmod() and curses */ #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.

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

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.

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)

Argument

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 Compaq 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 process-wide 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 Value

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

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

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.

Allows you to call the Compaq C RTL from other languages or to use the Compaq 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 Compaq 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 Compaq 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 Compaq 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.

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

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

Also see feature_get_name , feature_get_value , and feature_set_value .

Return Values

n	A nonnegative index that can be used to set or retrieve the values for the feature.
--1	Indicates an error; errno is set.

Example

#include <stdio.h> #include <stdlib.h> #include <errno.h> #include <ctype.h> #include <string.h> int decc$feature_get_index (char *name); char *decc$feature_get_name (int index); int decc$feature_get_value (int index, int mode); int decc$feature_set_value (int index, int mode, int value); int set_only; static char *sval(int i) { static char buf[128]; if (i) sprintf(buf, "%d", i); else strcpy(buf, "."); return buf; } /* ** Convert a string to lowercase ** */ char *strtolower( char *str ) { char *ret = str; char c; if (!str) return str; for (ret = str; c = *str; str++) *str = tolower( c ); return ret; } /* ** Print all available features and their values ** */ void print_feature_settings( void ) { char *name; int i; int skipped = 0; /* ** C RTL Feature settings ------------ Logical name --------------- Cur Def Min Max Ini DECC$EXEC_FILEATTR_INHERITANCE 1 . . 1 1 DECC$FILENAME_UNIX_ONLY 1 . . 1 2 DECC$FILE_SHARING 1 . . 1 2 DECC$POSIX_SEEK_STREAM_FILE 1 . . 1 2 DECC$STDIO_CTX_EOL 1 . . 1 1 DECC$TRACE 1 . . 1 1 DECC$ARGV_PARSE_STYLE 1 . . 1 1 DECC$EFS_CASE_PRESERVE 1 . . 1 2 DECC$EFS_CASE_SPECIAL 1 . . 1 1 */ puts("** C RTL Feature settings"); puts(" ------------ Logical name --------------- Cur Def Min Max Ini"); for (i = 0; name = decc$feature_get_name(i); i++) { int init = decc$feature_get_value(i, 4); if ((set_only < 0 || set_only > 1) || (set_only == 1 && init > 0) || (set_only == 0 && init < 1) ) { int default_val = decc$feature_get_value(i, 0); int current_val = decc$feature_get_value(i, 1); int min_val = decc$feature_get_value(i, 2); int max_val = decc$feature_get_value(i, 3); char f_name[256]; strcpy( f_name, name ); if (strlen(f_name) > 4) strtolower(f_name+4); printf(" %-40s", f_name); printf(" %6s", sval(current_val)); printf(" %6s", sval(default_val)); printf(" %6s", sval(min_val)); printf(" %6s", sval(max_val)); printf(" %3s", sval(init)); puts(""); } } puts(""); puts ("** C RTL features that cannot be set by API"); for (i++; name = decc$feature_get_name(i); i++) { int init = decc$feature_get_value(i, 4); if ((set_only < 0 || set_only > 1) || (set_only == 1 && init > 0) || (set_only == 0 && init < 1) ) { int default_val = decc$feature_get_value(i, 0); int current_val = decc$feature_get_value(i, 1); int min_val = decc$feature_get_value(i, 2); int max_val = decc$feature_get_value(i, 3); char f_name[256]; strcpy( f_name, name ); if (strlen(f_name) > 4) strtolower(f_name+4); printf(" %-40s", f_name); printf(" %6s", sval(current_val)); printf(" %6s", sval(default_val)); printf(" %6s", sval(min_val)); printf(" %6s", sval(max_val)); printf(" %3s", sval(init)); puts(""); } } } #ifdef LIB_INIT /* ** Sets current value for a feature */ static int set_feature_default(char *name, int value) { int index; int sts; errno = 0; index = decc$feature_get_index(name); if (index == -1 || ((sts = decc$feature_set_value(index, 1, value)) == -1)) { perror(name); return -1; } return 0; } static void set_coe ( void ) { set_feature_default("DECC$FILENAME_UNIX_ONLY" , TRUE); set_feature_default("DECC$FILE_SHARING" , TRUE); set_feature_default("DECC$POSIX_SEEK_STREAM_FILE" , TRUE); set_feature_default("DECC$EFS_CASE_PRESERVE" , TRUE); set_feature_default("DECC$ARGV_CASE_PARSE_STYLE" , TRUE); } int lib$initialize(); #pragma nostandard globaldef { "LIB$INITIALIZ" } readonly _align (LONGWORD) int spare[8] = {0}; globaldef { "LIB$INITIALIZE" } readonly _align (LONGWORD) void (*x_set_coe)() = set_coe; /* ** Force a reference to LIB$INITIALIZE to ensure it ** exists in the image. */ globaldef int (*lib_init_ref)() = lib$initialize; #pragma standard #endif int main(int argc, char **argv) { if (argc > 1) set_only = atol(argv[1]); else set_only = -1; print_feature_settings(); }

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

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

Also see feature_get_index , feature_get_value , and 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.

Returns a feature value depending on the mode argument.

Format

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

Argument

index

An integer value from 0 to the highest allocated feature.

mode

An integer indicating which feature value to return. Values for mode:

0 - default value
1 - current value
2 - minimum value
3 - maximum value

Description

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

On error, -1 is returned and errno is set to indicate the error.

Also see feature_get_index , feature_get_name , and 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.

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

Argument

index

An integer value from 0 to the highest allocated feature.

mode

An integer indicating whether to set the default or current feature value. Values for mode:

0 - default value
1 - current value

value

The feature value to be set.

Description

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

Also see feature_get_index , feature_get_name , and 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.