[an error occurred while processing this directive]

HP OpenVMS Systems

C Programming Language

HP C

HP C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

nrand48

Generates uniformly distributed pseudorandom-number sequences. Returns 48-bit signed long integers.

Format

#include <stdlib.h>
long int nrand48 (unsigned short int xsubi[3]);

Argument

xsubi
An array of three short int s that, when concatentated together, form a 48-bit integer.

Description

The nrand48 function generates pseudorandom numbers using the linear congruential algorithm and 48-bit integer arithmetic.
The nrand48 function returns nonnegative, long integers uniformly distributed over the range of y values, such that 0 <= y < 2³¹ .
The 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 the lcong48 function, the multiplier value a and the addend value c are:
a = 5DEECE66D₁₆ = 273673163155₈ c = B₁₆ = 13₈
The nrand48 function requires that the calling program pass an array as the xsubi argument, which for the first call must be initialized to the initial value of the pseudorandom-number sequence. Unlike the drand48 function, it is not necessary to call an initialization function prior to the first call.
By using different arguments, the nrand48 function allows separate modules of a large program to generate several independent sequences of pseudorandom numbers. For example, the sequence of numbers that one module generates does not depend upon how many times the functions are called by other modules.

Return Value

n Returns nonnegative, long integers over the range 0 <= y < 2 ³¹ .

open

Opens a file for reading, writing, or editing. It positions the file at its beginning (byte 0).

Format

#include <fcntl.h>
int open (const char *file_spec, int flags, mode_t mode); (ANSI C)
int open (const char *file_spec, int flags, ...); (HP C EXTENSION)

Arguments

file_spec
A null-terminated character string containing a valid file specification. If you specify a directory in the file_spec and it is a search list that contains an error, HP C interprets it as a file open error.
flags
The following values are defined in the <fcntl.h> header file:

O_RDONLY Open for reading only

O_WRONLY Open for writing only

O_RDWR Open for reading and writing

O_NDELAY Open for asynchronous input

O_APPEND Append on each write

O_CREAT Create a file if it does not exist

O_TRUNC Create a new version of this file

O_EXCL Error if attempting to create existing file

These flags are set using the bitwise OR operator (|) to separate specified flags.
Opening a file with O_APPEND causes each write on the file to be appended to the end. (In contrast, with the VAX C RTL the behavior of files opened in append mode was to start at EOF and, thereafter, write at the current file position.)
If O_TRUNC is specified and the file exists, open creates a new file by incrementing the version number by 1, leaving the old version in existence.
If O_CREAT is set and the named file does not exist, the HP C RTL creates it with any attributes specified in the fourth and subsequent arguments (...). If O_EXCL is set with O_CREAT and the named file exists, the attempted open returns an error.
mode
An unsigned value that specifies the file-protection mode. The compiler performs a bitwise AND operation on the mode and the complement of the current protection mode.
You can construct modes by using the bitwise OR operator (|) to separate specified modes. The modes are:

0400 OWNER:READ

0200 OWNER:WRITE

0100 OWNER:EXECUTE

0040 GROUP:READ

0020 GROUP:WRITE

0010 GROUP:EXECUTE

0004 WORLD:READ

0002 WORLD:WRITE

0001 WORLD:EXECUTE

The system is given the same access privileges as the owner. A WRITE privilege also implies a DELETE privilege.
...
Optional file attribute arguments. The file attribute arguments are the same as those used in the creat function. For more information, see the creat function.

Description

If a version of the file exists, a new file created with open inherits certain attributes from the existing file unless those attributes are specified in the open call. The following attributes are inherited: record format, maximum record size, carriage control, and file protection.

Notes

If you intend to do random writing to a file, the file must be opened for update by specifying a flags value of O_RDWR .
To create files with OpenVMS RMS default protections by using the UNIX system-call functions umask , mkdir , creat , and open , call mkdir , creat , and open with a file-protection mode argument of 0777 in a program that never specifically calls umask . These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on.

In programs that do vfork / exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.

See also creat , read , write , close , dup , dup2 , and lseek .

Return Values

x A nonnegative file descriptor number.

- 1 Indicates that the file does not exist, that it is protected against reading or writing, or that it cannot be opened for another reason.

