HP C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

getpwuid, getpwuid_r (INTEGRITY SERVERS, ALPHA)

The getpwuid function returns information about a user database entry for the specified uid.

The getpwuid_r function is a reentrant version of getpwuid .

Format

#include <pwd.h>

struct passwd *getpwuid (uid_t uid); (ISO POSIX-1)

struct passwd *getpwuid (uid_t uid, ...); (HP C EXTENSION)

int getpwuid_r (uid_t uid, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result); (ISO POSIX-1)

int getpwuid_r (uid_t uid, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result, ...); (HP C EXTENSION)

Function Variants The getpwuid and getpwuid_r functions have variants named __32_getpwuid , _getpwuid_r32 and __64_getpwuid , _getpwuid_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.

Arguments

uid

The user ID (UID) for which the attributes are to be read.

pwd

The location where the retrieved passwd structure is to be placed.

buffer

A working buffer for the result argument that is able to hold the 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 size.

bufsize

The length of the character array that buffer points to.

result

Upon successful return, result is set to pwd. Upon unsuccessful return, 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.

Description

The getpwuid function searches the user database for an entry with the specified uid. The function returns the first user entry in the database with a pw_uid member of the passwd structure that matches the uid 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 getpwuid function is stored in a per-thread static area and is overwritten on subsequent calls to the function.

The getpwuid_r function is the reentrant version of getpwuid . The getpwuid_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 with a matching uid. Storage referenced by the 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_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 getpwuid . If getpwuid returns a NULL pointer and errno is nonzero, an error occurred.

See also getuid to know how UIC is represented.

Return Values

x getpwuid returns a pointer to a valid passwd structure, if a matching entry is found.
NULL getpwuid returns NULL if an error occurred or a matching entry was not found. errno is set to indicate the error. The getpwuid 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, getpwuid_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), getpwuid_r returns 0 and stores a NULL pointer at the location pointed to by result. The getpwuid_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.

gets

Reads a line from the standard input ( stdin ).

Format

#include <stdio.h>

char *gets (char *str);

Function Variants The gets function has variants named _gets32 and _gets64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Argument

str

A pointer to a character string that is large enough to hold the information fetched from stdin .

Description

The new-line character (\n) that ends the line is replaced by the function with an ASCII null character (\0).

When stdin is opened in record mode, gets treats the end of a record the same as a new-line character and, therefore, reads up to and including a new-line character or to the end of the record.

Return Values

x A pointer to the str argument.
NULL Indicates that an error has occurred or that the end-of-file was encountered before a new-line character was encountered. The contents of str are undefined if a read error occurs.

getsid (INTEGRITY SERVERS, ALPHA)

Gets the process group ID of the session leader.

Format

#include <unistd.h>

pid_t getsid (pid_t pid);

Argument

pid

The process ID of the process whose session leader process group ID is being requested.

Description

The getsid function obtains the process group ID of the process that is the session leader of the process specified by pid. If pid is (pid_t)0, it specifies the calling process.

This function requires that long (32-bit) UID/GID support be enabled. See Section 1.4.8 for more information.

Return Values

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 the session leader of that process from the calling process.
  • ESRCH -- There is no process with a process ID of pid.

[w]getstr

Get a string from the terminal screen, store it in the variable str, and echo it on the specified window. The getstr function works on the stdscr window.

Format

#include <curses.h>

int getstr (char *str);

int wgetstr (WINDOW *win, char *str);

Arguments

win

A pointer to the window.

str

Must be large enough to hold the character string fetched from the window.

Description

The getstr and wgetstr functions refresh the specified window before fetching a string. The new-line terminator is stripped from the fetched string. For more information, see the scrollok function.

Return Values

OK Indicates success.
ERR Indicates that the function makes the screen scroll illegally.

gettimeofday

Gets the date and time.

Format

#include <time.h>

int gettimeofday (struct timeval *tp, void *tzp);

Arguments

tp

