[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP C
Run-Time Library Reference Manual for OpenVMS Systems


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

getgroups

Gets the current supplementary group IDs of the calling process.

Format

#include <unistd.h>

int getgroups (int gidsetsize, gid_t grouplist[]);


Arguments

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.

Description

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 .


Return Value

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.

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

int *getlogin_r (char *name, size_t namesize);


Description

The getlogin function returns the login name of the user associated with the current session. If getlogin returns a non-null pointer, then that pointer points to the name that the user logged in under, even if there are several login names with the same user ID.

The getlogin_r function is the reentrant version of getlogin . Upon successful completion, getlogin_r returns 0 and puts the name associated by the login activity with the controlling terminal of the current process in the character array pointed to by name. The array is namesize characters long and should have space for the name and the terminating null character. The maximum size of the login name is LOGIN_NAME_MAX.

If getlogin_r is successful, name points to the name the user used at login, even if there are several login names with the same user ID.


Return Values

x Upon successful completion, getlogin returns a pointer to a null-terminated string in a static buffer.
0 Indicates successful completion of getlogin_r .
NULL Indicates an error; errno is 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.


Previous Next Contents Index