Example

#include <unixio.h> 
#include <fcntl.h> 
#include <stdlib.h> 
 
main() 
{ 
    int file, 
        stat; 
    int flags; 
 
    flags = O_RDWR;  /*  Open for read and write,            */ 
                     /*  with user default file protection,  */ 
                     /*  with max fixed record size of 2048, */ 
                     /*  and a block size of 2048 bytes.     */ 
 
file = open("file.dat", flags, 0, "rfm=fix", "mrs=2048", "bls=2048"); 
    if (file == -1) 
        perror("OPEN error"), exit(1); 
 
    close(file); 
}

opendir

Opens a specified directory.

Format

#include <dirent.h>
DIR *opendir (const char *dir_name);

Argument

dir_name
The name of the directory to be opened.

Description

The opendir function opens the directory specifed by dir_name and associates a directory stream with it. The directory stream is positioned at the first entry. The type DIR , defined in the <dirent.h> header file, represents a directory stream. A directory stream is an ordered sequence of all the directory entries in a particular directory.
The opendir function also returns a pointer to identify the directory stream in subsequent operations. The NULL pointer is returned when the directory named by dir_name cannot be accessed, or when not enough memory is available to hold the entire stream.

Note
An open directory must always be closed with the closedir function to ensure that the next attempt to open that directory is successful. The opendir function should be used with readdir , closedir , and rewinddir to examine the contents of the directory.

Example

See the program example in the description of closedir .

Return Values

x A pointer to an object of type DIR .

NULL Indicates an error; errno is set to one of the following values:

EACCES -- Search permission is denied for any component of dir_name or read permission is denied for dir_name.
ENAMETOOLONG -- The length of the dir_name string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
ENOENT -- The dir_name argument points to the name of a file that does not exist, or is an empty string.

overlay

Nondestructively superimposes win1 on win2. The function writes the contents of win1 that will fit onto win2 beginning at the starting coordinates of both windows. Blanks on win1 leave the contents of the corresponding space on win2 unaltered. The overlay function copies as much of a window's box as possible.

Format

#include <curses.h>
int overlay (WINDOW *win1, WINDOW *win2);

Arguments

win1
A pointer to the window.
win2
A pointer to the window.

Return Values

OK Indicates success.

ERR Indicates an error.

overwrite

Destructively writes the contents of win1 on win2.

Format

#include <curses.h>
int overwrite (WINDOW *win1, WINDOW *win2);

Arguments

win1
A pointer to the window.
win2
A pointer to the window.

Description

The overwrite function writes the contents of win1 that will fit onto win2 beginning at the starting coordinates of both windows. Blanks on win1 are written on win2 as blanks. This function copies as much of a window's box as possible.

Return Values

OK Indicates success.

ERR Indicates failure.

pathconf

Retrieves file implementation characteristics.

Format

#include <unistd.h>
long int pathconf (const char *path, int name);

Arguments

path
The pathname of a file or directory.
name
The configuration attribute to query. If this attribute is not applicable to the file specified by the path argument, the pathconf function returns an error.

Description

The pathconf function allows an application to determine the characteristics of operations supported by the file system underlying the file named by path. Read, write, or execute permission of the named file is not required, but you must be able to search all directories in the path leading to the file.
Symbolic values for the name argument are defined in the <unistd.h> header file, as follows:

_PC_LINK_MAX The maximum number of links to the file. If the path argument refers to a directory, the value returned applies to the directory itself.

_PC_MAX_CANON The maximum number of bytes in a canonical input line. This is applicable only to terminal devices.

_PC_MAX_INPUT The number of types allowed in an input queue. This is applicable only to terminal devices.

_PC_NAME_MAX Maximum number of bytes in a file name (not including a terminating null). The byte range value is between 13 and 255. This is applicable only to a directory file. The value returned applies to file names within the directory.

_PC_PATH_MAX Maximum number of bytes in a pathname (not including a terminating null). The value is never larger than 65,535. This is applicable only to a directory file. The value returned is the maximum length of a relative pathname when the specified directory is the working directory.

_PC_PIPE_BUF Maximum number of bytes guaranteed to be written atomically. This is applicable only to a FIFO. The value returned applies to the referenced object. If the path argument refers to a directory, the value returned applies to any FIFO that exists or can be created within the directory.

