[an error occurred while processing this directive]

HP OpenVMS Systems

C Programming Language

Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

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 argument 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.10 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);

div

Returns the quotient and the remainder after the division of its arguments.

Format

#include <stdlib.h>
div_t div (int numer, int denom);

Arguments

numer
A numerator of type int .
denom
A denominator of type int .

Description

The type div_t is defined in the standard header file <stdlib.h> as follows:
typedef struct { int quot, rem; } div_t;

dlclose

Deallocates the address space for a shared library.

Format

#include <stdio.h>
void dlclose (void *handle);

Arguments

handle
Pointer to the shared library.

Description

The dlclose function deallocates the address space allocated by the Compaq C RTL for the handle.
There is no way on OpenVMS systems to "unload" a shareable image dynamically loaded by the LIB$FIND_IMAGE_SYMBOL routine, which is the routine called by the dlsym function. In other words, there is no way on OpenVMS systems to release the address space occupied by the shareable image brought into memory by dlsym .

dlerror

Returns a string describing the last error that occurred from a call to dlopen , dlclose , or dlsym .

Format

#include <stdio.h>
char *dlerror (void);

Return Values

x A string describing the last error that occurred from a call to dlopen , dlclose , or dlsym .

dlopen

Provides an interface to the dynamic library loader to allow shareable images to be loaded and called at run time.

Format

#include <stdio.h>
void *dlopen (char *pathname, int mode);

Arguments

pathname
The name of the shareable image. This name is saved for subsequent use by the dlsym function.
mode
This argument is ignored on OpenVMS systems.

Description

This function provides an interface to the dynamic library loader to allow shareable images to be loaded and called at run time.
The dlopen function does not load a shareable image but rather saves its pathname argument for subsequent use by the dlsym function. dlsym is the function that actually loads the shareable image through a call to LIB$FIND_IMAGE_SYMBOL.
The pathname argument of the dlopen function must be the name of the shareable image. This name is passed as-is by the dlsym function to the LIB$FIND_IMAGE_SYMBOL routine as the filename argument. No image-name argument is specified in the call to LIB$FIND_IMAGE_SYMBOL, so default file specification of SYS$SHARE:.EXE is applied to the image name.
The dlopen function returns a handle that is used by a dlsym or dlclose call. If an error occurs, a NULL pointer is returned.

Return Values

x A handle to be used by a dlsym or dlclose call.

NULL Indicates an error.

dlsym

Returns the address of the symbol name found in a shareable image.

Format

#include <stdio.h>
void *dlsym (void *handle, char *name);

Arguments

handle
Pointer to the shareable image.

Description

The dlsym function returns the address of the symbol name found in the shareable image corresponding to handle. If the symbol is not found, a NULL pointer is returned.

Return Values

x Address of the symbol name found.

NULL Indicates that the symbol was not found.

drand48

Generates uniformly distributed pseudorandom number sequences. Returns 48-bit, nonnegative, double-precision floating-point values.

Format

#include <stdlib.h>
double drand48 (void);

Description

This function generates pseudorandom numbers using the linear congruential algorithm and 48-bit integer arithmetic.
It returns non-negative, double-precision, floating-point values uniformly distributed over the range of y values such that 0.0 <= y < 1.0.
Before you call drand48 , use either srand48 , seed48 , or lcong48 to initialize the random number generator. You must initalize prior to invoking the drand48 function because it stores the last 48-bit Xi generated into an internal buffer. (Although it is not recommended, constant default initializer values are supplied automatically if the drand48 , lrand48 , or mrand48 functions are called without first calling an initialization function.)
The drand48 function works by generating a sequence of 48-bit integer values, Xi, according to the linear congruential formula:
Xn+1 = (aXn+c)mod m n >= 0
The argument m equals 2⁴⁸ , so 48-bit integer arithmetic is performed. Unless you invoke lcong48 , the multiplier value a and the addend value c are:
a = 5DEECE66D₁₆ = 273673163155₈ c = B₁₆ = 13₈
The values returned by drand48 are computed by first generating the next 48-bit Xi in the sequence. Then the appropriate bits, according to the type of returned data item, are copied from the high-order (most significant) bits of Xi and transformed into the returned value.
See also srand48 , seed48 , lcong48 , lrand48 , and mrand48 in this section.

Return Values

n A nonnegative, double-precision, floating-point value.

Contents

Index

HP OpenVMS Systems

Compaq CRun-Time Library Reference Manual for OpenVMS Systems

decc$translate_vms

Format

Argument

vms_filespec

Description

Return Values

Example

decc$validate_wchar

Format

Argument

wc

Description

Return Values

decc$write_eof_to_mbx

Format

Argument

fd

Description

Return Values

Example

[w]delch

Format

Argument

win

Description

Return Values

delete

Format

Argument

file_spec

Description

Return Values

[w]deleteln

Format

Argument

win

Description

Return Values

delwin

Format

Argument

win

Description

Return Values

difftime

Format

Arguments

time2

time1

Description

Return Value

dirname

Format

Argument

path

Description

Return Values

Example

div

Format

Arguments

numer

denom

Description

dlclose

Format

Arguments

handle

Description

dlerror

Format

Return Values

dlopen

Format

Arguments

pathname

mode

Description

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems