United States

Compaq C

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

Previous | Contents | Index

# fwprintf

> Writes output to the stream under control of the wide-character format string.

## Format

> #include <wchar.h>

> int fwprintf (FILE *stream, const wchar_t *format, ...);

## Arguments

> ### stream

> A file pointer.

> ### format

> A pointer to a wide-character string containing the format specifications. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

> ### ...

> Optional expressions whose resultant types correspond to conversion specifications given in the format specification.

> If no conversion specifications are given, the output sources can be omitted. Otherwise, the function calls 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. Any excess output sources are ignored.

## Description

> This function writes output to the stream pointed to by stream under control of the wide-character string pointed to by format, which specifies how to convert subsequent arguments to output. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated, but are otherwise ignored. The `fwprintf` function returns when it encounters the end of the format string.

> The format argument is composed of zero or more directives that include:

> - Ordinary wide characters (not the percent sign (%))
> - Conversion specifications

## Return Values

> n | The number of wide characters written.
> Negative value | Indicates an error. The function sets `errno` to one of the following: EILSEQ -- Invalid character detected. EINVAL -- Insufficient arguments. ENOMEM -- Not enough memory available for conversion. ERANGE -- Floating-point calculations overflow. EVMSERR -- Nontranslatable VMS error. `vaxc$errno` contains the VMS error code. This might indicate that conversion to a numeric value failed because of overflow. The function can also set `errno` to the following as a result of errors returned from the I/O subsystem: EBADF -- The file descriptor is not valid. EIO -- I/O error. ENOSPC -- No free space on the device containing the file. ENXIO -- Device does not exist. EPIPE -- Broken pipe. ESPIPE -- Illegal seek in a file opened for append. EVMSERR -- Nontranslatable VMS error. `vaxc$errno` contains the VMS error code. This indicates that an I/O error occurred for which there is no equivalent C error code.

## Example

> The following example shows how to print a date and time in the form "Sunday, July 3, 10:02", followed by Pi sign to five decimal places:

>      #include <math.h>
>      #include <stdio.h>
>      #include <wchar.h>
>      /*...*/
>      wchar_t *weekday, *month; /* pointers to wide-character strings */
>      int day, hours, min;
>      fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
>         weekday, month, day, hour, min);
>      fwprintf(stdout, L"pi = %.5f\n", 4 * atan(1.0));

# fwrite

> Writes a specified number of items to the file.

## Format

> #include <stdio.h>

> size_t fwrite (const void *ptr, size_t size_of_item, size_t number_items, FILE *file_ptr);

## Arguments

> ### ptr

> A pointer to the memory location from which information is being written. The type of the object pointed to is determined by the type of the item being written.

> ### size_of_item

> The size, in bytes, of the items being written.

> ### number_items

> The number of items to be written.

> ### file_ptr

> A file pointer that indicates the file to which the items are being written.

## Description

> The type `size_t` is defined in the header file `<stdio.h>` as follows:

>     typedef unsigned int size_t

> The writing begins at the current location in the file. The items are written from storage beginning at the location given by the first argument. You must also specify the size of an item, in bytes.

> If the file pointed to by file_ptr is a record file, the `fwrite` function outputs at least number_items records, each of length size_of_item.

## Return Value

> x | The number of items written. The number of records written depends upon the maximum record size of the file.

# fwscanf

> Reads input from the stream under control of the wide-character format string.

## Format

> #include <wchar.h>

> int fwscanf (FILE *stream, const wchar_t *format, ...);

## Arguments

> ### stream

> A file pointer.

> ### format

> A pointer to a wide-character string containing the format specification. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

> ### ...

> Optional expressions whose results correspond to conversion specifications given in the format specification. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

> If no conversion specifications are given, you can omit the input pointers. Otherwise, the function calls must have exactly as many input pointers as there are conversion specifications, and the conversion specifications must match the types of the input pointers.

> Conversion specifications are matched to input sources in left-to-right order. Excess input pointers, if any, are ignored.

## Description

> This function reads input from the stream pointed to by stream under the control of the wide-character string pointed to by format. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated, but otherwise ignored.

> The format is composed of zero or more directives that include:

> - One or more white-space wide characters.
> - An ordinary wide character (neither a percent (%)) nor a white-space wide character).
> - Conversion specifications.

> Each conversion specification is introduced by the wide character %.

> If the stream pointed to by the stream argument has no orientation, `fwscanf` makes the stream wide-oriented.

## Return Values