_PC_CHOWN_RESTRICTED This is applicable only to a directory file. The value returned applies to any files (other than directories) that exist or can be created within the directory.

_PC_NO_TRUNC Returns 1 if supplying a component name longer than allowed by NAME_MAX causes an error. Returns 0 (zero) if long component names are truncated. This is applicable only to a directory file.

_PC_VDISABLE This is always 0 (zero); no disabling character is defined. This is applicable only to a terminal device.

Return Values

x Resultant value of the configuration attribute specified in name.

- 1 Indicates an error; errno is set to one of the following values:

EACCES -- Search permission is denied for a component of the path prefix.
EINVAL -- The name argument specifies an unknown or inapplicable characteristic.
EFAULT -- The path argument is an invalid address.
ENAMETOOLONG -- The length of the path string exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
ENOENT -- The named file does not exist or the path argument points to an empty string.
ENOTDI -- A component of the path prefix is not a directory.

pause

Suspends the calling process until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.

Format

#include <unistd.h>
int pause (void);

Description

The pause function suspends the calling process until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.
If the action is to terminate the process, pause does not return.
If the action is to execute a signal-catching function, pause returns after the signal-catching function returns.

Return Value

Since the pause function suspends process execution indefinitely unless interrupted by a signal, there is no successful completion return value.

- 1 In cases where pause returns, the return value is - 1, and errno is set to EINTR.

pclose

Closes a pipe to a process.

Format

#include <stdio.h>
int pclose (FILE *stream);

Arguments

stream
A pointer to a FILE structure for an open pipe returned by a previous call to the popen function.

Description

The pclose function closes a pipe between the calling program and a shell command to be executed. Use pclose to close any stream you have opened with popen . The pclose function waits for the associated process to end, and then returns the exit status of the command. See the description of waitpid for information on interpreting the exit status.
Beginning with OpenVMS Version 7.3-1, when compiled with the _VMS_WAIT macro defined, the pclose function returns the OpenVMS completion code of the child process.
See also popen .

Return Values

x Exit status of child.

- 1 Indicates an error. The stream argument is not associated with a popen function. errno is set to the following:

ECHILD -- cannot obtain the status of the child process.

perror

Writes a short error message to stderr describing the current value of errno .

Format

#include <stdio.h>
void perror (const char *str);

Argument

str
Usually the name of the program that caused the error.

Description

The perror function uses the error number in the external variable errno to retrieve the appropriate locale-dependent error message. The function writes out the message as follows: str (a user-supplied prefix to the error message), followed by a colon and a space, followed by the message itself, followed by a new-line character.
See the description of errno in Chapter 4 for a list of possible errors.
See also strerror .

Example

#include <stdio.h> 
#include <stdlib.h> 
 
main(argc, argv) 
    int argc; 
    char *argv[]; 
{ 
    FILE *fp; 
 
    fp = fopen(argv[1], "r");   /* Open an input file. */ 
    if (fp == NULL) { 
 
        /* If the fopen call failed, perror prints out a        */ 
        /* diagnostic:                                          */ 
        /*                                                      */ 
        /*  "open: <error message>"                             */ 
        /*  This error message provides a diagnostic explaining */ 
        /*  the cause of the failure.                           */ 
 
        perror("open"); 
        exit(EXIT_FAILURE); 
    } 
    else 
        fclose(fd) ; 
}

Contents

Index

HP OpenVMS Systems

HP CRun-Time Library Reference Manual for OpenVMS Systems

nrand48

Format

Argument

xsubi

Description

Return Value

open

Format

Arguments

file_spec

flags

mode

...

Description

Return Values

Example

opendir

Format

Argument

dir_name

Description

Example

Return Values

overlay

Format

Arguments

win1

win2

Return Values

overwrite

Format

Arguments

win1

win2

Description

Return Values

pathconf

Format

Arguments

path

name

Description

Return Values

pause

Format

Description

Return Value

pclose

Format

Arguments

stream

Description

Return Values

perror

Format

Argument

str

Description

Example

HP C
Run-Time Library Reference Manual for OpenVMS Systems