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

getpagesize

Gets the system page size.

Format

#include <unistd.h>

int getpagesize (void);

Description

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

Return Values

x	Always indicates success. Returns the number of bytes in a page.

getpid

Returns the process ID of the current process.

Format

#include <unistd.h>

pid_t getpid (void);

Return Value

x	The process ID of the current process.

getppid

Returns the parent process ID of the calling process.

Format

#include <unistd.h>

pid_t getppid (void);

Return Values

x	The parent process ID.
0	Indicates that the calling process does not have a parent process.

getpwent

Accesses user entry information in the user database.

Format

#include <stdio.h>

#include <pwd.h>

struct passwd *getpwent (void);

Arguments

passwd

The password structure where you write the user attributes.

Description

This function accesses basic user attributes about a specified user. The function returns the next user entry in a sequential search.

The passwd structure is defined in the <pwd.h> header file as follows:

pw_name	The name of the user.
pw_passwd	The encrypted password of the user.
pw_uid	The ID of the user.
pw_gid	The group ID of the principle group of the user.
pw_pecos	The personal information about the user.
pw_dir	The home directory of the user.
pw_shell	The initial program for the user.

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

Return Values

x	A pointer to a valid password structure.
NULL	Indicates an error.

getpwnam

Accesses user-name information in the user database.

Format

#include <pwd.h>

struct passwd *getpwnam (const char name);

Arguments

name

The name of the user for which the attributes are to be read.

Description

This 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 static area and is overwritten on subsequent calls to the function.

Return Values

x	A pointer to a valid password structure.
NULL	An error occurred. errno is set to indicate the error.

getpwuid

Accesses user-ID information in the rights database.

Format

#include <pwd.h>

struct passwd *getpwuid (uid_t uid);

Arguments

uid

The ID of the user for which the attributes are to be read.

Description

This function accesses the identifier names of all identifiers in the rights database. It returns the first user entry in the rights 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.

To check for error situations, applications should set errno to zero before calling getpwuid . If errno is nonzero on return, then an error occurred.

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.

Return Values

x	A pointer to a valid password structure.
NULL	An error occurred. errno is set to indicate the error.

gets

Reads a line from the standard input (stdin).

Format

#include <stdio.h>

char *gets (char *str);

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.

[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 in this section.

Return Values

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

gettimeofday

Gets date and time.

Format

#include <time.h>

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

Arguments

tp

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

tpz

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

Description

This 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, 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

This function can be used with POSIX-style identifiers or with UIC-based identifiers.

Note Currently, POSIX-style IDs are supported only by some OpenVMS versions done for specific government agencies, but will be integrated into future OpenVMS releases. OpenVMS Version 7.3-1 does not support POSIX-style IDs, but it does support 32-bit identifiers.

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.

See also getegid and getgid in this section.

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

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

Arguments

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 in this section.

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 in this section.