@c ----------------------------------------------------------------------
@node _get_default_drive, dos
@heading @code{_get_default_drive}
@subheading Syntax

@example
int _get_default_drive(void);
@end example

@subheading Description

Gets the default drive.

@subheading Return Value

0 for drive A:, 1 for drive B:, etc, up to 26 for Z:

@subheading Example

@example
printf("Current drive is %c:\n", _get_current_drive()+'a');
@end example

@c ----------------------------------------------------------------------
@node getc, stdio
@heading @code{getc}
@subheading Syntax

@example
#include <stdio.h>

int getc(FILE *file);
@end example

@subheading Description

Get one character from @var{file}.

@subheading Return Value

The character ([0..255]) or @code{EOF} if eof or error.

@subheading Example

@example
int c;
while ((c=getc(stdin)) != EOF)
  putc(c, stdout);
@end example

@c ----------------------------------------------------------------------
@node getcbrk, dos
@heading @code{getcbrk}
@subheading Syntax

@example
#include <dos.h>

int getcbrk(void);
@end example

@subheading Description

Get the setting of the Ctrl-C checking flag in MS-DOS.

@xref{setcbrk}

@subheading Return Value

0 if not checking, 1 if checking.

@c ----------------------------------------------------------------------
@node getchar, stdio
@heading @code{getchar}
@subheading Syntax

@example
#include <stdio.h>

int getchar(void);
@end example

@subheading Description

The same as @code{fgetc(stdin)} (@pxref{fgetc}).

@subheading Return Value

The character, or @code{EOF}.

@c ----------------------------------------------------------------------
@node getcwd, file system
@heading @code{getcwd}
@subheading Syntax

@example
#include <osfcn.h>

char *getcwd(char *buffer, int max);
@end example

@subheading Description

Get the current directory.  The return value includes the drive
specifier.  If @var{buffer} is @code{NULL}, a buffer of size @var{max}
is allocated.  This call fails if more than @var{max} characters are
required to specify the current directory. 

If @code{getcwd} allocates a buffer for you, you may later free is with
@code{free}. 

@subheading Return Value

The buffer, either @var{buffer} or a newly-allocated buffer, or
@code{NULL} on error. 

@subheading Example

@example
char *buf = getcwd(0, PATH_MAX);
printf("cwd is %s\n", buf);
free(buf);
@end example

@c ----------------------------------------------------------------------
@node getdate, time
@heading @code{getdate}
@subheading Syntax

@example
#include <dos.h>

void getdate(struct date *);
@end example

@subheading Description

This function gets the current date.  The return structure is as follows:

@example
struct date @{
  short da_year;
  char  da_day;
  char  da_mon;
@};
@end example

@xref{setdate} @xref{gettime}

@subheading Return Value

None.

@subheading Example

@example
struct date d;
getdate(&d);
@end example

@c ----------------------------------------------------------------------
@node getdfree, file system
@heading @code{getdfree}
@subheading Syntax

@example
#include <dos.h>

void getdfree(unsigned char drive, struct dfree *ptr);
@end example

@subheading Description

This function gets information about the size and fullness of the given
drive (0=default, 1=A:, etc).  The return structure is as follows:

@example
struct dfree @{
  unsigned df_avail; /* number of available clusters */
  unsigned df_total; /* total number of clusters */
  unsigned df_bsec;  /* bytes per sector */
  unsigned df_sclus; /* sectors per cluster */
@};
@end example

@subheading Return Value

None.

@subheading Example

@example
struct dfree d;
getdfree(3, &d); /* drive C: */
@end example

@c ----------------------------------------------------------------------
@node getdisk, dos
@heading @code{getdisk}
@subheading Syntax

@example
#include <dir.h

int getdisk(void);
@end example

@subheading Description

Gets the current disk (0=A).

@xref{setdisk}

@subheading Return Value

The current disk.

@subheading Example

@example
printf("This drive is %c:\n", getdisk() + 'A');
@end example

