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.

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.

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.

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

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, ...); (COMPAQ C EXTENSION)

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.

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.

With POSIX IDs disabled, equivalent to getgid and returns the group number from the user identification code (UIC).

With POSIX IDs enabled, returns the effective group ID.

Format

#include <unistd.h>

gid_t getegid (void);

Description

This function can be used with POSIX-style identifiers or with UIC-based identifiers.

Note Currently, POSIX-style IDs are supported only by some OpenVMS versions done for specific government agencies, but will be integrated into future OpenVMS releases. OpenVMS Version 7.3-1 does not support POSIX-style IDs, but it does support 32-bit identifiers.

With POSIX-style IDs disabled (the default), the getegid and getgid functions are equivalent and return the group number from the current UIC. For example, if the UIC is [313,031], 313 is the group number.

With POSIX-style IDs enabled, getegid returns the effective group ID of the calling process, and getgid returns the real group ID of the calling process. The real group ID is specified at login time. The effective group ID is more transient, and determines additional access permission during execution of a set-group-ID process. It is for such processes that the getgid function is most useful.

See also geteuid and getuid in this section.

Return Value

x	The effective group ID (POSIX IDs enabled), or the group number from the UIC (POSIX IDs disabled).

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 the logical name is a search list with multiple equivalence values, the returned value points to the first equivalence value. For example:

   $ DEFINE A B,C ptr = getenv("A");

   
   A returns a pointer to " B ".

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

With POSIX IDs disabled, equivalent to getuid and returns the member number (in OpenVMS terms) from the user identification code (UIC).

With POSIX IDs enabled, returns the effective user ID.

Format

#include <unistd.h>

uid_t geteuid (void);

Description

This function can be used with POSIX-style identifiers or with UIC-based identifiers.

Note Currently, POSIX-style IDs are supported only by some OpenVMS versions done for specific government agencies, but will be integrated into future OpenVMS releases. OpenVMS Version 7.3-1 does not support POSIX-style IDs, but it does support 32-bit identifiers.

With POSIX-style IDs disabled (the default), the geteuid and getuid functions are equivalent and return the member number from the current UIC as follows:

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

With POSIX-style IDs enabled, geteuid returns the effective user ID of the calling process, and getuid returns the real user ID of the calling process.

See also getegid and getgid in this section.

Return Value

x	The effective user ID (POSIX IDs enabled), or the member number from the current UIC or the full UIC (POSIX IDs disabled).

With POSIX IDs disabled, equivalent to getegid and returns the group number from the user identification code (UIC).

With POSIX IDs enabled, returns the real group ID.

Format

#include <unistd.h>

gid_t getgid (void);

Description

This function can be used with POSIX-style identifiers or with UIC-based identifiers.

Note Currently, POSIX-style IDs are supported only by some OpenVMS versions done for specific government agencies, but will be integrated into future OpenVMS releases. OpenVMS Version 7.3-1 does not support POSIX-style IDs, but it does support 32-bit identifiers.

With POSIX-style IDs disabled (the default), the getegid and getgid functions are equivalent and return the group number from the current UIC. For example, if the UIC is [313,031], 313 is the group number.

With POSIX-style IDs enabled, getegid returns the effective group ID of the calling process, and getgid returns the real group ID of the calling process. The real group ID is specified at login time. The effective group ID is more transient, and determines additional access permission during execution of a set-group-ID process. It is for such processes that the getgid function is most useful.

See also geteuid and getuid in this section.

Return Value

x	The real group ID (POSIX IDs enabled), or the group number from the current UIC (POSIX IDs disabled).

Returns the value of interval timers.

Format

#include <time.h>

int getitimer (int which, struct itimerval *value);

Arguments

which

The type of interval timer. The Compaq C RTL supports only ITIMER_REAL.

value

Pointer to an itimerval structure whose members specify a timer interval and the time left to the end of the interval.

Description

This function returns the current value for the timer specified by the which argument in the structure pointed to by value .

A timer value is defined by the itimerval structure:

struct itimerval { struct timeval it_interval; struct timeval it_value; };

The following table lists the values for the itimerval structure members:

itimerval Member Value	Meaning
it_interval = 0	Disables a timer after its next expiration Assumes it_value is nonzero.
it_interval = nonzero	Specifies a value used in reloading it_value when the timer expires.
it_value = 0	Disables a timer.
it_value = nonzero	Indicates the time to the next timer expiration.

Time values smaller than the resolution of the system clock are rounded up to this resolution.

The Compaq C RTL provides each process with one interval timer, defined in the <time.h> header file as ITIMER_REAL. This timer decrements in real time and delivers a SIGALRM signal when the timer expires.

Return Values

0	Indicates success.
--1	Indicates an error; errno is set to EINVAL (The value argument specified a time that was too large to handle.)

Gets the login name.

Format

#include <unistd.h>

char *getlogin (void);

Description

The getlogin function returns the login name of the user associated with the current session.

Return Values

x	A pointer to a null-terminated string in a static buffer.
NULL	Indicates an error. Login name is not set.

Returns the file specification associated with a file descriptor.

Format

#include <unixio.h>

char *getname (int file_desc, char *buffer, ...);

Arguments

file_desc

A file descriptor.

buffer

A pointer to a character string that is large enough to hold the file specification.

...

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

Description

This function places the file specification into the area pointed to by buffer and returns that address. The area pointed to by buffer should be an array large enough to contain a fully qualified file specification (the maximum length is 256 characters).

Return Values

x	The address passed in the buffer argument.
0	Indicates an error.