> n | The number of input items assigned, sometimes fewer than provided for, or even zero, in the event of an early matching failure.
> EOF | Indicates an error; input failure occurs before any conversion.

# gcvt

> Converts its argument to a null-terminated string of ASCII digits and returns the address of the string.

## Format

> #include <stdlib.h>

> char *gcvt (double value, int ndigit, char *buffer);

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

> ### value

> An object of type `double` that is converted to a null-terminated string of ASCII digits.

> ### ndigit

> The number of ASCII digits to use in the converted string. If ndigit is less than 6, the value of 6 is used.

> ### buffer

> A storage location to hold the converted string.

## Description

> This function places the converted string in a buffer and returns the address of the buffer. If possible, `gcvt` produces ndigit significant digits in F-format, or if not possible, in E-format. Trailing zeros are suppressed.

> The `ecvt` , `fcvt` , and `gcvt` functions represent the following special values specified in the IEEE Standard for floating-point arithmetic:

> Value | Representation
> --- | ---
> Quiet NaN | NaNQ
> Signalling NaN | NaNS
> +Infinity | Infinity
> --Infinity | --Infinity

> The sign associated with each of these values is stored into the sign argument. In IEEE floating-point representation, a value of 0 (zero) can be positive or negative, as set by the sign argument.

> See also `fcvt` and `ecvt` in this section.

## Return Value

> x | The address of the buffer.

# getc

> The `getc` macro returns the next character from a specified file.

## Format

> #include <stdio.h>

> int getc (FILE *file_ptr);

## Argument

> ### file_ptr

> A pointer to the file to be accessed.

## Description

> Since `getc` is a macro, a file pointer argument with side effects (for example, `getc (*f++)` ) might be evaluated incorrectly. In such a case, use the `fgetc` function instead. See the `fgetc` function in this section.

## Return Values

> n | The returned character.
> EOF | Indicates the end-of-file or an error.

# [w]getch

> Get a character from the terminal screen and echo it on the specified window. The `getch` function echos the character on stdscr.

## Format

> #include <curses.h>

> char getch();

> char wgetch (WINDOW *win);

## Argument

> ### win

> A pointer to the window.

## Description

> The `getch` and `wgetch` functions refresh the specified window before fetching a character. For more information, see the `scrollok` function in this section.

## Return Values

> x | The returned character.
> ERR | Indicates that the function makes the screen scroll illegally.

# getchar

> Reads a single character from the standard input (stdin).

## Format

> #include <stdio.h>

> int getchar (void);

## Description

> The `getchar` function is identical to `fgetc` (stdin).

## Return Values

> x | The next character from stdin, converted to `int` .
> EOF | Indicates the end-of-file or an error.

# getclock

> Gets the current value of the system-wide clock.

## Format

> #include <timers.h>

> int getclock (int clktyp, struct timespec *tp);

## Arguments

> ### clktyp

> The type of system-wide clock.

> ### tp

> Pointer to a `timespec` structure space where the current value of the system-wide clock is stored.

## Description

> This function sets the current value of the clock specified by clktyp into the location pointed to by tp.

> The clktyp argument is given as a symbolic constant name, as defined in the `<timers.h>` header file. Only the `TIMEOFDAY` symbolic constant, which specifies the normal time-of-day clock to access for system-wide time, is supported.

> For the clock specified by `TIMEOFDAY` , the value returned by this function is the elapsed time since the Epoch. The Epoch is referenced to 00:00:00 UTC (Coordinated Universal Time) 1 Jan 1970.

> The `getclock` function returns a `timespec` structure, which is defined in the `<timers.h>` header file as follows:

>      struct  timespec {

>        unsigned long  tv_sec   /* Elapsed time in seconds since the Epoch*/
>        long           tv_nsec  /* Elapsed time as a fraction of a second */
>                                /* since the Epoch (expressed in nanoseconds */

>      };

## Return Values

> 0 | Indicates success.
> --1 | Indicates an error; `errno` is set to one of the following values: EINVAL -- The clktyp argument does not specify a known system-wide clock. Or, the value of SYS$TIMEZONE_DIFFERENTIAL logical is wrong. EIO -- An error occurred when the system-wide clock specified by the clktyp argument was accessed.

# getcwd

> Returns a pointer to the file specification for the current working directory.

## Format

> #include <unistd.h>

> char *getcwd (char *buffer, size_t size); (ISO POSIX-1)

> char *getcwd (char *buffer, unsigned int size, ...); (DEC C EXTENSION)

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