@c ----------------------------------------------------------------------
@node getdtablesize, posix
@heading @code{getdtablesize}
@subheading Syntax

@example
#include <osfcn.h>

int getdtablesize(void);
@end example

@subheading Description

Get the maximum number of open file descriptors the system supports. 
Should depend on the setting of @code{FILES=} in @file{config.sys}, but
is currently hardcoded to 50. 

@subheading Return Value

The number of file descriptors.

@c ----------------------------------------------------------------------
@node getegid, unix
@heading @code{getegid}
@subheading Syntax

@example
#include <osfcn.h>

int getegid(void);
@end example

@subheading Description

Get the effective group id.

@subheading Return Value

42

@c ----------------------------------------------------------------------
@node getenv, environment
@heading @code{getenv}
@subheading Syntax

@example
#include <stdlib.h>

char *getenv(const char *name);
@end example

@subheading Description

Get the setting of the environment variable @var{name}.  Do not alter or
free the returned value. 

@subheading Return Value

The value, or @code{NULL} if that variable does not exist.

@subheading Example

@example
char *term = getenv("TERM");
@end example

@c ----------------------------------------------------------------------
@node geteuid, unix
@heading @code{geteuid}
@subheading Syntax

@example
#include <osfcn.h>

int geteuid(void);
@end example

@subheading Description

Gets the effective UID.

@subheading Return Value

42

@c ----------------------------------------------------------------------
@node getftime, file system
@heading @code{getftime}
@subheading Syntax

@example
#include <dos.h>

int getftime(int handle, struct ftime *ptr);
@end example

@subheading Description

Get the timestamp for the given file handle.  The return structure is as
follows:

@example
struct ftime @{
  unsigned ft_tsec:5;	/* 0-29, double to get real seconds */
  unsigned ft_min:6;	/* 0-59 */
  unsigned ft_hour:5;	/* 0-23 */
  unsigned ft_day:5;	/* 1-31 */
  unsigned ft_month:4;	/* 1-12 */
  unsigned ft_year:7;	/* since 1980 */
@}
@end example

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
struct ftime t;
getftime(fd, &t);
@end example

@c ----------------------------------------------------------------------
@node getgid, unix
@heading @code{getgid}
@subheading Syntax

@example
#include <osfcn.h>

int getgid(void);
@end example

@subheading Description

Get the current group id.

@subheading Return Value

42

@c ----------------------------------------------------------------------
@node getgrent, unix
@heading @code{getgrent}
@subheading Syntax

@example
#include <grp.h>

struct group *getgrent(void);
@end example

@subheading Description

This function returns the next available group entry.  Note that for
MS-DOS, this is simulated.  If the environment variable GROUP is set,
that is the name of the only group returned, else the only group is
"other". 

The return type of this and related function is as follows:

@example
struct group @{
  char *  gr_name;   /* "other" or getenv("GROUP"); */
  char *  gr_passwd; /* "*" */
  int     gr_gid;    /* result of getgid() */
  char ** gr_mem;    /* always empty */
@};
@end example

@subheading Return Value

The next structure, or @code{NULL} at the end of the list.

@subheading Example

@example

struct group *g;
setgrent();
while ((g = getgrent()) != NULL)
@{
  printf("group %s gid %d\n", g->gr_name, g->gr_gid);
@}
endgrent();
@end example

@c ----------------------------------------------------------------------
@node getgrgid, unix
@heading @code{getgrgid}
@subheading Syntax

@example
#include <grp.h>

extern struct group *getgrgid(int gid);
@end example

@subheading Description

This function returns the group entry that matches @var{gid}. 
@xref{getgrent}

@subheading Return Value

The matching group, or @code{NULL} if none match.

@c ----------------------------------------------------------------------
@node getgrnam, unix
@heading @code{getgrnam}
@subheading Syntax

@example
#include <grp.h>

struct group *getgrnam(char *name);
@end example

@subheading Description

This function returns the group entry for the group named @var{name}. 
@xref{getgrent}

@subheading Return Value

The matching group, or @code{NULL} if none match.

