[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

pipe

Creates a temporary mailbox that can be used to read and write data between a parent and child process. The channels through which the processes communicate are called a pipe.

Format

#include <unistd.h>
int pipe (int array_fdscptr[2]); (ISO POSIX-1)
int pipe (int array_fdscptr[2], ...); (HP C EXTENSION)

Arguments

array_fdscptr
An array of file descriptors. A pipe is implemented as an array of file descriptors associated with a mailbox. These mailbox descriptors are special in that these are the only file descriptors which, when passed to the isapipe function, will return 1.
The file descriptors are allocated in the following way:

The first available file descriptor is assigned to writing, and the next available file descriptor is assigned to reading.
The file descriptors are then placed in the array in reverse order; element 0 contains the file descriptor for reading, and element 1 contains the file descriptor for writing.

...
Represents three optional, positional arguments, flag, bufsize, and bufquota:
flag
An optional argument used as a bitmask.
If either the O_NDELAY or O_NONBLOCK bit is set, the I/O operations to the mailbox through array_fdscptr file descriptors terminate immediately, rather than waiting for another process.
If, for example, the O_NDELAY bit is set and the child issues a read request to the mailbox before the parent has put any data into it, the read terminates immediately with 0 status. If neither the O_NDELAY nor O_NONBLOCK bit is set, the child will be waiting on the read until the parent writes any data into the mailbox. This is the default behavior if no flag argument is specified.
The values of O_NDELAY and O_NONBLOCK are defined in the <fcntl.h> header file. Any other bits in the flag argument are ignored. You must specify this argument if the second optional, positional argument bufsize is specified. If the flag argument is needed only to allow specification of the bufsize argument, specify flag as 0.
bufsize
Optional argument of type int that specifies the size of the mailbox, in bytes. Specify a value from 512 to 65535.
If you specify 0 or omit this argument, the operating system creates a mailbox with a default size of 512 bytes.
If you specify a value less than 0 or larger than 65535, the results are unpredictable.
If you do specify this argument, be sure to precede it with a flag argument.
The DECC$PIPE_BUFFER_SIZE feature logical can also be used to specify the size of the mailbox. If bufsize is supplied, it takes precedence over the value of DECC$PIPE_BUFFER_SIZE. Otherwise, the value of DECC$PIPE_BUFFER_SIZE is used.
If neither bufsize nor DECC$PIPE_BUFFER_SIZE is specified, the default buffer size of 512 is used.
bufquota
Optional argument of type int that specifies the buffer quota of the pipe's mailbox. Specify a value from 512 to 2147483647.
OpenVMS Version 7.3-2 added this argument. In previous OpenVMS versions, the buffer quota was equal to the buffer size.
The DECC$PIPE_BUFFER_QUOTA feature logical can also be used to specify the buffer quota. If the optional bufquota argument of the pipe function is supplied, it takes precedence over the value of DECC$PIPE_BUFFER_QUOTA. Otherwise, the value of DECC$PIPE_BUFFER_QUOTA is used.
If neither bufquota nor DECC$PIPE_BUFFER_QUOTA is specified, then the buffer quota defaults to the buffer size.

Description

The mailbox used for the pipe is a temporary mailbox. The mailbox is not deleted until all processes that have open channels to that mailbox close those channels. The last process that closes a pipe writes a message to the mailbox, indicating the end-of-file.
The mailbox is created by using the $CREMBX system service, specifying the following characteristics:

A maximum message length of 512 characters
A buffer quota of 512 characters
A protection mask granting all privileges to USER and GROUP and no privileges to SYSTEM or WORLD

The buffer quota of 512 characters implies that you cannot write more than 512 characters to the mailbox before all or part of the mailbox is read. Since a mailbox record is slightly larger than the data part of the message that it contains, not all of the 512 characters can be used for message data. You can increase the size of the buffer by specifying an alternative size using the optional, third argument to the pipe function. A pipe under the OpenVMS system is a stream-oriented file with no carriage-control attributes. It is fully buffered by default in the HP C RTL. A mailbox used as a pipe is different than a mailbox created by the application. A mailbox created by the application defaults to a record-oriented file with carriage return, carriage control. Additionally, writing a zero-length record to a mailbox writes an EOF, as does each close of the mailbox. For a pipe, only the last close of a pipe writes an EOF.
The pipe is created by the parent process before vfork and an exec function are called. By calling pipe first, the child inherits the open file descriptors for the pipe. You can then use the getname function to return the name of the mailbox associated with the pipe, if this information is desired. The mailbox name returned by getname has the format _MBAnnnn: (ALPHA ONLY) or _MBAnnnnn: (I64 ONLY) , where nnnn or nnnnn is a unique number.
Both the parent and the child need to know in advance which file descriptors will be allocated for the pipe. This information cannot be retrieved at run time. Therefore, it is important to understand how file descriptors are used in any HP C for OpenVMS program. For more information about file descriptors, see Chapter 2.
File descriptors 0, 1, and 2 are open in a HP C for OpenVMS program for stdin (SYS$INPUT), stdout (SYS$OUTPUT), and stderr (SYS$ERROR), respectively. Therefore, if no other files are open when pipe is called, pipe assigns file descriptor 3 for writing and file descriptor 4 for reading. In the array returned by pipe , 4 is placed in element 0 and 3 is placed in element 1.
If other files have been opened, pipe assigns the first available file descriptor for writing and the next available file descriptor for reading. In this case, the pipe does not necessarily use adjacent file descriptors. For example, assume that two files have been opened and assigned to file descriptors 3 and 4 and the first file is then closed. If pipe is called at this point, file descriptor 3 is assigned for writing and file descriptor 5 is assigned for reading. Element 0 of the array will contain 5 and element 1 will contain 3.
In large applications that do large amounts of I/O, it gets more difficult to predict which file descriptors are going to be assigned to a pipe; and, unless the child knows which file descriptors are being used, it will not be able to read and write successfully from and to the pipe.
One way to be sure that the correct file descriptors are being used is to use the following procedure:

Choose two descriptor numbers that will be known to both the parent and the child. The numbers should be high enough to account for any I/O that might be done before the pipe is created.
Call pipe in the parent at some point before calling an exec function.
In the parent, use dup2 to assign the file descriptors returned by pipe to the file descriptors you chose. This now reserves those file descriptors for the pipe; any subsequent I/O will not interfere with the pipe.

You can read and write through the pipe using the UNIX I/O functions read and write , specifying the appropriate file descriptors. As an alternative, you can issue fdopen calls to associate file pointers with these file descriptors so that you can use the Standard I/O functions ( fread and fwrite ).
Two separate file descriptors are used for reading from and writing to the pipe, but only one mailbox is used so some I/O synchronization is required. For example, assume that the parent writes a message to the pipe. If the parent is the first process to read from the pipe, then it will read its own message back as shown in Figure REF-1.

Note
For added UNIX portability, you can use the following feature logicals to control the behavior of the C RTL pipe implementation:

Define the DECC$STREAM_PIPE feature logical name to ENABLE to direct the pipe function to use stream I/O instead of record I/O.
Define the DECC$POPEN_NO_CRLF_REC_ATTR feature logical to ENABLE to prevent CR/LF carriage control from being added to pipe records for pipes opened with the popen function. Be aware that enabling this feature might result in undesired behavior from other functions such as gets that rely on the carriage-return character.

Figure REF-1 Reading and Writing to a Pipe

Return Values

0 Indicates success.

- 1 Indicates an error.

popen

Initiates a pipe to a process.

Format

#include <stdio.h>
FILE *popen (const char *command, const char *type);

Arguments

command
A pointer to a null-terminated string containing a shell command line.
type
A pointer to a null-terminated string containing an I/O mode. Because open files are shared, you can use a type r command as an input filter and a type w command as an output filter. Specify one of the following values for the type argument:

r ---the calling program can read from the standard output of the command by reading from the returned file stream.
w ---the calling program can write to the standard input of the command by writing to the returned file stream.

Description

The popen function creates a pipe between the calling program and a shell command awaiting execution. It returns a pointer to a FILE structure for the stream.
The popen function uses the value of the DECC$PIPE_BUFFER_SIZE feature logical to set the buffer size of the mailbox it creates for the pipe. You can specify a DECC$PIPE_BUFFER_SIZE value of 512 to 65024 bytes. If DECC$PIPE_BUFFER_SIZE is not specified, the default buffer size of 512 is used.

Notes

When you use the popen function to invoke an output filter, beware of possible deadlock caused by output data remaining in the program buffer. You can avoid this by either using the setvbuf function to ensure that the output stream is unbuffered, or the fflush function to ensure that all buffered data is flushed before calling the pclose function.
For added UNIX portability, you can use the following feature logicals to control the behavior of the C RTL pipe implementation:

Define the DECC$STREAM_PIPE feature logical name to ENABLE to direct the pipe function to use stream I/O instead of record I/O.
Define the DECC$POPEN_NO_CRLF_REC_ATTR feature logical to ENABLE to prevent CR/LF carriage control from being added to pipe records for pipes opened with the popen function. Be aware that enabling this feature might result in undesired behavior from other functions such as gets that rely on the carriage-return character.

See also fflush , pclose , and setvbuf .

Return Values

x A pointer to the FILE structure for the opened stream.

NULL Indicates an error. Unable to create files or processes.

pow

Returns the first argument raised to the power of the second argument.

Format

#include <math.h>
double pow (double x, double y);
float powf (float x, float y); (ALPHA, I64)
long double powl (long double x, long double y); (ALPHA, I64)

Arguments

x
A floating-point base to be raised to an exponent y.
y
The exponent to which the base x is to be raised.

Description

The pow functions raise a floating-point base x to a floating-point exponent y. The value of pow (x,y) is computed as e**(y ln(x)) for positive x.
If x is 0 and y is negative, - HUGE_VAL is returned, and errno is set to EDOM.

Return Values

x The result of the first argument raised to the power of the second.

1.0 The base is 0 and the exponent is 0.

HUGE_VAL The result overflowed; errno is set to ERANGE.

- HUGE_VAL The base is 0 and the exponent is negative; errno is set to EDOM.

Example

#include <stdio.h> 
#include <math.h> 
#include <errno.h> 
 
main() 
{ 
    double x; 
 
    errno = 0; 
 
    x = pow(-3.0, 2.0); 
    printf("%d, %f\n", errno, x); 
}

This example program outputs the following:

0, 9.000000

pread (ALPHA, I64)

Reads bytes from a given position within a file without changing the file pointer.

Format

#include <unistd.h>
ssize_t pread (int file_desc, void *buffer, size_t nbytes, off_t offset);

Arguments

file_desc
A file descriptor that refers 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.
offset
The offset for the desired position inside the file.

Description

The pread function performs the same action as read , except that it reads from a given position in the file without changing the file pointer. The first three arguments to pread are the same as for read , with the addition of a fourth argument offset for the desired position inside the file. An attempt to perform a pread on a file that is incapable of seeking results in an error.

Return Values

n The number of bytes read.

- 1 Upon failure, the file pointer remains unchanged and pread sets errno to one of the following values:

EINVAL -- The offset argument is invalid. The value is negative.
EOVERFLOW -- The file is a regular file, and an attempt was made to read or write at or beyond the offset maximum associated with the file.
ENXIO -- A request was outside the capabilities of the device.
ESPIPE -- fildes is associated with a pipe or FIFO.

printf

Performs formatted output from the standard output ( stdout ). See Chapter 2 for information on format specifiers.

Format

#include <stdio.h>
int printf (const char *format_spec, ...);

Arguments

format_spec
Characters to be written literally to the output or converted as specified in the ... arguments.
...
Optional expressions whose resultant types correspond to conversion specifications given in the format specification.
If no conversion specifications are given, you may omit the output sources. Otherwise, the function call must have exactly as many output sources as there are conversion specifications, and the conversion specifications must match the types of the output sources.
Conversion specifications are matched to output sources in left-to-right order. Excess output pointers, if any, are ignored.

Return Values

x The number of bytes written.

Negative value Indicates that an output error occurred. The function sets errno . For a list of errno values set by this function, see fprintf .

[w]printw

Perform a printf in the specified window, starting at the current position of the cursor. The printw function acts on the stdscr window.

Format

#include <curses.h>
printw (char *format_spec, ...);
int wprintw (WINDOW *win, char *format_spec, ...);

Arguments

win
A pointer to the window.
format_spec
A pointer to the format specification string.
...
Optional expressions whose resultant types correspond to conversion specifications given in the format specification.
If no conversion specifications are given, you may omit the output sources. Otherwise, the function call must have exactly as many output sources as there are conversion specifications, and the conversion specifications must match the types of the output sources.
Conversion specifications are matched to output sources in left-to-right order. Excess output pointers, if any, are ignored.

Description

The formatting specification (format_spec) and the other arguments are identical to those used with the printf function.
The printw and wprintw functions format and then print the resultant string to the window using the addstr function. For more information, see the printf and scrollok functions in this section. See Chapter 2 for information on format specifiers.

Return Values

OK Indicates success.

ERR Indicates that the function makes the window scroll illegally.

putc

The putc macro writes a single character to a specified file.

Format

#include <stdio.h>
int putc (int character, FILE *file_ptr);

Arguments

character
The character to be written.
file_ptr
A file pointer to the output stream.

Description

The putc macro writes the byte character (converted to an unsigned char) to the output specified by the file_ptr parameter. The byte is written at the position at which the file pointer is currently pointing (if defined) and advances the indicator appropriately. If the file cannot support positioning requests, or if the output stream was opened with append mode, the byte is appended to the output stream.
Since putc is a macro, a file pointer argument with side effects (for example, putc (ch, *f++) ) might be evaluated incorrectly. In such a case, use the fputc function instead.
See also putc_unlocked .

Return Values

x The character written to the file. Indicates success.

EOF Indicates output errors.

Contents

Index

HP OpenVMS Systems

HP CRun-Time Library Reference Manual for OpenVMS Systems

pipe

Format

Arguments

array_fdscptr

...

flag

bufsize

bufquota

Description

Return Values

popen

Format

Arguments

command

type

Description

Return Values

pow

Format

Arguments

x

y

Description

Return Values

Example

pread (ALPHA, I64)

Format

Arguments

file_desc

buffer

nbytes

offset

Description

Return Values

printf

Format

Arguments

format_spec

...

Return Values

[w]printw

Format

Arguments

win

format_spec

...

Description

Return Values

putc

Format

Arguments

character

file_ptr

Description

Return Values

HP C
Run-Time Library Reference Manual for OpenVMS Systems