United States

Compaq C

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

Previous | Contents | Index

# [w]getstr

> Get a string from the terminal screen, store it in the variable str, and echo it on the specified window. The `getstr` function works on the `stdscr` window.

## Format

> #include <curses.h>

> int getstr (char *str);

> int wgetstr (WINDOW *win, char *str);

## Arguments

> ### win

> A pointer to the window.

> ### str

> Must be large enough to hold the character string fetched from the window.

## Description

> The `getstr` and `wgetstr` functions refresh the specified window before fetching a string. The new-line terminator is stripped from the fetched string. For more information, see the `scrollok` function in this section.

## Return Values

> OK | Indicates success.
> ERR | Indicates that the function makes the screen scroll illegally.

# gettimeofday

> Gets date and time.

## Format

> #include <time.h>

> int gettimeofday (struct timeval *tp, void *tpz);

## Arguments

> ### tp

> Pointer to a `timeval` structure, defined in the `<time.h>` header file.

> ### tpz

> A NULL pointer. If this argument is not a NULL pointer, it is ignored.

## Description

> This function gets the current time (expressed as seconds and microseconds) since 00::00 Coordinated Universal Time, January 1, 1970. The current time is stored in the `timeval` structure pointed to by the tp argument.

> The tzp argument is intended to hold time-zone information set by the kernel. However, because the OpenVMS kernel does not set time-zone information, the tzp argument should be NULL. If it is not NULL, it is ignored. This function is supported for compatibility with BSD programs.

> If the value of the SYS$TIMEZONE_DIFFERENTIAL logical is wrong, the function fails with `errno` set to EINVAL.

## Return Values

> 0 | Indicates success.
> --1 | An error occurred. `errno` is set to indicate the error.

# getuid

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

## Format

> #include <unistd.h>

> uid_t getuid (void);

## Description

> In Compaq C for OpenVMS Systems, `getuid` and `geteuid` perform the same function.

> For programs compiled with the _VMS_V6_SOURCE feature-test macro or programs that do not include the `<unistd.h>` header file, the `getuid` and `geteuid` functions return the member number of the OpenVMS UIC. For example, if the UIC is [313,31], then the member number, 31, is returned.

> For programs compiled without the _VMS_V6_SOURCE feature-test macro that do include the `<unistd.h>` header file, the full UIC is returned. For example, if the UIC is [313, 31] then 20512799 (31 + 313 * 65536) is returned.

> 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 member number from the current UIC, or the full UIC. See description.

# getw

> Returns characters from a specified file.

## Format

> #include <stdio.h>

> int getw (FILE *file_ptr);

## Argument

> ### file_ptr

> A pointer to the file to be accessed.

## Description

> This function returns the next four characters from the specified input file as an `int` .

## Return Values

> x | The next four characters, in an `int` .
> EOF | Indicates that the end-of-file was encountered during the retrieval of any of the four characters and all four characters were lost. Since EOF is an acceptable integer, use `feof` and `ferror` to check the success of the function.

# getwc

> Reads the next character from a specified file, and converts it to a wide-character code.

## Format

> #include <wchar.h>

> wint_t getwc (FILE *file_ptr);

## Arguments

> ### file_ptr

> A pointer to the file to be accessed.

## Description

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

## Return Values

> n | The returned character.
> WEOF | Indicates the end-of-file or an error. If an error occurs, the function sets `errno` . For a list of the values set by this function, see `fgetwc` in this section.

# getwchar

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

## Format

> #include <wchar.h>

> wint_t getwchar (void);

## Description

> The `getwchar` function is identical to `fgetwc(stdin)` .

## Return Values

> x | The next character from stdin, converted to `wint_t` .
> WEOF | Indicates the end-of-file or an error. If an error occurs, the function sets `errno` . For a list of the values set by this function, see `fgetwc` in this section.

# getyx

> Puts the (y,x) coordinates of the current cursor position on win in the variables y and x.

## Format

> #include <curses.h>

> getyx (WINDOW *win, int y, int x);

## Arguments

> ### win

> Must be a pointer to the window.

> ### y

> Must be a valid lvalue.

> ### x

> Must be a valid lvalue.

# gmtime, gmtime_r

> Converts time units to the broken-down UTC time.

## Format

> #include <time.h>

> struct tm *gmtime (const time_t *timer);

> struct tm *gmtime_r (const time_t *timer, struct tm *result); (ISO POSIX-1)

Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to this function that is equivalent to the behavior before OpenVMS Version 7.0.

