|
HP OpenVMS Systems Documentation |
|
HP C
|
| Previous | Contents | Index |
Gets the login name.
#include <unistd.h>char *getlogin (void);
int *getlogin_r (char *name, size_t namesize);
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.
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.
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.9 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 filename according to your current command-language interpreter (CLI). For more information about UNIX style file specifications, see Section 1.3.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.This function requires that long (32-bit) UID/GID support be enabled. See Section 1.4.8 for more information.
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.
Gets the process group ID of the calling process.
#include <unistd.h>pid_t getpgrp (void);
The getpgrp function returns the process group ID of the calling process.The getpgrp function is always successful, and no return value is reserved to indicate an error.
This function requires that long (32-bit) UID/GID support be enabled. See Section 1.4.8 for more information.
x The process group ID of the calling process.
Returns the process ID of the current process.
#include <unistd.h>pid_t getpid (void);
x The process ID of the current process.
Returns the parent process ID of the calling process.
#include <unistd.h>pid_t getppid (void);
x The parent process ID. 0 Indicates that the calling process does not have a parent process.
Accesses user entry information in the user database, returning a pointer to a passwd structure.
#include <pwd.h>Function Variants The getpwent function has variants named __32_getpwent and __64_getpwent for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.struct passwd *getpwent (void);
The getpwent function returns a pointer to a structure containing fields whose values are derived from an entry in the user database. Entries in the database are accessed sequentially by getpwent . When first called, getpwent returns a pointer to a passwd structure containing the first entry in the user database. Thereafter, it returns a pointer to a passwd structure containing the next entry in the user database. Successive calls can be used to search the entire user database.The passwd structure is defined in the <pwd.h> header file as follows:
pw_name The name of the user. pw_uid The ID of the user. pw_gid The group ID of the principle group of the user. pw_dir The home directory of the user. pw_shell The initial program for the user. If an end-of-file or an error is encountered on reading, getpwent returns a NULL pointer.
Because getpwent accesses the user authorization file (SYSUAF) directly, the process must have appropriate privileges enabled or the function will fail.
Notes
All information generated by the getpwent function is stored in a per-thread static area and is overwritten on subsequent calls to the function.
Password file entries that are too long are ignored.
x Pointer to a passwd structure, if successful. NULL Indicates an end-of-file or error occurred. The function sets errno to one of the following values:
- EIO -- Indicates that an I/O error occurred or the user does not have appropriate privileges enabled to access the user authorization file (SYSUAF).
- 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.
The getpwnam function returns information about a user database entry for the specified name.The getpwnam_r function is a reentrant version of getpwnam .
#include <pwd.h>Function Variants The getpwnam and getpwnam_r functions have variants named __32_getpwnam , _getpwnam_r32 and __64_getpwnam , _getpwnam_r64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.struct passwd *getpwnam (const char *name); (ISO POSIX-1)
struct passwd *getpwnam (const char *name, ...); (HP C EXTENSION)
int getpwnam_r (const char *name, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result); (ISO POSIX-1), (INTEGRITY SERVERS, ALPHA)
int getpwnam_r (const char *name, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result, ...); (HP C EXTENSION), (INTEGRITY SERVERS, ALPHA)
name
The name of the user for which the attributes are to be read.pwd
The address of a passwd structure into which the function writes its results.buffer
A working buffer for the result argument that is able to hold the largest entry in the passwd structure. Storage referenced by the passwd structure is allocated from the memory provided with the buffer argument, which is bufsize characters in length.bufsize
The length of the character array that buffer points to.result
Upon successful return, is set to pwd. Upon unsuccessful return, the result is set to NULL....
An optional argument that can be either 1 or 0. If you specify 1, the directory specification is returned in OpenVMS format. If you specify 0, the directory specification (pathname) is returned in UNIX style format. If you omit this argument, the function returns the directory specification according to your current command-language interpreter. For more information about UNIX style directory specifications, see Section 1.3.3.
The getpwnam function searches the user database for an entry with the specified name. The function returns the first user entry in the database with the pw_name member of the passwd structure that matches the name argument.The passwd structure is defined in the <pwd.h> header file as follows:
pw_name The user's login name. pw_uid The numerical user ID. pw_gid The numerical group ID. pw_dir The home directory of the user. pw_shell The initial program for the user.
Note
All information generated by the getpwnam function is stored in a per-thread static area and is overwritten on subsequent calls to the function.The getpwnam_r function is the reentrant version of getpwnam . The getpwnam_r function updates the passwd structure pointed to by pwd and stores a pointer to that structure at the location pointed to by result. The structure will contain an entry from the user database that matches the specified name. Storage referenced by the structure is allocated from the memory provided with the buffer argument, which is bufsize characters in length. The maximum size needed for this buffer can be determined with the _SC_GETPW_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.
Applications wishing to check for error situations should set errno to 0 before calling getpwnam . If getpwnam returns a NULL pointer and errno is nonzero, an error occurred.
x getpwnam returns a pointer to a valid passwd structure, if a matching entry is found. NULL getpwnam returns NULL if an error occurred or a the specified entry was not found. errno is set to indicate the error. The getpwnam function may fail if:
- EIO -- An I/O error has occurred.
- EINTR -- A signal was intercepted during getpwnam .
- 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.
0 When successful, getpwnam_r returns 0 and stores a pointer to the updated passwd structure at the location pointed to by result. 0 When unsuccessful (on error or if the requested entry is not found), getpwnam_r returns 0 and stores a NULL pointer at the location pointed to by result. The getpwnam_r function may fail if:
- ERANGE -- Insufficient storage was supplied through buffer and bufsize to contain the data to be referenced by the resulting passwd structure.
When building a sample program with /def=_USE_STD_STAT, you can observe the following:
- When the DECC$POSIX_STYLE_UID logical is enabled:
- For a system, that supports POSIX style identifiers:
- getpwnam_r API reads information from the TCP/IP proxy database and fills UID and GID with values from the TCP/IP proxy database.
- getgrgid_r API returns gr_name and gr_mem from the right's database associated with GID returned by getpwnam_r API.- System with no support for POSIX style identifiers, getpwnam_r fills GID and UID with SYSGEN parameters as "DEFUID" and "DEFGID".
- When the DECC$POSIX_STYLE_UID logical is not defined:
getpwnam function returns information about a user database entry for the specified name, which is specified in SYSUAF.DAT
#include <unistd> // getuid() #include <pwd> // getpwuid_r() #include <grp> #include <errno.h> #include <stdio.h> #include <string.h> main() { struct passwd pwd2; const unsigned int PWD_BUFF_SIZE = 1024; const unsigned int GRP_BUFF_SIZE = 1024; struct passwd *p_passwd; struct passwd *result; struct group *grpresult; struct group grp; char pwdBuffer[PWD_BUFF_SIZE],*name; char grpBuffer[GRP_BUFF_SIZE]; char buf[PWD_BUFF_SIZE]; gid_t gid; uid_t uid; int status; p_passwd = getpwnam("user1"); uid=p_passwd->pw_uid; gid=p_passwd->pw_gid; printf("User id is %u\n", uid); printf("Group id is %u\n", gid); status = getpwnam_r("user1", &pwd2, pwdBuffer, PWD_BUFF_SIZE, &result); gid = pwd2.pw_gid; status = getgrgid_r(gid, &grp, grpBuffer, GRP_BUFF_SIZE, &grpresult); gid=grp.gr_gid; name=grp.gr_name; strcpy(name,grp.gr_name); printf("Group id is %u\n", gid); printf("Group name is %s\n", name); }Running the example program with /def=_USE_STD_STAT produces the following result:
- When the DECC$POSIX_STYLE_UID logical is NOT enabled, prints uid as 11010118 (result of 65536*168+ 70) and gid as 168 with group name as RTL.
- When the DECC$POSIX_STYLE_UID logical is enabled and POSIX style identifiers are supported, prints uid as 70, gid as 168 with group name as FOR_POSIX_TEST (retrieved from TCP/IP proxy database).
- When the DECC$POSIX_STYLE_UID logical is enabled, but POSIX style identifiers are not supported, prints uid as DEFUID, gid as DEFGID with group name as invalid buffer.
| Previous | Next | Contents | Index |