@c ----------------------------------------------------------------------
@node getgroups, unix
@heading @code{getgroups}

@subheading Description

This function is provided only to assist in porting from Unix.  It
always returns an error condition. 

@c ----------------------------------------------------------------------
@node getkey, dos
@heading @code{getkey}
@subheading Syntax

@example
#include <pc.h>
#include <keys.h>

int getkey(void);
@end example

@subheading Description

Waits for the user to press one key, then returns that key.  Alt-key
combinations have 0x100 added to them.  Extended keys return their
non-extended codes. 

The file @file{keys.h} has symbolic names for many of the keys.

@xref{getxkey}

@subheading Return Value

The key pressed.

@subheading Example

@example
while (getkey() != K_Alt_3)
  do_something();
@end example

@c ----------------------------------------------------------------------
@node getlogin, unix
@heading @code{getlogin}
@subheading Syntax

@example
#include <unistd.h>

char *getlogin(void);
@end example

@subheading Description

Get the login ID of the user.

@subheading Return Value

Returns the value of the @code{USER} environment variable, else the
@code{LOGNAME} environment variable, else @code{"dosuser"}. 

@subheading Example

@example
printf("I am %s\n", getlogin());
@end example

@c ----------------------------------------------------------------------
@node getlongpass, unix
@heading @code{getlongpass}
@subheading Syntax

@example
int getlongpass(const char *prompt, char *password, int max_length);
@end example

@subheading Description

Read a password from the user.  First, the prompt is sent to
@code{stderr}.  The characters typed are not echoed, and backspace can
be used to edit the line.  The password will be stored in
@var{password}, up to @var{max_length} characters.  When the user
hits @key{Return} or @key{Enter}, a newline is printed to @code{stderr} and the
password is returned.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
@end example

@c ----------------------------------------------------------------------
@node getmntent, unix
@heading @code{getmntent}
@subheading Syntax

@example
#include <mntent.h>

struct mntent *getmntent(FILE *filep);
@end example

@subheading Description

This function returns information about the various drives that are
available to your program.  Beginning with drive @code{A:}, information
is retrieved for successive drives with successive calls to
@code{getmntent}.  Note that drives @code{A:} and @code{B:} will only be
returned if they are the current drive, otherwise the first drive
returned is @code{C:}.

This function operates by reading the volume label, so unlabelled disks
will not be available.  For each drive scanned, a pointer to a static
structure of the following type is returned:

@example
struct mntent
@{
    char * mnt_fsname;  /* The volume name */
    char * mnt_dir;     /* The drive name (like "c:") */
    char * mnt_type;    /* "dos" */
    char * mnt_opts;    /* "rw" */
    int    mnt_freq;    /* -1 */
    int    mnt_passno;  /* -1 */
    long   mnt_time;    /* -1 */
@};
@end example

@subheading Return Value

This function returns a pointer to an @code{struct} @code{mntent}, or
NULL if there are no more drives to report on. 

@subheading Example

@example
struct mntent *m;
FILE *f;
f = setmntent("", "");
while (m = getmntent(f))
  printf("Drive %s, name %s\n", m->mnt_dir, m->mnt_fsname);
endmntent(f);
@end example

@c ----------------------------------------------------------------------
@node getopt, misc
@heading @code{getopt}
@subheading Syntax

@example
int getopt(int argc, char * const *argv, const char *options);
extern char *optarg;
extern int optind, opterr;
extern char optopt;
@end example

@subheading Description

Parse options from the command line.  The @var{options} are a string of
valid option characters.  If a given option takes a parameter, that
character should be followed by a colon.

For each valid switch, this function sets @code{optarg} to the argument
(if the switch takes one), sets @code{optind} to the index in @var{argv}
that it is using, sets @code{optopt} to the option letter found, and
returns the option letter found.

If an unexpected option is found, @code{getopt} will return @code{?},
and if @code{opterr} is nonzero, will print an error message to stderr. 

The special option @code{--} indicates that no more options follow on
the command line, and cause @code{getopt} to stop looking. 