## Arguments

> ### timer

> Points to a variable that specifies a time value in seconds since the Epoch.

> ### result

> A pointer to a `tm` structure where the result is stored.

> The `tm` structure is defined in the `<time.h>` header, and is also shown in Table REF-4 in the description of `localtime` .

## Description

> The `gmtime` and `gmtime_r` functions convert the time (in seconds since the Epoch) pointed to by timer into a broken-down time, expressed as Coordinated Universal Time (UTC), and store it in a `tm` structure.

> The difference between the `gmtime_r` and `gmtime` functions is that the former puts the result into a user-specified `tm` structure where the result is stored. The latter puts the result into thread-specific static memory allocated by the Compaq C RTL, and which is overwritten by subsequent calls to `gmtime` ; you must make a copy if you want to save it.

> On success, `gmtime` returns a pointer to the `tm` structure; `gmtime_r` returns its second argument. On failure, these functions return the NULL pointer.

> Note Generally speaking, UTC-based time functions can affect in-memory time-zone information, which is process-wide data. However, if the system time zone remains the same during the execution of the application (which is the common case) and the cache of timezone files is enabled (which is the default), then the `_r` variant of the time functions `asctime_r` , `ctime_r` , `gmtime_r` and `localtime_r` , is both thread-safe and AST-reentrant. If, however, the system time zone can change during the execution of the application or the cache of timezone files is not enabled, then both variants of the UTC-based time functions belong to the third class of functions, which are neither thread-safe nor AST-reentrant.

## Return Values

> x | Pointer to a `tm` structure.
> NULL | Indicates an error; `errno` is set to one of the following values: EINVAL -- The timer argument is NULL.

# gsignal

> Generates a specified software signal, which invokes the action routine established by a `signal` , `ssignal` , or `sigvec` function.

## Format

> #include <signal.h>

> int gsignal (int sig [, int sigcode]);

## Arguments

> ### sig

> The signal to be generated.

> ### sigcode

> An optional signal code. 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, but 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 `gsignal` specifies a sig argument that is outside the range defined in the `<signal.h>` header file, then `gsignal` returns 0 and sets `errno` to EINVAL.
> - If `signal` , `ssignal` , or `sigvec` establishes SIG_DFL (default action) for the signal, then `gsignal` does 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 `gsignal` returns its argument, sig.
> - `signal` , `ssignal` , or `sigvec` must be used to establish an action routine for the signal. That function is called and its return value is returned by `gsignal` .

> See also `raise` , `signal` , `ssignal` , and `sigvec` in this section.

> See Chapter 4 for more information.

## Return Values

> 0 | Indicates a sig argument that is outside the range defined in the `<signal.h>` header file; `errno` is set to EINVAL.
> sig | Indicates that SIG_IGN (ignore signal) has been established as the action for the signal.
> x | Indicates that `signal` , `ssignal` , or `sigvec` has established an action function for the signal. That function is called, and its return value is returned by `gsignal` .

# hypot

> Returns the square root of the sum of the squares of two arguments:

> `sqrt(x2 + y2)`

## Format

> #include <math.h>

> double hypot (double x, double y);

## Arguments

> ### x

> A real value.

> ### y

> A real value.

## Description

> On overflow, the return value is undefined.

# iconv

> Converts characters coded in one codeset to characters coded in another codeset.

## Format

> #include <iconv.h>

> size_t iconv (iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);

## Arguments

> ### cd

> A conversion descriptor. This is returned by a successful call to `iconv_open` .

> ### inbuf

> A pointer to a variable that points to the first character in the input buffer.

> ### inbytesleft

> Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the input buffer (inbuf). When the conversion is completed, the variable indicates the number of bytes in inbuf not converted.

> ### outbuf

> A pointer to a variable that points to the first available byte in the output buffer. The output buffer contains the converted characters.

> ### outbytesleft

> Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the output buffer (outbuf). When the conversion is completed, the variable indicates the number of bytes left in outbuf.

## Description

> This function converts characters in the buffer pointed to by inbuf to characters in another code set. The resulting characters are stored in the buffer pointed to by outbuf. The conversion type is specified by the conversion descriptor cd. This descriptor is returned from a successful call to `iconv_open` .

> If an invalid character is found in the input buffer, the conversion stops after the last successful conversion. The variable pointed to by inbytesleft is updated to reflect the number of bytes in the input buffer that are not converted. The variable pointed to by outbytesleft is updated to reflect the number of bytes remaining in the output buffer.

