United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

# decc$set_reentrancy

> Controls the type of reentrancy that reentrant Compaq 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 Compaq 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 Compaq 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 Compaq 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.

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

>     /* Translate "Unix" wildcard file names to VMS names    */
>     /* Define as a foreign command and provide the name     */
>     /* as an argument.                                      */

>     #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 Compaq 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 function translates the given OpenVMS file specification into the equivalent UNIX style file specification, whether or not the file exists. The translated name string is stored in a thread-specific memory, which is overwritten by each call to `decc$translate_vms` from the same thread.

> This function differs from the `decc$from_vms` function, 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

>     /* Demonstrate translation of a "UNIX" name to VMS form */
>     /* define a foreign command and pass the name as the    */
>     /* argument.                                            */

>     #include <unixlib.h>
>     #include <stdio.h>

>     int main(int argc, char *argv[])
>     {
>         char *ptr;                      /* translation result */

>         ptr = decc$translate_vms( argv[1] );

>         if ((int) ptr == 0 || (int) ptr == -1)

>             printf( "could not translate %s\n", argv[1]);
>         else
>             printf( "%s is translated to %s\n", argv[1], ptr );
>     }

# decc$validate_wchar

> Confirms that its argument is a valid wide character in the current program's locale.

## Format

> #include <unistd.h>

> int decc$validate_wchar (wchar_t wc);

## Argument

> ### wc

> Wide character to be validated.

## Description

> This function provides a convenient way to verify whether a specified argument of `wchar_t` type is a valid wide character in the current program's locale.

> One reason to call `decc$validate_wchar` is that the `isw` * wide-character classification functions and macros do not validate their argument before dereferencing the `classmask` array describing character properties. Passing an `isw` * function a value that exceeds the maximum wide-character value for the current program's locale can result in an attempt to access memory beyond the allocated `classmask` array.

> A standard way to validate a wide character is to call the `wctomb` function, but this way is less convenient because it requires declaring a multibyte character array of sufficient size and passing it to `wctomb` .

## Return Values

> 1 | Indicates that the specified wide character is a valid wide character in the current program's locale.
> 0 | Indicates that the specified wide character is not a valid wide character in the current program's locale. `errno` is not set.

# decc$write_eof_to_mbx

> Writes an end-of-file message to the mailbox.

## Format

> #include <unistd.h>

> int decc$write_eof_to_mbx (int fd);

## Argument

> ### fd

> File descriptor associated with the mailbox.

## Description

> This function writes end-of-file message to the mailbox.

> For a mailbox that is not a pipe, the `write` function called with an nbytes parameter value of 0 sends an end-of-file message to the mailbox. For a pipe, however, the only way to write an end-of-file message to the mailbox is to close the pipe.

> If the child's standard input is redirected to a pipe through a call to the `decc$set_child_standard_streams` function, the parent process can call `decc$write_eof_to_mbx` for this pipe to send an EOF message to the child. It has the same effect as if the child read the data from a terminal, and Ctrl/Z was pressed.

> After a call to `decc$write_eof_to_mbx` , the pipe can be reused for communication with another child, for example. This is the purpose of `decc$write_eof_to_mbx` : to allow reuse of the pipe instead of having to close it just to send an end-of-file message.

## Return Values

> 0 | Indicates success
> --1 | Indicates failure; `errno` and `vaxc$errno` are set according to the failure status returned by SYS$QIOW.

## Example

>     /*      decc$write_eof_to_mbx_example.c         */

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

>     #include <fcntl.h>
>     #include <unistd.h>
>     #include <unixio.h>

>     #include <descrip.h>
>     #include <ssdef.h>
>     #include <starlet.h>

>     int decc$write_eof_to_mbx( int );

