| Previous | Contents | Index |
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);
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.
x Always indicates success. Returns the number of bytes in a page.
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-name information in the user database.
#include <pwd.h>struct passwd *getpwnam (const char name);
name
The name of the user for which the attributes are to be read.
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.
x A pointer to a valid password structure. NULL An error occurred. errno is set to indicate the error.
Accesses user-ID information in the user database.
#include <pwd.h>struct passwd *getpwuid (uid_t uid);
uid
The ID of the user for which the attributes are to be read.
This function accesses basic user attributes about a specified user. It returns the first user entry in a 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.
x A pointer to a valid password structure. NULL An error occurred. errno is set to indicate the error.
Reads a line from the standard input (stdin).
#include <stdio.h>Function Variants This function also has variants named _gets32 and _gets64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.char *gets (char *str);
str
A pointer to a character string that is large enough to hold the information fetched from stdin.
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.
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.
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.
#include <curses.h>int getstr (char *str);
int wgetstr (WINDOW *win, char *str);
win
A pointer to the window.str
Must be large enough to hold the character string fetched from the window.
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.
OK Indicates success. ERR Indicates that the function makes the screen scroll illegally.
Gets date and time.
#include <time.h>int gettimeofday (struct timeval *tp, void *tpz);
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, the behavior is unspecified.
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.
0 Indicates success. --1 An error occurred. errno is set to indicate the error.
Returns, in OpenVMS terms, the member number from the user identification code (UIC). For example, if the UIC is [313,031], 031 is the member number.
#include <unistd.h>uid_t getuid (void);
In DEC C for OpenVMS Systems, getuid and geteuid perform the same function.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.
x The member number from the current UIC, or the full UIC. See description.
Returns characters from a specified file.
#include <stdio.h>int getw (FILE *file_ptr);
file_ptr
A pointer to the file to be accessed.
This function returns the next four characters from the specified input file as an int .
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.
Reads the next character from a specified file, and converts it to a wide-character code.
#include <wchar.h>wint_t getwc (FILE *file_ptr);
file_ptr
A pointer to the file to be accessed.
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.
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.
Reads a single wide character from the standard input (stdin).
#include <wchar.h>wint_t getwchar (void);
The getwchar function is identical to fgetwc(stdin) .
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 in this section.
Puts the (y,x) coordinates of the current cursor position on win in the variables y and x.
#include <curses.h>getyx (WINDOW *win, int y, int x);
win
Must be a pointer to the window.y
Must be a valid lvalue.x
Must be a valid lvalue.
Converts time units to broken-down UTC time.
#include <time.h>Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to this function that is equivalent to the behavior before OpenVMS Version 7.0.struct tm *gmtime (const time_t *timer);
timer
Points to a variable that specifies a time value in seconds since the Epoch.
This function converts the time (in seconds since the Epoch) pointed to by timer into a broken-down time, expressed as Coordinated Universal Time (UTC).The tm structure is defined in the <time.h> header file as follows:
int tm_sec ; Seconds after the minute (0-60) int tm_min ; Minutes after the hour (0-59) int tm_hour ; Hours since midnight (0-23) int tm_mday ; Day of the month (1-31) int tm_mon ; Months since January (1-11) int tm_year ; Years since 1900 int tm_wday ; Days since Sunday (0-6) int tm_yday ; Days since January 1 (0-365) int tm_isdst ; Daylight Savings Time flag
- tm_isdst = 0 for Standard Time
- tm_isdst = 1 for Daylight Time
long tm_gmtoff ;1 Seconds east of Greenwich (Negative values indicate seconds west of Greenwich) char * tm_zone ;1 Time zone string, for example "GMT"
1This field is an extension to the ANSI C tm structure. It is present unless you compile your program with /STANDARD=ANSI89 or with _DECC_V4_SOURCE defined.
Note
Return values point to per-thread static storage, which is overwritten by subsequent calls to the gmtime function. You must make a copy if you wish to save it.
x Pointer to a tm structure. NULL Indicates an error; errno is set to one of the following values:
- EINVAL -- The timer argument is NULL.
Generates a specified software signal, which invokes the action routine established by a signal , ssignal , or sigvec function.
#include <signal.h>int gsignal (int sig [, int sigcode]);
sig
The signal to be generated.sigcode
An optional signal code. For example, signal SIGFPE---the arithmetic trap signal---has 10 different codes, each representing a different type of arithmetic trap.The signal codes can be represented by mnemonics or numbers. The arithmetic trap codes are represented by the numbers 1 to 10, but the SIGILL codes are represented by the numbers 0 to 2. The code values are defined in the <signal.h> header file. See Tables 4-4 and 4-5 for a list of signal mnemonics, codes, and corresponding OpenVMS exceptions.
Calling this function has one of the following results:
- If gsignal specifies a sig argument that is outside the range defined in the <signal.h> header file, then gsignal returns 0 and sets errno to EINVAL.
- If signal , ssignal , or sigvec establishes SIG_DFL (default action) for the signal, then gsignal does not return. The image is exited with the OpenVMS error code corresponding to the signal.
- If signal , ssignal , or sigvec establishes SIG_IGN (ignore signal) as the action for the signal, then gsignal returns its argument, sig.
- signal , ssignal , or sigvec must be used to establish an action routine for the signal. That function is called and its return value is returned by gsignal .
See also raise , signal , ssignal , and sigvec in this section.
See Chapter 4 for more information.
0 Indicates a sig argument that is outside the range defined in the <signal.h> header file; errno is set to EINVAL. sig Indicates that SIG_IGN (ignore signal) has been established as the action for the signal. x Indicates that signal , ssignal , or sigvec has established an action function for the signal. That function is called, and its return value is returned by gsignal .
Returns the square root of the sum of the squares of two arguments:
sqrt(x2 + y2)
#include <math.h>double hypot (double x, double y);
x
A real value.y
A real value.
On overflow, the return value is undefined.
Converts characters coded in one codeset to characters coded in another codeset.
#include <iconv.h>size_t iconv (iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
cd
A conversion descriptor. This is returned by a successful call to iconv_open .inbuf
A pointer to a variable that points to the first character in the input buffer.inbytesleft
Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the input buffer (inbuf). When the conversion is completed, the variable indicates the number of bytes in inbuf not converted.outbuf
A pointer to a variable that points to the first available byte in the output buffer. The output buffer contains the converted characters.outbytesleft
Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the output buffer (outbuf). When the conversion is completed, the variable indicates the number of bytes left in outbuf.
This function converts characters in the buffer pointed to by inbuf to characters in another code set. The resulting characters are stored in the buffer pointed to by outbuf. The conversion type is specified by the conversion descriptor cd. This descriptor is returned from a successful call to iconv_open .
Previous Next Contents Index