## Return Values

> x | Number of non-identical conversions performed. Indicates successful conversion. In most cases 0 is returned.
> ( `size_t` ) --1 | Indicates an error condition. The function sets `errno` to one of the following: EBADF -- The cd argument is not a valid conversion descriptor. EILSEQ -- The conversion stops when an invalid character detected. E2BIG -- The conversion stops because of insufficient space in the output buffer. EINVAL -- The conversion stops because of an incomplete character at the end of the input buffer.

# iconv_close

> Deallocates a specified conversion descriptor and the resources allocated to the descriptor.

## Format

> #include <iconv.h>

> int iconv_close (iconv_t cd);

## Arguments

> ### cd

> The conversion descriptor to be deallocated. A conversion descriptor is returned by a successful call to `iconv_open` .

## Return Values

> 0 | Indicates that the conversion descriptor was successfully deallocated.
> --1 | Indicates an error occurred. The function sets `errno` to one of the following: EBADF -- The cd argument is not a valid conversion descriptor. EVMSERR -- Non-translatable VMS error occur. `vaxc$errno` contains the VMS error code.

# iconv_open

> Allocates a conversion descriptor for a specified codeset conversion.

## Format

> #include <iconv.h>

> iconv_t iconv_open (const char *tocode, const char *fromcode);

## Arguments

> ### tocode

> The name of the codeset to which characters are converted.

> ### fromcode

> The name of the source codeset. See Chapter 10 for information on obtaining a list of currently available codesets or for details on adding new codesets.

## Return Values

> x | A conversion descriptor. Indicates the call was successful. This descriptor is used in subsequent calls to `iconv`
> (iconv_t) --1 | Indicates an error occurred. The function sets `errno` to one of the following: EMFILE -- The process does not have enough I/O channels to open a file. ENOMEM -- Insufficient space is available. EINVAL -- The conversion specified by fromcode and tocode is not supported. EVMSERR -- Nontranslatable VMS error occur. `vaxc$errno` contains the VMS error code. A value of SS$_BADCHKSUM in `vaxc$errno` indicates that a conversion table file was found, but its contents is corrupted. A value of SS$_IDMISMATCH in `vaxc$errno` indicates that the conversion table file version does not match the version of the C Run-Time Library.

## Example

>     #include <stdio.h>
>     #include <iconv.h>
>     #include <errno.h>

>     int main()
>     {
>         /* Declare variables to be used                      */

>         char fromcodeset[30];
>         char tocodeset[30];
>         int iconv_opened;
>         iconv_t iconv_struct;       /* Iconv descriptor      */

>         /* Initialize variables                              */

>         sprintf(fromcodeset, "DECHANYU");
>         sprintf(tocodeset, "EUCTW");
>         iconv_opened = FALSE;

>         /* Attempt to create a conversion descriptor for the */
>         /* codesets specified. If the return value from      */
>         /* iconv_open is -1 then an error has occurred.      */
>         /*  Check the value of errno.                        */

>         if ((iconv_struct = iconv_open(tocodeset, fromcodeset))
>            == (iconv_t) - 1) {

>             /* Check the value of errno                      */

>             switch (errno) {
>             case EMFILE:
>             case ENFILE:
>                 printf("Too many iconv conversion files open\n");
>                 break;

>             case ENOMEM:
>                 printf("Not enough memory\n");
>                 break;

>             case EINVAL:
>                 printf("Unsupported conversion\n");
>                 break;

>             default:
>                 printf("Unexpected error from iconv_open\n");
>                 break;
>            }
>         }
>         else

>             /* Successfully allocated a conversion descriptor   */

>             iconv_opened = TRUE;

>         /*  Was a conversion descriptor allocated               */

>         if (iconv_opened) {

>             /* Attempt to deallocate the conversion descriptor. */
>             /* If iconv_close returns -1 then an error has      */
>             /* occurred.                                        */

>             if (iconv_close(iconv_struct) == -1) {

>                 /* An error occurred. Check the value of errno  */

>                 switch (errno) {
>                 case EBADF:
>                     printf("Conversion descriptor is invalid\n");
>                     break;
>                 default:
>                     printf("Unexpected error from iconv_close\n");
>                     break;
>                 }
>             }
>         }
>         return (EXIT_FAILURE);
>     }

Previous | Next | Contents | Index

privacy and legal statement