|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
Searches the environment array for the current process and returns the value associated with a specified environment name.
#include <stdlib.h>char *getenv (const char *name);
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 command-language interpreter (CLI) symbolic name
- An environment variable set with setenv or putenv
The case of the specified name is important.
In certain situations, the getenv function attempts to perform a logical name translation on the user-specified argument:
- 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.- 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 ".- If no logical name exists, getenv attempts to translate the argument string as a 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.
Notes
- In OpenVMS Version 7.1, a cache of OpenVMS environment variables (that is, logical names and DCL symbols) was 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 enabling the DECC$ENABLE_GETENV_CACHE logical before invoking the application.
- Do not use the setenv , getenv , and putenv functions to manipulate symbols and logicals. Instead use the OpenVMS library calls lib$set_logical , lib$get_logical , lib$set_symbol , and lib$get_symbol . The * env functions deliberately provide UNIX behavior, and are not a substitute for these OpenVMS runtime library calls.
OpenVMS DCL symbols, not logical names, are the closest analog to environment variables on UNIX systems. While getenv is a mechanism to retrieve either a logical name or a symbol, it maintains an internal cache of values for use with setenv and subsequent getenv calls. The setenv function does not write or create DCL symbols or OpenVMS logical names.
This is consistent with UNIX behavior. On UNIX systems, setenv does not change or create any symbols that will be visible in the shell after the program exits.
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, this function is equivalent to getuid and returns the member number (in OpenVMS terms) from the user identification code (UIC).With POSIX IDs enabled, this function returns the effective user ID.
#include <unistd.h>uid_t geteuid (void);
The geteuid function can be used with POSIX style identifiers (IDs) 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 in decimal after converting the octal representation to decimal. For example, if the UIC is [313, 31] then 13303833 is returned. (13303833 = 25 + 203 * 65536; Octal 31 = 25 decimal; Octal 313 = 203 decimal.)
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.6.
See also getegid and getgid .
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, this function is equivalent to getegid and returns the group number from the user identification code (UIC).With POSIX IDs enabled, this function returns the real group ID.
#include <unistd.h>gid_t getgid (void);
The getgid 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 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.
To enable/disable POSIX style IDs, see Section 1.6.
See also geteuid and getuid .
x The real group ID (POSIX IDs enabled), or the group number from the current UIC (POSIX IDs disabled).
Gets a group database entry.
#include <grp.h>struct group *getgrent (void);
The getgrent function returns the next group in the sequential search, returning a pointer to a structure containing the broken-out fields of an entry in the group database.When first called, getgrent returns a pointer to a group structure containing the first entry in the group database. Thereafter, it returns a pointer to the next group structure in the group database, so successive calls can be used to search the entire database.
If an end-of-file or an error is encountered on reading, getgrent returns a NULL pointer and sets errno .
x Pointer to a group structure, if successful. NULL Indicates that an error occurred. The function sets errno to one of the following values:
- EACCES -- The user process does not have appropriate privileges enabled to access the user authorization file.
- EINTR -- A signal was intercepted during the operation.
- EIO -- Indicates that an I/O error occurred.
- EMFILE -- OPEN_MAX file descriptors are currently open in the calling process.
- ENFILE -- The maximum allowable number of files is currently open in the system.
Gets a group database entry for a group ID.
#include <types.h>#include <grp.h>
struct group *getgrgid (gid_t gid);
gid
The group ID of the group for which the group database entry is to be retrieved.
The getgrgid function searches the group database for an entry with a matching gid and returns a pointer to the group structure containing the matching entry.
x Pointer to a valid group structure containing a matching entry. NULL An error occurred. Note: The return value points to a static area that is overwritten by subsequent calls to getgrent , getgrgid , or getgrnam .
On error, the function sets errno to one of the following values:
- EACCES -- The user process does not have appropriate privileges enabled to access the user authorization file.
- EIO -- An I/O error has occurred.
- EINTR -- A signal was intercepted during getgrgid .
- EMFILE -- OPEN_MAX file descriptors are currently open in the calling process.
- ENFILE -- The maximum allowable number of files is currently open in the system.
Applications checking for error situations must set errno to 0 before calling getgrgid . If errno is set on return, an error has occurred.
Gets a group database entry for a group ID.
#include <types.h>#include <grp.h>
int getgrgid_r (gid_t gid, struct group *grp, char *buffer, size_t bufsize, struct group **result);
gid
The group ID of the group for which the group database entry is to be retrieved.grp
Storage area to hold the retrieved group structure.buffer
The working buffer that is able to hold the longest group entry in the database.bufsize
The length, in characters, of buffer.result
Upon successful return, result points to the retrieved group structure.Upon unsuccessful return, result is set to NULL.
The getgrgid_r function updates the group structure pointed to by grp and stores a pointer to that structure at the location pointed to by result. The structure contains an entry from the group database with a matching gid. Storage referenced by the group structure is allocated from the memory provided with the buffer argument, which is bufsize characters in size. The maximum size needed for this buffer can be determined with the _SC_GETGR_R_SIZE_MAX parameter of the sysconf function. On error or if the requested entry is not found, a NULL pointer is returned at the location pointed to by result.
0 Successful completion. x On error, the function sets the return value to one of the following:
- EACCES -- The user process does not have appropriate privileges enabled to access the user authorization file.
- EIO -- An I/O error has occurred.
- EINTR -- A signal was intercepted during getgrgid .
- EMFILE -- OPEN_MAX file descriptors are currently open in the calling process.
- ENFILE -- The maximum allowable number of files is currently open in the system.
- ERANGE -- Insufficient storage was supplied through the buffer and bufsize arguments to contain the data to be referenced by the resulting group structure.
Gets a group database entry for a name.
#include <types.h>#include <grp.h>
struct group *getgrnam (const char *name);
name
The group name of the group for which the group database entry is to be retrieved.
The getgrnam function searches the group database for an entry with a matching name, and returns a pointer to the group structure containing the matching entry.
x Pointer to a valid group structure containing a matching entry. NULL Indicates an error. Note: The return value points to a static area which is overwritten by subsequent calls to getgrent , getgrgid , or getgrnam .
On error, the function sets the return value to one of the following:
- EACCES -- The user process does not have appropriate privileges enabled to access the user authorization file.
- EIO -- An I/O error has occurred.
- EINTR -- A signal was intercepted during getgrnam .
- EMFILE -- OPEN_MAX file descriptors are currently open in the calling process.
- ENFILE -- The maximum allowable number of files is currently open in the system.
Applications wishing to check for error situations should set errno to 0 before calling getgrnam . If errno is set on return, an error occurred.
Gets a group database entry for a name.
#include <types.h>#include <grp.h>
int getgrnam_r (const char *name, struct group *grp, char *buffer, size_t bufsize, struct group **result);
name
The group name of the group for which the group database entry is to be retrieved.grp
Storage area to hold the retrieved group structure.buffer
The working buffer that is able to hold the longest group entry in the database.bufsize
The length, in characters, of buffer.result
Upon successful return, result points to the retrieved group structure.Upon unsuccessful return, result is set to NULL.
The getgrnam_r function updates the group structure pointed to by grp and stores a pointer to that structure at the location pointed to by result. The structure contains an entry from the group database with a matching name. Storage referenced by the group structure is allocated from the memory provided with the buffer argument, which is bufsize characters in size. The maximum size needed for this buffer can be determined with the _SC_GETGR_R_SIZE_MAX parameter of the sysconf function. On error or if the requested entry is not found, a NULL pointer is returned at the location pointed to by result.
0 Successful completion. x On error, the function sets the return value to one of the following:
- EACCES -- The user process does not have appropriate privileges enabled to access the user authorization file.
- EIO -- An I/O error has occurred.
- EINTR -- A signal was intercepted during getgrnam .
- EMFILE -- OPEN_MAX file descriptors are currently open in the calling process.
- ENFILE -- The maximum allowable number of files is currently open in the system.
- ERANGE -- Insufficient storage was supplied through the buffer and bufsize arguments to contain the data to be referenced by the resulting group structure.
Gets the current supplementary group IDs of the calling process.
#include <unistd.h>int getgroups (int gidsetsize, gid_t grouplist[]);
gidsetsize
Indicates the number of entries that can be stored in the array pointed to by the grouplist parameter.grouplist
Points to the array in which the supplementary group IDs of the process are stored. The effective group ID of the process is not returned by the getgroups function if it is not also a supplementary group ID of the calling process.
The getgroups function gets the current supplementary group IDs of the calling process. The list is stored in the array pointed to by the grouplist parameter. The gidsetsize parameter indicates the number of entries that can be stored in this array.The getgroups function never returns more IDs than the value indicated by the sysconf parameter _SC_NGROUPS_MAX.
See also getgid and setsid .
n The number of elements stored in the array pointed to by the grouplist parameter. - 1 Indicates failure. errno might be set to one of the following values:
- EFAULT -- The gidsetsize and grouplist parameters specify an array that is partially or completely outside of the allocated address space of the process.
- EINVAL -- The gidsetsize parameter is nonzero and smaller than the number of supplementary group IDs.
Returns the value of interval timers.
#include <time.h>int getitimer (int which, struct itimerval *value);
which
The type of interval timer. The HP 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.
The getitimer 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 and 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 HP 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.
0 Indicates success. - 1 Indicates an error; errno is set to EINVAL (The value argument specified a time that was too large to handle.)
| Previous | Next | Contents | Index |