HP C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

gets

Reads a line from the standard input ( stdin ).

Format

#include <stdio.h>

char *gets (char *str);

Function Variants The gets function has variants named _gets32 and _gets64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.

Argument

str

A pointer to a character string that is large enough to hold the information fetched from stdin .

Description

The new-line character (\n) that ends the line is replaced by the function with an ASCII null character (\0).

When stdin is opened in record mode, gets treats the end of a record the same as a new-line character and, therefore, reads up to and including a new-line character or to the end of the record.

Return Values

x A pointer to the str argument.
NULL Indicates that an error has occurred or that the end-of-file was encountered before a new-line character was encountered. The contents of str are undefined if a read error occurs.

getsid (ALPHA, I64)

Gets the process group ID of the session leader.

Format

#include <unistd.h>

pid_t getsid (pid_t pid);

Argument

pid

The process ID of the process whose session leader process group ID is being requested.

Description

The getsid function obtains the process group ID of the process that is the session leader of the process specified by pid. If pid is (pid_t)0, it specifies the calling process.

This function requires that long (32-bit) UID/GID support be enabled. See Section 1.5.8 for more information.

Return Values

x The process group ID of the session leader of the specified process.
(pid_t) - 1 Indicates an error. The function sets errno to one of the following values:
  • EPERM -- The process specified by pid is not in the same session as the calling process, and the implementation does not allow access to the process group ID of the session leader of that process from the calling process.
  • ESRCH -- There is no process with a process ID of pid.

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

Return Values

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

gettimeofday

Gets the date and time.

Format

#include <time.h>

int gettimeofday (struct timeval *tp, void *tzp);

Arguments

tp

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

tzp

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

Description

The gettimeofday 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

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

With POSIX IDs enabled, returns the real user ID.

Format

#include <unistd.h>

uid_t getuid (void);

Description

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

POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher.

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:

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.

To enable/disable POSIX style IDs, see Section 1.7.

See also getegid and getgid .

Return Value

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

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

The getw 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);

Argument

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.

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 .

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 .

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.

glob (ALPHA, I64)

Returns a list of existing files for a user supplied pathname (with optional wildcards).

Format

#include <glob.h>

int glob (const char *pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);

Function Variants The glob function has variants named _glob32 and _glob64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.

Arguments

pattern

The pattern string to match with accessible files and pathnames. This pattern can have wildcards.

flags

Controls the customizable behavior of the glob function.

errfunc

An optional function that, if specified, is called when the glob function detects an error condition, or if not specified, is NULL.

epath

First argument of the optional errfunc function, epath is the pathname that failed because a directory could not be opened or read.

eerrno

Second argument of the optional errfunc function, eerrno is the errno value from a failure specified by the epath argument as set by the opendir , readdir , or stat functions.

pglob

Pointer to a glob_t structure that returns the matching accessible existing filenames. The structure is allocated by the caller. The array of structures containing the located filenames that match the pattern argument are stored by the glob function into the structure. The last entry is a NULL pointer.

The structure type glob_t is defined in the <glob.h> header file and includes at least the following members: 


size_t   gl_pathc    //Count of paths matched by pattern.  
char **  gl_pathv    //Pointer to a list of matched pathnames.  
size_t   gl_offs     //Slots to reserve at the beginning of gl_pathv.

Description

The glob function constructs a list of accessible files that match the pattern argument.

The glob function operates in one of two modes: UNIX mode or OpenVMS mode.

You can select UNIX mode explicitly by enabling the feature logical DECC$GLOB_UNIX_STYLE, which is disabled by default.

The glob function defaults to OpenVMS mode unless one of the following conditions is met (in which case glob uses UNIX mode):

OpenVMS mode

This mode allows an OpenVMS programmer to give an OpenVMS style pattern to the glob function and get expected OpenVMS style output. The OpenVMS style pattern is what a user would expect from DCL commands or as input to the SYS$PARSE and SYS$SEARCH system routines.

In this mode, you can use any of the expected OpenVMS wildcards (see the OpenVMS documentation for additional information).

OpenVMS mode does not support the UNIX wildcard ?, or [] pattern matching. OpenVMS users expect [] to be available as directory delimiters.

Some additional behavior differences between OpenVMS mode and UNIX mode:

For example: 


Sample pattern input      Sample output 
 
