[an error occurred while processing this directive]

HP OpenVMS Systems

C Programming Language

HP C

HP C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

geteuid

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.

Format

#include <unistd.h>
uid_t geteuid (void);

Description

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

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

getgid

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.

Format

#include <unistd.h>
gid_t getgid (void);

Description

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.7.
See also geteuid and getuid .

Return Value

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

getgrent (ALPHA, I64)

Gets a group database entry.

Format

#include <grp.h>
struct group *getgrent (void);

Description

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 .

Return Values

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

getgrgid (ALPHA, I64)

Gets a group database entry for a group ID.

Format

#include <types.h>
#include <grp.h>
struct group *getgrgid (gid_t gid);

Argument

gid
The group ID of the group for which the group database entry is to be retrieved.

Description

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.

Return Values

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 caught 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 wishing to check for error situations should set errno to 0 before calling getgrgid . If errno is set on return, an error occurred.

getgrgid_r (ALPHA, I64)

Gets a group database entry for a group ID.

Format

#include <types.h>
#include <grp.h>
int getgrgid_r (gid_t gid, struct group *grp, char *buffer, size_t bufsize, struct group **result);

Arguments

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.

Description

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.

Return Values

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

getgrnam (ALPHA, I64)

Gets a group database entry for a name.

Format

#include <types.h>
#include <grp.h>
struct group *getgrnam (const char *name);

Argument

name
The group name of the group for which the group database entry is to be retrieved.

Description

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.

Return Values

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

getgrnam_r (ALPHA, I64)

Gets a group database entry for a name.

Format

#include <types.h>
#include <grp.h>
int getgrnam_r (const char *name, struct group *grp, char *buffer, size_t bufsize, struct group **result);

Arguments

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.

Description

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.

Return Values

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

getitimer

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

Description

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.

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

getlogin

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.

getname

Returns the file specification associated with a file descriptor.

Format

#include <unixio.h>
char *getname (int file_desc, char *buffer, ...);

Function Variants The getname function has variants named _getname32 and _getname64 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

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 omit 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

The getname 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.

getopt

A command-line parser that can be used by applications that follow UNIX command-line conventions.

Format

#include <unistd.h> (X/OPEN, POSIX-1)
#include <stdio.h> (X/OPEN, POSIX-2)
int getopt (int argc, char * const argv[], const char *optstring);
extern char *optarg;
extern int optind, opterr, optopt;

Arguments

argc
The argument count as passed to main .
argv
The argument array as passed to main .
optstring
A string of recognized option characters. If a character is followed by a colon, the option takes an argument.

Description

The variable optind is the index of the next element of the argv vector to be processed. It is initialized to 1 by the system, and it is updated by getopt when it finishes with each element of argv. When an element of argv contains multiple option characters, it is unspecified how getopt determines which options have already been processed.
The getopt function returns the next option character (if one is found) from argv that matches a character in optstring, if there is one that matches. If the option takes an argument, getopt sets the variable optarg to point to the option-argument as follows:

If the option was the last character in the string pointed to by an element of argv, then optarg contains the next element of argv, and optind is incremented by 2. If the resulting value of optind is not less than argc, getopt returns an error, indicating a missing option-argument.
Otherwise, optarg points to the string following the option character in that element of argv, and optind is incremented by 1.

If one of the following is true, getopt returns - 1 without changing optind :
argv[ optind ] is a NULL pointer
*argv[ optind ] is not the character --
argv[ optind ] points to the string "--"

If argv[ optind ] points to the string "-- --" getopt returns - 1 after incrementing optind .
If getopt encounters an option character not contained in optstring, the question-mark character (?) is returned.
If getopt detects a missing argument, the colon character (:) is returned if the first character of optstring is a colon; otherwise, a question-mark character is returned.
In either of the previous two cases, getopt sets the variable optopt to the option character that caused the error. If the application has not set the variable opterr to 0 and the first character of optstring is not a colon, getopt also prints a diagnostic message to stderr .

Return Values

x The next option character specified on the command line.
A colon is returned if getopt detects a missing argument and the first character of optstring is a colon.
A question mark is returned if getopt encounters an option character not in optstring or detects a missing argument and the first character of optstring is not a colon.

- 1 When all command-line options are parsed.

Example

The following example shows how you might process the arguments for a utility that can take the mutually exclusive options a and b and the options f and o, both of which require arguments:

#include <unistd.h> 
 
int main (int argc, char *argv[ ]) 
{ 
         int c; 
         int bflg, aflg, errflg; 
         char *ifile; 
         char *ofile; 
         extern char *optarg; 
         extern int optind, optopt; 
         . 
         . 
         . 
         while ((c = getopt(argc, argv, ":abf:o:)) != -1) {    
 
                switch (c) { 
                case 'a': 
                        if (bflg)  
                                errflg++; 
                        else  
                                aflg++; 
                        break; 
                case 'b': 
                        if (aflg)  
                               errflg++; 
                        else { 
                               bflg++; 
                               bproc(); 
                        }           
 
                        break; 
                case 'f': 
                        ifile = optarg; 
                        break; 
                case 'o': 
                        ofile = optarg; 
                        break; 
                case ':':      /* -f or -o without operand */ 
                        fprintf (stderr, 
                         "Option -%c requires an operand\n"' optopt); 
                        errflg++; 
                        break; 
                case '?': 
                        fprintf (stderr, 
                                "Unrecognized option -%c\n"' optopt); 
                        errflg++; 
                }   
         }               
         if (errflg) { 
                fprintf (stderr, "usage: ..."); 
                exit(2); 
         } 
         for ( ; optind < argc; optind++)  { 
                if (access(argv[optind], R_OK)) { 
         . 
         . 
         . 
}

This sample code accepts any of the following as equivalent:

cmd -ao arg path path 
cmd -a -o arg path path 
cmd -o arg -a path path 
cmd -a -o arg -- path path 
cmd -a -oarg path path 
cmd -aoarg path path

Contents

Index

HP OpenVMS Systems

HP CRun-Time Library Reference Manual for OpenVMS Systems

geteuid

Format

Description

Return Value

getgid

Format

Description

Return Value

getgrent (ALPHA, I64)

Format

Description

Return Values

getgrgid (ALPHA, I64)

Format

Argument

gid

Description

Return Values

getgrgid_r (ALPHA, I64)

Format

Arguments

gid

grp

buffer

bufsize

result

Description

Return Values

getgrnam (ALPHA, I64)

Format

Argument

name

Description

Return Values

getgrnam_r (ALPHA, I64)

Format

Arguments

name

grp

buffer

bufsize

result

Description

Return Values

getitimer

Format

Arguments

which

value

Description

Return Values

getlogin

Format

Description

Return Values

getname

Format

Arguments

file_desc

buffer

...

Description

Return Values

getopt

Format

Arguments

argc

argv

optstring

Description

Return Values

Example

HP C
Run-Time Library Reference Manual for OpenVMS Systems