> ### buffer

> Pointer to a character string large enough to hold the directory specification.

> If buffer is a NULL pointer, `getcwd` obtains size bytes of space using `malloc` . In this case, you can use the pointer returned by `getcwd` as the argument in a subsequent call to `free` .

> ### size

> The length of the directory specification to be returned.

> ### ...

> An optional argument that can be either 1 or 0. If you specify 1, the `getcwd` function returns the directory specification in OpenVMS format. If you specify 0, `getcwd` returns the directory specification (path name) in UNIX style format. If you do not specify this argument, `getcwd` returns the file name according to your current command-language interpreter. For more information about UNIX style directory specifications, see Section 1.4.3.

## Return Values

> x | A pointer to the file specification.
> NULL | Indicates an error.

# getdtablesize

> Gets the total number of file descriptors that a process can have open simultaneously.

## Format

> #include <unistd.h>

> int getdtablesize (void);

## Description

> This function returns the total number of file descriptors that a process can have open simultaneously. Each process is limited to a fixed number of open file descriptors.

> The number of file descriptors that a process can have open is the minumum of the following:

> - Compaq C RTL open file limit---65535 on OpenVMS Alpha; 2048 on OpenVMS VAX.
> - SYSGEN CHANNELCNT parameter---permanent I/O channel count.
> - Process open file quota FILLM parameter---number of open files that can be opened by a process at one time.

## Return Values

> x | The number of file descriptors that a process can have open simultaneously.
> --1 | Indicates an error.

# getegid

> Returns, in OpenVMS terms, the group number from the user identification code (UIC). For example, if the UIC is [313,031], 313 is the group number.

## Format

> #include <unistd.h>

> gid_t getegid (void);

## Description

> In Compaq C for OpenVMS Systems, the `getgid` and `getegid` functions both return the group number from the current UIC. See also `geteuid` and `getuid` in this section.

> Note (ALPHA ONLY) On OpenVMS Alpha systems, this function has been enhanced to take advantage of the new OpenVMS support for POSIX-style user, group, and session IDs available on a version of OpenVMS Alpha after Version 7.3. The new functionality, based on PERSONA VMS services, is the default on those versions of OpenVMS Alpha where the underlying operating system support is available. To request the old behavior, define the DECC$GETJPI_BASED_UID logical name to "ENABLE":
>     $ DEFINE DECC$GETJPI_BASED_UID ENABLE

## Return Value

> x | The group number from the UIC.

# getenv

> Searches the environment array for the current process and returns the value associated with a specified environment name.

## Format

> #include <stdlib.h>

> char *getenv (const char *name);

## Argument

> ### name

> One of the following values:
> - HOME---Your login directory
> - TERM---The type of terminal being used
> - PATH--The default device and directory
> - USER---The name of the user who initiated the process
> - Logical name or CLI symbolic name
> - An environment variable set with `setenv` or `putenv` .
>   The case of the specified name is important.

## Description

> In certain situations, this function attempts to perform a logical name translation on the user-specified argument:
> 1. If the argument to `getenv` does not match any of the environment strings present in your environment array, `getenv` attempts to translate your argument as a logical name by searching the logical name tables indicated by the LNM$FILE_DEV logical, as is done for file processing.
>    `getenv` first does a case-sensitive lookup. If that fails, it does a case-insensitive lookup. In most instances, logical names are defined in uppercase, but `getenv` can also find logical names that include lowercase letters.
>    `getenv` does not perform iterative logical name translation.
> 2. If no logical name exists, `getenv` attempts to translate the argument string as a command-language interpreter (CLI) symbol. If it succeeds, it returns the translated symbol text. If it fails, the return value is NULL.
>    `getenv` does not perform iterative CLI translation.

> If your CLI is the DEC/Shell, the function does not attempt a logical name translation since Shell environment symbols are implemented as DCL symbols.

> Note In OpenVMS Version 7.1, a cache of VMS environment variables (that is, logical names and DCL symbols) has been added to the `getenv` function to avoid the library making repeated calls to translate a logical name or to obtain the value of a DCL symbol. By default, the cache is disabled. If your application does not need to track changes in OpenVMS environment variables that can occur during its execution, the cache can be enabled by setting the DECC$ENABLE_GETENV_CACHE logical before invoking the application (any equivalence string).

## Return Values

> x | Pointer to an array containing the translated symbol. An equivalence name is returned at index zero.
> NULL | Indicates that the translation failed.

Previous | Next | Contents | Index

privacy and legal statement