United States

Compaq C

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

Previous | Contents | Index

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.

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

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

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

> See also `fflush` , `pclose` , and `setvbuf` in this section.

## 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 base, double exp);

## Arguments

> ### base

> A value of type `double` that is to be raised to a power.

> ### exp

> The exponent to which the power base is to be raised.

## Description

> Both arguments must be `double` and the returned value is `double` .

## Return Values

> x | The result of the first argument raised to the power of the second.
> 1.0 | Indicates that the base is zero and the exponent is zero.
> HUGE_VAL | Indicates that the result overflowed; `errno` is set to ERANGE.
> --HUGE_VAL | Indicates that the base is zero 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

# 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` in this section.

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

> An object of type `int` .

> ### file_ptr

> A file pointer.

## Description

> 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 `fputc` in this section.

## Return Values

> x | The character written to the file. Indicates success.
> EOF | Indicates output errors.

# putchar

> Writes a single character to the standard output (stdout) and returns the character.

## Format

> #include <stdio.h>

> int putchar (int character);

## Argument

> ### character

> An object of type `int` .

## Description

> This function is identical to `fputc` (character, stdout).

## Return Values

> character | Indicates success.
> EOF | Indicates output errors.

# putenv

> Sets an environmental variable.

## Format

> #include <stdlib.h>

> int putenv (const char *string);

## Arguments

> ### string

> A pointer to a name=value string.

## Description

> This function sets the value of an environment variable by altering an existing variable or by creating a new one. The string argument points to a string of the form name=value, where name is the environment variable and value is the new value for it.

> The string pointed to by string becomes part of the environment, so altering the string changes the environment. When a new string-defining name is passed to `putenv` , the space used by string is no longer used.

> Note The `putenv` function manipulates the environment pointed to by the `environ` external variable, and can be used with `getenv` . However, the third argument to the main function (the environment pointer), is not changed. The `putenv` function uses the `malloc` function to enlarge the environment. A potential error is to call `putenv` with an automatic variable as the argument, then exit the calling function while string is still part of the environment.

## Return Values

> 0 | Indicates success.
> --1 | Indicates an error. `errno` is set to ENOMEM---Not enough memory available to expand the environment list.

## Restriction

> This function cannot take a 64-bit address. See Section 1.8.

# puts

> Writes a character string to the standard output (stdout) followed by a new-line character.

## Format

> #include <stdio.h>

> int puts (const char *str);

## Argument

> ### str

> A pointer to a character string.

## Description

> This function does not copy the terminating null character to the output stream.

## Return Values

> Nonnegative value | Indicates success.
> EOF | Indicates output errors.

# putw

> Writes characters to a specified file.

## Format

> #include <stdio.h>

> int putw (int integer, FILE *file_ptr);

## Arguments

> ### integer

> An object of type `int` or `long` .

> ### file_ptr

> A file pointer.

## Description

> This function writes four characters to the output file as an `int` . No conversion is performed.

## Return Values

> integer | Indicates success.
> EOF | Indicates output errors.

# putwc

> Converts a wide character to its corresponding multibyte value, and writes the result to a specified file.

## Format

> #include <wchar.h>

> wint_t putwc (wint_t wc, FILE *file_ptr);

## Arguments

> ### wc

> An object of type `wint_t` .

> ### file_ptr

> A file pointer.

## Description

> Since `putwc` might be implemented as a macro, a file pointer argument with side effects (for example `putwc (wc, *f++)` ) might be evaluated incorrectly. In such a case, use the `fputwc` function instead. See also `fputwc` in this section.

## Return Values

> x | The character written to the file. Indicates success.
> WEOF | Indicates an output error. The function sets `errno` . For a list of the `errno` values set by this function, see `fputwc` in this section.

# putwchar

> Writes a wide character to the standard output (stdout) and returns the character.

## Format

> #include <wchar.h>

> wint_t putwchar (wint_t wc);

## Arguments

> ### wc

> An object of type `wint_t` .

## Description