>     main()
>     {
>         int status, nbytes, failed = 0;
>         int fd, fd2[2];
>         short int channel;
>         $DESCRIPTOR(mbxname_dsc, "TEST_MBX");
>         char c;

>         /* first try a mailbox created by SYS$CREMBX        */

>         status = sys$crembx(0, &channel, 0, 0, 0, 0, &mbxname_dsc, 0, 0);
>         if ( status != SS$_NORMAL ) {
>             printf("sys$crembx failed: %s\n",strerror(EVMSERR, status));
>             failed = 1;
>         }

>         if ( (fd = open(mbxname_dsc.dsc$a_pointer, O_RDWR, 0)) == -1 ) {
>             perror("? open mailbox");
>             failed = 1;
>         }

>         if ( decc$write_eof_to_mbx(fd) == -1 ) {
>             perror("?  decc$write_eof_to_mbx to mailbox");
>             failed = 1;
>         }

>         if ( (nbytes = read(fd, &c, 1)) != 0 || errno != 0 ) {
>             perror("? read mailbox");
>             printf("? nbytes = %d\n", nbytes);
>             failed = 1;
>         }

>         if ( close(fd) == -1 ) {
>             perror("? close mailbox");
>             failed = 1;
>         }

>         /* Now do the same thing with a pipe                */

>         errno = 0;                  /* Clear errno for consistency */

>         if ( pipe(fd2) == -1 ) {
>             perror("? opening pipe");
>             failed = 1;
>         }

>         if ( decc$write_eof_to_mbx(fd2[1]) == -1 ) {
>             perror("? decc$write_eof_to_mbx to pipe");
>             failed = 1;
>         }

>         if ( (nbytes = read(fd2[0], &c, 1)) != 0 || errno != 0 ) {
>             perror("? read pipe");
>             printf("? nbytes = %d\n", nbytes);
>             failed = 1;
>         }

>         /* Close both file descriptors involved with the pipe       */

>         if ( close(fd2[0]) == -1 ) {
>             perror("close(fd2[0])");
>             failed = 1;
>         }

>         if ( close(fd2[1]) == -1 ) {
>             perror("close(fd2[1])");
>             failed = 1;
>         }

>         if ( failed )
>             puts("?Example program failed");
>         else
>             puts("Example ran to completion");
>     }

> This example program produces the following result:

>     Example ran to completion

# [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, Compaq C for OpenVMS Systems interprets it as a file error.

> The `remove` and `delete` functions are functionally equivalent in the Compaq 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:

>     typedef unsigned long int time_t

## Return Value

> n | time2 -- time1 in seconds expressed as a `double` .

# dirname

> Reports the parent directory name of a file path name.

## Format

> #include <libgen.h>

> char *dirname (char *path);

Function Variants This function also has variants named `_dirname32` and `_dirname64` 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

> ### path

> The file path name.

## Description

> This function takes a pointer to a character string that contains a UNIX path name and returns a pointer to a string that is a path name of the parent directory of that file. Trailing '/' (slash) characters in the path are not counted as part of the path.

> The `dirname` function returns a pointer to the string "." (dot), when the path argument:

> - Does not contain a '/' (slash).
> - Is a NULL pointer.
> - Points to an empty string.

> The `dirname` function can modify the string pointed to by the path argument.

> The `dirname` and `basename` functions together yield a complete path name. The expression `dirname` (path) obtains the path name of the directory where `basename` (path) is found.

> See also `basename` in this section.

## Return Values

> x | A pointer to a string that is the parent directory of the path argument.
> "." | The path argument: Does not contain a '/' (slash). Is a NULL pointer. Points to an empty string.

## Example

> Using the `dirname` function, the following example reads a path name, changes the current working directory to the parent directory, and opens a file.

>         char path [MAXPATHLEN], *pathcopy;
>         int fd;

>         fgets(path, MAXPATHLEN, stdin);
>         pathcopy = strdup(path);
>         chdir(dirname(pathcopy));
>         fd = open(basename(path), O_RDONLY);

Previous | Next | Contents | Index

privacy and legal statement