Pointer to a timeval structure, defined in the <time.h> header file.

tzp

A NULL pointer. If this argument is not a NULL pointer, it is ignored.

Description

The gettimeofday function gets the current time (expressed as seconds and microseconds) since 00::00 Coordinated Universal Time, January 1, 1970. The current time is stored in the timeval structure pointed to by the tp argument.

The tzp argument is intended to hold time-zone information set by the kernel. However, because the OpenVMS kernel does not set time-zone information, the tzp argument should be NULL. If it is not NULL, it is ignored. This function is supported for compatibility with BSD programs.

If the value of the SYS$TIMEZONE_DIFFERENTIAL logical is wrong, the function fails with errno set to EINVAL.

Return Values

0 Indicates success.
- 1 An error occurred. errno is set to indicate the error.

getuid

With POSIX IDs disabled, this function is equivalent to geteuid and returns the member number (in OpenVMS terms) from the user identification code (UIC).

With POSIX IDs enabled, returns the real user ID.

Format

#include <unistd.h>

uid_t getuid (void);

Description

The getuid 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 geteuid and getuid functions are equivalent and return the member number from the current UIC as follows:

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 .

Return Value

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

getw

Returns characters from a specified file.

Format

#include <stdio.h>

int getw (FILE *file_ptr);

Argument

file_ptr

A pointer to the file to be accessed.

Description

The getw function returns the next four characters from the specified input file as an int .

Return Values

x The next four characters, in an int .
EOF Indicates that the end-of-file was encountered during the retrieval of any of the four characters and all four characters were lost. Since EOF is an acceptable integer, use feof and ferror to check the success of the function.

getwc

Reads the next character from a specified file, and converts it to a wide-character code.

Format

#include <wchar.h>

wint_t getwc (FILE *file_ptr);

Argument

file_ptr

A pointer to the file to be accessed.

Description

Since getwc is implemented as a macro, a file pointer argument with side effects (for example getwc (*f++) ) might be evaluated incorrectly. In such a case, use the fgetwc function instead. See the fgetwc function.

Return Values

n The returned character.
WEOF Indicates the end-of-file or an error. If an error occurs, the function sets errno . For a list of the values set by this function, see fgetwc .

getwchar

Reads a single wide character from the standard input ( stdin ).

Format

#include <wchar.h>

wint_t getwchar (void);

Description

The getwchar function is identical to fgetwc ( stdin ).

Return Values

x The next character from stdin , converted to wint_t .
WEOF Indicates the end-of-file or an error. If an error occurs, the function sets errno . For a list of the values set by this function, see fgetwc .

getyx

Puts the (y,x) coordinates of the current cursor position on win in the variables y and x.

Format

#include <curses.h>

getyx (WINDOW *win, int y, int x);

Arguments

win

Must be a pointer to the window.

y

Must be a valid lvalue.

x

Must be a valid lvalue.

glob (INTEGRITY SERVERS, ALPHA)

Returns a list of existing files for a user supplied pathname (with optional wildcards).

Format

#include <glob.h>

int glob (const char *pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);

Function Variants The glob function has variants named _glob32 and _glob64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

pattern

The pattern string to match with accessible files and pathnames. This pattern can have wildcards.

flags

Controls the customizable behavior of the glob function.

errfunc

An optional function that, if specified, is called when the glob function detects an error condition, or if not specified, is NULL.

epath

First argument of the optional errfunc function, epath is the pathname that failed because a directory could not be opened or read.

eerrno

Second argument of the optional errfunc function, eerrno is the errno value from a failure specified by the epath argument as set by the opendir , readdir , or stat functions.

pglob

Pointer to a glob_t structure that returns the matching accessible existing filenames. The structure is allocated by the caller. The array of structures containing the located filenames that match the pattern argument are stored by the glob function into the structure. The last entry is a NULL pointer.

The structure type glob_t is defined in the <glob.h> header file and includes at least the following members: 