@subheading Return Value

The option found, or -1 if no more options.

@subheading Example

@example
int c;
opterr = 0;
while ((c=getopt(argc, argv, "vbf:")) != -1)
@{
  switch (c)
  @{
    case 'v':
      verbose_flag ++;
      break;
    case 'b':
      binary_flag ++;
      break;
    case 'f':
      output_filename = optarg;
      break;
    case '?':
      printf("Unknown option %c\n", c);
      usage();
      exit(1);
  @}
@}
@end example

@c ----------------------------------------------------------------------
@node getpagesize, misc
@heading @code{getpagesize}
@subheading Syntax

@example
#include <osfcn.h>

int getpagesize(void);
@end example

@subheading Description

Return the size of the native virtual memory page size.

@subheading Return Value

4096 for the i386 and higher processors.

@c ----------------------------------------------------------------------
@node getpass, unix
@heading @code{getpass}
@subheading Syntax

@example
#include <unistd.h>

char *getpass(const char *prompt);
@end example

@subheading Description

Prompts the user with @var{prompt} and accepts a non-echoed password. 
@xref{getlongpass}

@subheading Return Value

A pointer to a static buffer is returned.  This buffer is overridden
with each call to @code{getpass}.

@subheading Example

@example
char *pw = getpass("Enter password : ");
@end example

@c ----------------------------------------------------------------------
@node getpid, unix
@heading @code{getpid}
@subheading Syntax

@example
#include <osfcn.h>

int getpid(void);
@end example

@subheading Description

Get the process ID, which uniquely identifies each program running on
the system. 

@subheading Return Value

The process ID.

@c ----------------------------------------------------------------------
@node getpwent, unix
@heading @code{getpwent}
@subheading Syntax

@example
#include <pwd.h>

struct passwd *getpwent(void);
@end example

@subheading Description

This function retrieves the next available password file entry. 
For MS-DOS, this is simulated by providing exactly one entry:

@example
struct passwd @{
  char * pw_name;    /* getlogin() */
  char * pw_passwd;  /* "*" */
  int    pw_uid;     /* getuid() */
  int    pw_gid;     /* getgid() */
  char * pw_age;     /* "" */
  char * pw_comment; /* "" */
  char * pw_gecos;   /* "DOS User" */
  char * pw_dir;     /* "/" or getenv("HOME") */
  char * pw_shell;   /* "/bin/sh" or getenv("SHELL") */
  long   pw_audid;   /* -1 */
  int    pw_audflg;  /* -1 */
@};
@end example

@subheading Return Value

The next passwd entry, or @code{NULL} if there are no more.

@subheading Example

@example
struct passwd *p;
setpwent();
while ((p = getpwent()) != NULL)
@{
  printf("user %s name %s\n", p->pw_name, p->pw_gecos);
@}
endpwent();
@end example

@c ----------------------------------------------------------------------
@node getpwnam, unix
@heading @code{getpwnam}
@subheading Syntax

@example
#include <pwd.h>

struct passwd *getpwnam(char *name);
@end example

@subheading Description

This function gets the password file entry matchine @var{name}.  @xref{getpwent}

@subheading Return Value

The matching record, or @code{NULL} if none match.

@c ----------------------------------------------------------------------
@node getpwuid, unix
@heading @code{getpwuid}
#include <pwd.h>

struct passwd *getpwuid(int uid);
@subheading Syntax

@example
@end example

@subheading Description

This function gets the password file entry matchine @var{uid}.  @xref{getpwent}

@subheading Return Value

The matching record, or @code{NULL} if none match.

@c ----------------------------------------------------------------------
@node getrusage, unix
@heading @code{getrusage}
@subheading Syntax

@example
#include <sys/time.h>
#include <sys/resource.h

int getrusage(int who, struct rusage *rusage);
@end example

@subheading Description

This function returns information about the running process.  Currently,
the only field that is computed is this:

@example
struct rusage @{
  struct timeval ru_utime;  /* total time used by process */
@};
@end example

