|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
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 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.
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 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.
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 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.
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 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.
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.)
Gets the login name.
#include <unistd.h>char *getlogin (void);
The getlogin function returns the login name of the user associated with the current session.
x A pointer to a null-terminated string in a static buffer. NULL Indicates an error. Login name is not set.
Returns the file specification associated with a file descriptor.
#include <unixio.h>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.char *getname (int file_desc, char *buffer, ...);
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.
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).
x The address passed in the buffer argument. 0 Indicates an error.
A command-line parser that can be used by applications that follow UNIX command-line conventions.
#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;
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.
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 .
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.
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
Gets the system page size.
#include <unistd.h>int getpagesize (void);
The getpagesize function returns the number of bytes in a page. The system page size is useful for specifying arguments to memory management system calls.The page size is a system page size and is not necessarily the same as the underlying hardware page size.
x Always indicates success. Returns the number of bytes in a page.
Gets the process group ID for a process.
#include <unistd.h>pid_t getpgid (pid_t pid);
pid
The process ID for which the group ID is being requested.
The getpgid function returns the process group ID of the process specified by pid. If pid is 0, the getpgid function returns the process group ID of the calling process.
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 that process from the calling process.
- ESRCH -- There is no process with a process ID of pid.
- EINVAL -- The value of pid is invalid.
| Previous | Next | Contents | Index |