size_t   gl_pathc    //Count of paths matched by pattern.  
char **  gl_pathv    //Pointer to a list of matched pathnames.  
size_t   gl_offs     //Slots to reserve at the beginning of gl_pathv.

Description

The glob function constructs a list of accessible files that match the pattern argument.

The glob function operates in one of two modes: UNIX mode or OpenVMS mode.

You can select UNIX mode explicitly by enabling the feature logical DECC$GLOB_UNIX_STYLE, which is disabled by default.

The glob function defaults to OpenVMS mode unless one of the following conditions is met (in which case glob uses UNIX mode):

OpenVMS mode

This mode allows an OpenVMS programmer to give an OpenVMS style pattern to the glob function and get expected OpenVMS style output. The OpenVMS style pattern is what a user would expect from DCL commands or as input to the SYS$PARSE and SYS$SEARCH system routines.

In this mode, you can use any of the expected OpenVMS wildcards (see the OpenVMS documentation for additional information).

OpenVMS mode does not support the UNIX wildcard ?, or [] pattern matching. OpenVMS users expect [] to be available as directory delimiters.

Some additional behavior differences between OpenVMS mode and UNIX mode:

For example: 


Sample pattern input      Sample output 
 
[.SUBDIR1]A.TXT           DEV:[DIR.SUBDIR1]A.TXT;1 
[.SUB*]%.*                DEV:[DIR.SUBDIR1]A.TXT;1

UNIX mode

You can enable this mode explicitly with: 


$ DEFINE DECC$GLOB_UNIX_STYLE ENABLE

UNIX mode is also enabled if the DECC$FILENAME_UNIX_ONLY feature logical is set, or if the glob function determines that the specified pattern looks like a UNIX style pathname.

In UNIX mode, the glob function follows the X/Open specification where possible.

For example: 


Sample pattern input      Sample output 
 
./a/b/c                   ./a/b/c 
./?/b/*                   ./a/b/c 
[a-c]                     c

Standard Description

The glob function matches all accessible pathnames against this pattern and develops a list of all pathnames that match. To have access to a pathname, the glob function requires search permission on every component of a pathname except the last, and read permission on each directory of any filename component of the pattern argument.

The glob function stores the number of matched pathnames and a pointer to a list of pointers to pathnames in the pglob argument. The pathnames are sorted, based on the setting of the LC_COLLATE category in the current locale. The first pointer after the last pathname is NULL. If the pattern does not match any pathnames, the returned number of matched pathnames is 0.

It is the caller's responsibility to create the structure pointed to by the pglob argument. The glob function allocates other space as needed. The globfree function frees any space associated with the pglob argument as a result of a previous call to the glob function.

The flags argument is used to control the behavior of the glob function. The flags value is the bitwise inclusive OR (|) of any of the following constants, which are defined in the <glob.h> header file:
GLOB_APPEND Appends pathnames located with this call to any pathnames previously located.
GLOB_DOOFFS Uses the gl_offs structure to specify the number of NULL pointers to add to the beginning of the gl_pathv component of the pglob argument.
GLOB_ERR Causes the glob function to return when it encounters a directory that it cannot open or read. If the GLOB_ERR flag is not set, the glob function continues to find matches if it encounters a directory that it cannot open or read.
GLOB_MARK Specifies that each pathname that is a directory should have a slash (/) appended. GLOB_MARK is ignored in OpenVMS mode because it is not meaningful to append a slash to a directory on OpenVMS systems.
GLOB_NOCHECK If the pattern argument does not match any pathname, then the glob function returns a list consisting only of the pattern argument, and the number of matched pathnames is 1.
GLOB_NOESCAPE If the GLOB_NOESCAPE flag is set, a backslash (\) cannot be used to escape metacharacters.

The GLOB_APPEND flag can be used to append a new set of pathnames to those found in a previous call to the glob function. The following rules apply when two or more calls to the glob function are made with the same value of the pglob argument, and without intervening calls to the globfree function:

Previous Next Contents Index