> This function is identical to `fputwc` (wc, stdout).

## Return Values

> x | The character written to the file. Indicates success.
> WEOF | Indicates an output error. The function sets `errno` . For a list of the `errno` values set by this function, see `fputwc` in this section.

# qabs, llabs (ALPHA ONLY)

> Returns the absolute value of an integer as an `__int64` . `llabs` is a synonym for `qabs` .

## Format

> #include <stdlib.h>

> __int64 qabs (__int64 j);

> __int64 llabs (__int64 j);

## Argument

> ### j

> A value of type `__int64` .

# qdiv, lldiv (ALPHA ONLY)

> Returns the quotient and the remainder after the division of its arguments. `lldiv` is a synonym for `qdiv` .

## Format

> #include <stdlib.h>

> qdiv_t qdiv (__int64 numer, __int64 denom);

> lldiv_t lldiv (__int64 numer, __int64 denom);

## Arguments

> ### numer

> A numerator of type `__int64` .

> ### denom

> A denominator of type `__int64` .

## Description

> The types `qdiv_t` and `lldiv_t` are defined in the `<stdlib.h>` header file as follows:

>     typedef struct
>              {
>              __int64 quot, rem;
>              } qdiv_t, lldiv_t;

# qsort

> Sorts an array of objects in place. It implements the quick-sort algorithm.

## Format

> #include <stdlib.h>

> void qsort (void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *));

Function Variants This function also has variants named `_qsort32` and `_qsort64` for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

## Arguments

> ### base

> A pointer to the first member of the array. The pointer should be of type pointer-to-element and cast to type pointer-to-character.

> ### nmemb

> The number of objects in the array.

> ### size

> The size of an object, in bytes.

> ### compar

> A pointer to the comparison function.

## Description

> Two arguments are passed to the comparison function pointed to by compar. The two arguments point to the objects being compared. Depending on whether the first argument is less than, equal to, or greater than the second argument, the comparison function returns an integer less then, equal to, or greater than 0.

> The comparison function compar need not compare every byte, so arbitrary data might be contained in the objects in addition to the values being compared.

> The order in the output of two objects that compare as equal is unpredictable.

# raise

> Generates a specified software signal. Generating a signal causes the action routine established by the `signal` , `ssignal` , or `sigvec` function to be invoked.

## Format

> #include <signal.h>

> int raise (int sig); (ANSI C)

> int raise (int sig[, int sigcode]); (DEC C EXTENSION)

## Arguments

> ### sig

> The signal to be generated.

> ### sigcode

> An optional signal code, available only when not compiling in strict ANSI C mode. For example, signal SIGFPE---the arithmetic trap signal---has 10 different codes, each representing a different type of arithmetic trap.

> The signal codes can be represented by mnemonics or numbers. The arithmetic trap codes are represented by the numbers 1 to 10; the SIGILL codes are represented by the numbers 0 to 2. The code values are defined in the `<signal.h>` header file. See Tables 4_4 and 4-5 for a list of signal mnemonics, codes, and corresponding OpenVMS exceptions.

## Description

> Calling this function has one of the following results:
> - If `raise` specifies a sig argument that is outside the range defined in the `<signal.h>` header file, then the `raise` function returns 0, and the `errno` variable is set to EINVAL.
> - If `signal` , `ssignal` , or `sigvec` establishes SIG_DFL (default action) for the signal, then the functions do not return. The image is exited with the OpenVMS error code corresponding to the signal.
> - If `signal` , `ssignal` , or `sigvec` establishes SIG_IGN (ignore signal) as the action for the signal, then `raise` returns its argument, sig.
> - `signal` , `ssignal` , or `sigvec` must establish an action function for the signal. That function is called and its return value is returned by `raise` .

> See Chapter 4 for more information on signal processing. See also `gsignal` , `signal` , `ssignal` , and `sigvec` in this section.

## Return Values

> 0 | If successful.
> nonzero | If unsuccessful.

Previous | Next | Contents | Index

privacy and legal statement