|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
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.
#include <curses.h>int getstr (char *str);
int wgetstr (WINDOW *win, char *str);
win
A pointer to the window.str
Must be large enough to hold the character string fetched from the window.
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.
OK Indicates success. ERR Indicates that the function makes the screen scroll illegally.
Gets the date and time.
#include <time.h>int gettimeofday (struct timeval *tp, void *tzp);
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.
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.
0 Indicates success. - 1 An error occurred. errno is set to indicate the error.
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.
#include <unistd.h>uid_t getuid (void);
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:
- 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.
To enable/disable POSIX style IDs, see Section 1.7.
See also getegid and getgid .
x The real user ID (POSIX IDs enabled), or the member number from the current UIC or the full UIC (POSIX IDs disabled).
Returns characters from a specified file.
#include <stdio.h>int getw (FILE *file_ptr);
file_ptr
A pointer to the file to be accessed.
The getw function returns the next four characters from the specified input file as an int .
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.
Reads the next character from a specified file, and converts it to a wide-character code.
#include <wchar.h>wint_t getwc (FILE *file_ptr);
file_ptr
A pointer to the file to be accessed.
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.
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 .
Reads a single wide character from the standard input ( stdin ).
#include <wchar.h>wint_t getwchar (void);
The getwchar function is identical to fgetwc ( stdin ).
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 .
Puts the (y,x) coordinates of the current cursor position on win in the variables y and x.
#include <curses.h>getyx (WINDOW *win, int y, int x);
win
Must be a pointer to the window.y
Must be a valid lvalue.x
Must be a valid lvalue.
Returns a list of existing files for a user supplied pathname (with optional wildcards).
#include <glob.h>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.int glob (const char *pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);
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.
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):
- The DECC$GLOB_UNIX_STYLE is enabled.
- The DECC$FILENAME_UNIX_ONLY feature logical is enabled.
- The glob function checks the specified pattern for pathname indications, such as directory delimiters, and determines it to be a UNIX style pathname.
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:
- OpenVMS mode outputs full file specifications, not relative ones, as in UNIX mode.
- The GLOB_MARK flag is ignored in OpenVMS mode because it is not meaningful to append a slash (/) to a directory on OpenVMS.
For example:
Sample pattern input Sample output [.SUBDIR1]A.TXT DEV:[DIR.SUBDIR1]A.TXT;1 [.SUB*]%.* DEV:[DIR.SUBDIR1]A.TXT;1UNIX mode
You can enable this mode explicitly with:
$ DEFINE DECC$GLOB_UNIX_STYLE ENABLEUNIX 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] cStandard 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:
- If the application sets the GLOB_DOOFFS flag in the first call to the glob function, then it is also set in the second call, and the value of the gl_offs field of the pglob argument is not modified between the calls.
- If the application did not set the GLOB_DOOFFS flag in the first call to the glob function, then it is not set in the second call.
- After the second call, pglob-> gl_pathv points to a list containing the following:
- Zero or more NULLs, as specified by the GLOB_DOOFFS flag and pglob-> gl_offs .
- Pointers to the pathnames that were in the pglob-> gl_pathv list before the call, in the same order as after the first call to the glob function.
- Pointers to the new pathnames generated by the second call, in the specified order.
- The count returned in the pglob-> gl_offs argument is the total number of pathnames from the two calls.
- The application should not modify the pglob-> gl_pathc or pglob-> gl_pathv fields between the two calls.
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 , fnmatch , readdir , and stat ,
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.
Frees any space associated with the pglob argument resulting from a previous call to the glob function.
#include <glob.h>Function Variants The globfree function has variants named _globfree32 and _globfree64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.void globfree (glob_t *pglob);
pglob
Pointer to a previously allocated glob_t structure.
The globfree function frees any space associated with the pglob argument resulting from a previous call to the glob function. The globfree function returns no value.
Converts time units to the broken-down UTC time.
#include <time.h>Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to the gmtime_r function that is equivalent to the behavior before OpenVMS Version 7.0.struct tm *gmtime (const time_t *timer);
struct tm *gmtime_r (const time_t *timer, struct tm *result); (ISO POSIX-1)
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 .
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 HP 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 processwide 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.
x Pointer to a tm structure. NULL Indicates an error; errno is set to the following value:
- EINVAL -- The timer argument is NULL.
| Previous | Next | Contents | Index |