The remainder of the fields are set to zero.

The @var{who} parameter must be @code{RUSAGE_SELF} or
@code{RUSAGE_CHILDREN}. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
struct rusage r;
getrusage(RUSAGE_SELF, &r);
@end example

@c ----------------------------------------------------------------------
@node gets, stdio
@heading @code{gets}
@subheading Syntax

@example
#include <stdio.h>

char *gets(char *buffer);
@end example

@subheading Description

Reads characters from @code{stdin}, storing them in @var{buffer}, until
either end of file or a newline is encountered.  If any characters were
stored, the @var{buffer} is then @code{NULL} terminated and it's address
is returned, else @code{NULL} is returned.

@subheading Return Value

The address of the buffer, or @code{NULL}.

@subheading Example

@example
char buf[1000];
while (gets(buf))
  puts(buf);
@end example

@c ----------------------------------------------------------------------
@node gettime, time
@heading @code{gettime}
@subheading Syntax

@example
#include <dos.h>

void gettime(struct time *);
@end example

@subheading Description

This function gets the current time.  The return structure is as follows:

@example
struct time @{
  unsigned char ti_min;
  unsigned char ti_hour;
  unsigned char ti_hund;
  unsigned char ti_sec;
@};
@end example

@xref{settime} @xref{getdate}

@subheading Return Value

None.

@subheading Example

@example
struct time t;
gettime(&t);
@end example

@c ----------------------------------------------------------------------
@node gettimeofday, time
@heading @code{gettimeofday}
@subheading Syntax

@example
#include <sys/time.h>

int gettimeofday(struct timeval *tp, struct timezone *tzp);
@end example

@subheading Description

Gets the current GMT time and the local timezone information.  The
return structures are as follows:

@example
struct timeval @{
  long tv_sec;  /* seconds since 00:00:00 GMT 1/1/1980 */
  long tv_usec; /* microseconds */
@};
struct timezone @{
  int tz_minuteswest; /* west of GMT */
  int tz_dsttime;     /* set if daylight saving time in affect */
@};
@end example

If either @var{tp} or @var{tzp} are @code{NULL}, that information is not
provided. 

@xref{settimeofday}

@subheading Return Value

Zero on success, nonzero on failure.

@c ----------------------------------------------------------------------
@node getuid, unix
@heading @code{getuid}
@subheading Syntax

@example
#include <osfcn.h>

int getuid(void);
@end example

@subheading Description

Returns the user ID.

@subheading Return Value

42

@c ----------------------------------------------------------------------
@node getw, stdio
@heading @code{getw}
@subheading Syntax

@example
#include <stdio.h>

int getw(FILE *file);
@end example

@subheading Description

Reads a single binary word in native format from @var{file}.

@xref{putw}

@subheading Return Value

The value read, or @code{EOF} for end-of-file or error.  Since
@code{EOF} is a valid integer, you should use @code{feof} or
@code{ferror} to detect this situation. 

@subheading Example

@example
int i = getw(stdin);
@end example

@c ----------------------------------------------------------------------
@node getwd, file system
@heading @code{getwd}
@subheading Syntax

@example
#include <osfcn.h>

char *getwd(char *buffer);
@end example

@subheading Description

Get the current directory and put it in @var{buffer}.  The return value
includes the drive specifier. 

@subheading Return Value

@var{buffer} is returned.

@subheading Example

@example
char buf[PATH_MAX];
getwd(buf);
@end example

@c ----------------------------------------------------------------------
@node getxkey, dos
@heading @code{getxkey}
@subheading Syntax

@example
#include <pc.h>
#include <keys.h>

int getxkey(void);
@end example

@subheading Description

Waits for the user to press one key, then returns that key.  Alt-key
combinations have 0x100 added to them, and extended keys have 0x200
added to them. 

The file @file{keys.h} has symbolic names for many of the keys.

@xref{getkey}

@subheading Return Value

The key pressed.

@subheading Example

@example
while (getxkey() != K_EEnd)
  do_something();
@end example