[.SUBDIR1]A.TXT           DEV:[DIR.SUBDIR1]A.TXT;1 
[.SUB*]%.*                DEV:[DIR.SUBDIR1]A.TXT;1

UNIX mode

You can enable this mode explicitly with: 


$ DEFINE DECC$GLOB_UNIX_STYLE ENABLE

UNIX mode is also enabled if the DECC$FILENAME_UNIX_ONLY feature logical is set, or if the glob function determines that the specified pattern looks like a UNIX style pathname.

In UNIX mode, the glob function follows the X/Open specification where possible.

For example: 


Sample pattern input      Sample output 
 
./a/b/c                   ./a/b/c 
./?/b/*                   ./a/b/c 
[a-c]                     c

Standard Description

The glob function matches all accessible pathnames against this pattern and develops a list of all pathnames that match. To have access to a pathname, the glob function requires search permission on every component of a pathname except the last, and read permission on each directory of any filename component of the pattern argument.

The glob function stores the number of matched pathnames and a pointer to a list of pointers to pathnames in the pglob argument. The pathnames are sorted, based on the setting of the LC_COLLATE category in the current locale. The first pointer after the last pathname is NULL. If the pattern does not match any pathnames, the returned number of matched pathnames is 0.

It is the caller's responsibility to create the structure pointed to by the pglob argument. The glob function allocates other space as needed. The globfree function frees any space associated with the pglob argument as a result of a previous call to the glob function.

The flags argument is used to control the behavior of the glob function. The flags value is the bitwise inclusive OR (|) of any of the following constants, which are defined in the <glob.h> header file:
GLOB_APPEND Appends pathnames located with this call to any pathnames previously located.
GLOB_DOOFFS Uses the gl_offs structure to specify the number of NULL pointers to add to the beginning of the gl_pathv component of the pglob argument.
GLOB_ERR Causes the glob function to return when it encounters a directory that it cannot open or read. If the GLOB_ERR flag is not set, the glob function continues to find matches if it encounters a directory that it cannot open or read.
GLOB_MARK Specifies that each pathname that is a directory should have a slash (/) appended. GLOB_MARK is ignored in OpenVMS mode because it is not meaningful to append a slash to a directory on OpenVMS systems.
GLOB_NOCHECK If the pattern argument does not match any pathname, then the glob function returns a list consisting only of the pattern argument, and the number of matched pathnames is 1.
GLOB_NOESCAPE If the GLOB_NOESCAPE flag is set, a backslash (\) cannot be used to escape metacharacters.

The GLOB_APPEND flag can be used to append a new set of pathnames to those found in a previous call to the glob function. The following rules apply when two or more calls to the glob function are made with the same value of the pglob argument, and without intervening calls to the globfree function:

On successful completion, the glob function returns a value of 0 (zero). The pglob-> gl_pathc field returns the number of matched pathnames and the pglob-> gl_pathv field contains a pointer to a NULL-terminated list of matched and sorted pathnames. If the number of matched pathnames in the pglob-> gl_pathc argument is 0 (zero), the pointer in the pglob-> gl_pathv argument is undefined.

If the glob function terminates because of an error, the function returns one of the nonzero constants GLOB_ABORTED, GLOB_NOMATCH, or GLOB_NOSPACE, defined in the <glob.h> header file. In this case, the pglob argument values are still set as defined above.

If, during the search, a directory is encountered that cannot be opened or read and the errfunc argument value is not NULL, the glob function calls errfunc with the two arguments epath and eerno:

epath---The pathname that failed because a directory could not be opened or read.
eerno---The errno value from a failure specified by the epath argument as set by the opendir , readdir , or stat functions.

If errfunc is called and returns nonzero, or if the GLOB_ERR flag is set in flags, the glob function stops the scan and returns GLOB_ABORTED after setting the pglob argument to reflect the pathnames already scanned. If GLOB_ERR is not set and either errfunc is NULL or errfunc returns zero, the error is ignored.

No errno values are returned.

See also globfree , readdir , and stat .

Return Values

0 Successful completion.
GLOB_ABORTED The scan was stopped because GLOB_ERROR was set or errfunc returned a nonzero value.
GLOB_NOMATCH The pattern does not match any existing pathname, and GLOB_NOCHECK was not set in flags.
GLOB_NOSPACE An attempt to allocate memory failed.

Previous Next Contents Index