@c ----------------------------------------------------------------------
@node stat, io
@heading @code{stat}
@subheading Syntax

@example
#include <sys/stat.h>

int stat(const char *file, struct stat *sbuf);
@end example

@subheading Description

This function obtains the status of the file @var{file} and stores
it in @var{sbuf}, which has this structure:

@example
struct  stat @{
        short    st_dev;         /* The drive number */
        short    st_ino;         /* a unique identifier */
        unsigned short st_mode;  /* file mode - S_IF* and S_IREAD/S_IWRITE */
        short    st_nlink;       /* 1 */
        short    st_uid;         /* getuid() */
        short    st_gid;         /* getgid() */
        short    st_rdev;        /* the drive number */
        short    st_align_for_word32;
        long     st_size;        /* size of file in bytes */
        long     st_atime;       /* time of last modification */
        long     st_mtime;       /*            ''             */
        long     st_ctime;       /*            ''             */
        long     st_blksize;     /* 512 */
@};
@end example

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
struct stat s;
stat("data.txt", &s);
if (S_ISDIR(s.st_mode))
  printf("is directory\n");
@end example

@c ----------------------------------------------------------------------
@node stat_assist, io
@heading @code{stat_assist}

@subheading Description

This is an internal function used by @code{stat}.

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

@example
#include <sys/vfs.h>

int statfs(const char *filename, struct statfs *buf);
@end example

@subheading Description

This function returns information about the given "filesystem".  The
drive letter of the given @var{filename}, or the default drive if none
is given, is used to retrieve the following structure:

@example
struct statfs
@{
    long	f_type;   /* 0 */
    long	f_bsize;  /* bytes per cluster */
    long	f_blocks; /* clusters on drive */
    long	f_bfree;  /* available clusters */
    long	f_bavail; /* available clusters */
    long	f_files;  /* clusters on drive */
    long	f_ffree;  /* available clusters */
    fsid_t	f_fsid;   /* [0]=drive_number, [1]=MOUNT_UFS
    long	f_magic;  /* FS_MAGIC */
@};
@end example

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
struct statfs fs;
statfs("anything", &fs);
printf("%d bytes left\n", fs.f_bfree * fs.f_bsize);
@end example

@c ----------------------------------------------------------------------
@node stdin/stdout/stderr/stdprn/stdaux, stdio
@heading @code{stdin}, @code{stdout}, @code{stderr}, @code{stdprn}, @code{stdaux}
@subheading Syntax

@example
#include <stdio.h>

extern FILE *stdin, *stdou, *stderr;
@end example

@subheading Description

These predefined files represent the "standard" input and output files
that are available to a program.

@subheading Example

@example
  fprintf(stdprn, "This goes to the printer\n");
@end example

@c ----------------------------------------------------------------------
@node _stklen, go32
@heading @code{_stklen}
@subheading Syntax

@example
extern int _stklen;
@end example

@subheading Description

This variable sets the minimum stack length that the program requires. 
Note that the stack may be much larger than this.  This value should be
set statically, as it is only used at startup. 

@subheading Example

@example
extern int _stklen = 256000;
@end example

@c ----------------------------------------------------------------------
@node strcasecmp, string
@heading @code{strcasecmp}
@subheading Syntax

@example
#include <string.h>

int strcasecmp(const char *s1, const char *s2);
@end example

@subheading Description

This function compares the two strings, disregarding case.

@subheading Return Value

Zero if they're the same, nonzero if different, the sign indicates
"order". 

@subheading Example

@example
if (strcasecmp(arg, "-i") == 0)
  do_include();
@end example

@c ----------------------------------------------------------------------
@node strcat, string
@heading @code{strcat}
@subheading Syntax

@example
#include <string.h>

char *strcat(char *s1, const char *s2);
@end example

@subheading Description

This function concatenates @var{s2} to the end of @var{s1}.

@subheading Return Value

@var{s1}

@subheading Example

@example
char buf[100] = "hello";
strcat(buf, " there");
@end example

@c ----------------------------------------------------------------------
@node strchr, string
@heading @code{strchr}
@subheading Syntax

@example
#include <string.h>

char *strchr(const char *s, int c);
@end example

@subheading Description

This function returns a pointer to the first occurrence of @var{c} in
@var{s}.  Note that if @var{c} is @code{NULL}, this will return a
pointer to the end of the string. 

@subheading Return Value

A pointer to the character, or @code{NULL} if it wasn't found. 

@subheading Example

@example
char *slash = strchr(filename, '/');
@end example

@c ----------------------------------------------------------------------
@node strcmp, string
@heading @code{strcmp}
@subheading Syntax

@example
#include <string.h>

int strcmp(const char *s1, const char *s2);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}.

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequense, else a negative number. 

@subheading Example

@example
if (strcmp(arg, "-i") == 0)
  do_include();
@end example

@c ----------------------------------------------------------------------
@node strcoll, locale
@heading @code{strcoll}
@subheading Syntax

@example
#include <string.h>

int strcoll(const char *s1, const char *s2);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}, using the collating
sequences from the current locale. 

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the collating sequense, else a negative number. 

@subheading Example

@example
while (strcoll(var, list[i]) < 0)
  i++;
@end example

@c ----------------------------------------------------------------------
@node strcpy, string
@heading @code{strcpy}
@subheading Syntax

@example
#include <string.h>

char *strcpy(char *s1, const char *s2);
@end example

@subheading Description

This function copies @var{s2} into @var{s1}.

@subheading Return Value

@var{s1}

@subheading Example

@example
char buf[100];
strcpy(buf, arg);
@end example

@c ----------------------------------------------------------------------
@node strcspn, string
@heading @code{strcspn}
@subheading Syntax

@example
#include <string.h>

size_t strcspn(const char *s1, const char *set);
@end example

@subheading Description

This function finds the first character in @var{s1} that matches any
character in @var{set}.  Note that the @code{NULL} bytes at the end of
each string counts, so you'll at least get a pointer to the end of the
string if nothing else. 

@subheading Return Value

The index of the found character.

@subheading Example

@example
int i = strcspn(command, "<>|");
if (command[i])
  do_redirection();
@end example

@c ----------------------------------------------------------------------
@node strdup, string
@heading @code{strdup}
@subheading Syntax

@example
#include <string.h>

char * strdup (const char *source);
@end example

@subheading Description

Returns a newly allocated area of memory that contains a duplicate of
the string pointed to by @var{source}.  The memory returned by this
call must be freed by the caller.

@subheading Return Value

Returns the newly allocated string, or @var{NULL} if there
is no more memory.

@subheading Example

@example
char *foo()
@{
  return strdup("hello");
@}
@end example

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

@example
#include <string.h>

char *strerror(int error);
@end example

@subheading Description

This function returns a string that describes the @var{error}. 

@subheading Return Value

A pointer to a static string that should not be modified or free'd. 

@subheading Example

@example
if (f=fopen("foo", "r") == 0)
  printf("Error! %s: %s\n", "foo", strerror(errno));
@end example

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

@example
#include <time.h>

size_t strftime(char *buf, size_t n, const char *format, const struct tm *time);
@end example

@subheading Description

This function formats the given @var{time} according to the given
@var{format} and stores it in @var{buf}, not exceeding @var{n} bytes. 

The format string is like @code{printf} in that any character other than
@code{%} is added to the output string, and for each character following
a @code{%} a pattern is added to the string as follows, with the
examples as if the time was Friday, October 1, 1993, at 03:30:34 PM EDT:

@table @code

@item %A

The full weekday name (@code{Friday})

@item %a

The abbreviated weekday name (@code{Fri})

@item %B

The full month name (@code{October})

@item %b
@itemx %h

The abbreviated month name (@code{Oct})

@item %C

Short for @code{%a %b %e %H:%M:%S %Y} (@code{Fri Oct  1 15:30:34 1993})

@item %c

Short for @code{%m/%d/%y %H:%M:%S} (@code{10/01/93 15:30:34})

@item %e

The day of the month, blank padded to two characters (@code{ 2})

@item %D

Short for @code{%m/%d/%y} (@code{10/01/93})

@item %d

The day of the month, zero padded to two characters (@code{02})

@item %H

The hour (0-24), zero padded to two characters (@code{15})

@item %I

The hour (1-12), zero padded to two characters (@code{03})

@item %j

The julien day, zero padded to three characters (@code{275})

@item %k

The hour (0-24), space padded to two characters (@code{15})

@item %l

The hour (1-12), space padded to two characters(@code{ 3})

@item %M

The minutes, zero padded to two characters (@code{30})

@item %m

The month (1-12), zero padded to two characters (@code{10})

@item %n

A newline (@code{\n})

@item %p

AM or PM (@code{PM})

@item %R

Short for @code{%H:%M} (@code{15:30})

@item %r

Short for @code{%I:%M:%S %p} (@code{03:30:35 PM})

@item %S

The seconds, zero padded to two characters (@code{35})

@item %T
@itemx %X

Short for @code{%H:%M:%S} (@code{15:30:35})

@item %t

A tab (@code{\t})

@item %U

The week of the year, with the first week defined by the first Sunday of
the year, zero padded to two characters (@code{39})

@item %W

The week of the year, with the first week defined by the first Monday of
the year, zero padded to two characters (@code{39})

@item %w

The day of the week (0-6) (@code{5})

@item %x

Short for @code{%m/%d/%y} (@code{10/01/93})

@item %y

The year (00-99) of the century (@code{93})

@item %Y

The year, zero padded to four digits (@code{1993})

@item %Z

The timezone abbreviation (@code{EDT})

@item %%

A percent symbol (@code{%})

@end table

@subheading Return Value

The number of characters stored.

@subheading Example

@example
struct tm t;
char buf[100];
strftime(buf, 100, "%B %d, %Y", &t);
@end example

@c ----------------------------------------------------------------------
@node stricmp, string
@heading @code{stricmp}
@subheading Syntax

@example
#include <string.h>

int stricmp(const char *s1, const char *s2);
@end example

@subheading Description

This function compares the two strings, disregarding case.

@subheading Return Value

Zero if they're the same, nonzero if different, the sign indicates
"order". 

@subheading Example

@example
if (stricmp(arg, "-i") == 0)
  do_include();
@end example

@c ----------------------------------------------------------------------
@node strlen, string
@heading @code{strlen}
@subheading Syntax

@example
#include <string.h>

size_t strlen(const char *string);
@end example

@subheading Description

This function returns the number of characters in @var{string}.

@subheading Return Value

The length of the string.

@subheading Example

@example
if (strlen(fname) > PATH_MAX)
  invalid_file(fname);
@end example

@c ----------------------------------------------------------------------
@node strlwr, string
@heading @code{strlwr}
@subheading Syntax

@example
#include <string.h>

char *strlwr(char *string);
@end example

@subheading Description

This function replaces all upper case letters in @var{string} with lower
case letters. 

@subheading Return Value

The string.

@subheading Example

@example
char buf[100] = "Hello";
strlwr(buf);
@end example

@c ----------------------------------------------------------------------
@node strncasecmp, string
@heading @code{strncasecmp}
@subheading Syntax

@example
#include <string.h>

int strncasecmp(const char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}, ignoring case, up to a
maximum of @var{max} characters. 

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequense, else a negative number. 

@subheading Example

@example
if (strncasecmp(foo, "-i", 2) == 0)
  do_include();
@end example

@c ----------------------------------------------------------------------
@node strncat, string
@heading @code{strncat}
@subheading Syntax

@example
#include <string.h>

char *strncat(char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function concatenates up to @var{max} characters of @var{s2} to the
end of @var{s1}.

@subheading Return Value

@var{s1}

@subheading Example

@example
strncat(fname, extension, 4);
@end example

@c ----------------------------------------------------------------------
@node strncmp, string
@heading @code{strncmp}
@subheading Syntax

@example
#include <string.h>

int strncmp(const char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function compares upto @var{max} characters of @var{s1} and @var{s2}.

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequense, else a negative number. 

@subheading Example

@example
if (strncmp(arg, "-i", 2) == 0)
  do_include();
@end example

@c ----------------------------------------------------------------------
@node strncpy, string
@heading @code{strncpy}
@subheading Syntax

@example
#include <string.h>

char *strcpy(char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function copies up to @var{max} characters of @var{s2} into @var{s1}.

@subheading Return Value

@var{s1}

@subheading Example

@example
char buf[100];
strcpy(buf, arg, 99);
@end example

@c ----------------------------------------------------------------------
@node strnicmp, string
@heading @code{strnicmp}
@subheading Syntax

@example
#include <string.h>

int strnicmp(const char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}, ignoring case, up to a
maximum of @var{max} characters. 

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequense, else a negative number. 

@subheading Example

@example
if (strnicmp(foo, "-i", 2) == 0)
  do_include();
@end example

@c ----------------------------------------------------------------------
@node strpbrk, string
@heading @code{strpbrk}
@subheading Syntax

@example
#include <string.h>

char *strpbrk(const char *s1, const char *set);
@end example

@subheading Description

This function finds the first character in @var{s1} that matches any
character in @var{set}.

@subheading Return Value

A pointer to the first match, or @code{NULL} if none are found.

@subheading Example

@example
if (strpbrk(command, "<>|"))
  do_redirection();
@end example

@c ----------------------------------------------------------------------
@node strrchr, string
@heading @code{strrchr}
@subheading Syntax

@example
#include <string.h>

char *strrchr(const char *s1, int c);
@end example

@subheading Description

This function finds the last occurrence of @code{c} in @code{s1}.

@subheading Return Value

A pointer to the last match, or @code{NULL} if the character isn't in
the string. 

@subheading Example

@example
char *last_slash = strrchr(filename, '/');
@end example

@c ----------------------------------------------------------------------
@node strsep, string
@heading @code{strsep}
@subheading Syntax

@example
#include <string.h>

char *strsep(char **stringp, char *delim);
@end example

@subheading Description

This function retrieves the next token from the given string, where
@var{stringp} points to a variable holding, initially, the start of the
string.  Tokens are delimited by a character from @var{delim}.  Each
time the function is called, it returns a pointer to the next token, and
sets *@var{stringp} to the next spot to check, or @code{NULL}. 

@subheading Return Value

The next token, or NULL.

@subheading Example

@example
main()
@{
  char *buf = "Hello  there,stranger";
  char **bp = &buf;
  char *tok;
  while (tok = strsep(bp, " ,"))
    printf("tok = `%s'\n", tok);
@}

tok = `Hello'
tok = `'
tok = `there'
tok = `stranger'
@end example

@c ----------------------------------------------------------------------
@node strspn, string
@heading @code{strspn}
@subheading Syntax

@example
#include <string.h>

size_t strspn(const char *s1, const char *set);
@end example

@subheading Description

This function finds the first character in @var{s1} that does not match
any character in @var{set}.  Note that the @code{NULL} bytes at the end
of @var{s1} counts, so you'll at least get a pointer to the end of the
string if nothing else. 

@subheading Return Value

The index of the found character.

@subheading Example

@example
int i = strcspn(entry, " \t\b");
if (entry[i])
  do_something();
@end example

@c ----------------------------------------------------------------------
@node strstr, string
@heading @code{strstr}
@subheading Syntax

@example
#include <string.h>

char *strstr(const char *s1, const char *s2);
@end example

@subheading Description

This function finds the first occurrence of @var{s2} in @var{s1}. 

@subheading Return Value

A pointer within @var{s1}, or @code{NULL} if @var{s2} wasn't found.

@subheading Example

@example
if (strstr(command, ".exe"))
  do_exe();
@end example

@c ----------------------------------------------------------------------
@node strtod, string
@heading @code{strtod}
@subheading Syntax

@example
#include <stdlib.h>

double strtod(const char *s, char **endp);
@end example

@subheading Description

This function converts as many characters of @var{s} that look like a
floating point number into one, and sets @var{*endp} to point to the
first unused character. 

@subheading Return Value

The value the string represented. 

@subheading Example

@example
char *buf = "123ret";
char *bp;
double x = strtod(buf, &bp);
@end example

@c ----------------------------------------------------------------------
@node _strtold, string
@heading @code{_strtold}
@subheading Syntax

@example
#include <stdlib.h>

long double _strtold(const char *s, char **endp);
@end example

@subheading Description

This function converts as many characters of @var{s} that look like a
floating point number into one, and sets @var{*endp} to point to the
first unused character. 

@subheading Return Value

The value the string represented. 

@subheading Example

@example
char *buf = "123ret";
char *bp;
long double x = _strtold(buf, &bp);
@end example

@c ----------------------------------------------------------------------
@node strtok, string
@heading @code{strtok}
@subheading Syntax

@example
#include <string.h>

char *strtok(char *s1, const char *s2);
@end example

@subheading Description

This function retrieves tokens from @var{s1} which are delimited by
characters from @var{s2}.

To initiate the search, pass the string to be searched as @var{s1}.  For
the remaining tokens, pass @code{NULL} instead. 

@subheading Return Value

A pointer to the token, or @code{NULL} if no more are found.

@subheading Example

@example
main()
@{
  char *buf = "Hello there, stranger";
  char *tok;
  for (tok = strtok(buf, " ,");
       tok;
       tok=strtok(0, " ,"))
    printf("tok = `%s'\n", tok);
@}

tok = `Hello'
tok = `there'
tok = `stranger'
@end example

@c ----------------------------------------------------------------------
@node strtol, string
@heading @code{strtol}
@subheading Syntax

@example
#include <stdlib.h>

long strtol(const char *s, char **endp, int base);
@end example

@subheading Description

This function converts as much of @var{s} as looks like an appropriate
number into the value of that number, and sets @var{*endp} to point to
the first unused character. 

The @var{base} argument indicates what base the digits (or letters)
should be treated as.  If @var{base} is zero, the base is determined by
looking for @code{0x}, @code{0X}, or @code{0} as the first part of the
string, and sets the base used to 16, 16, or 8 if it finds one.  The
default base is 10 if none of those prefixes are found.

@subheading Return Value

The value.

@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %d\n", strtol(buf, &bp, 0));
@end example

@c ----------------------------------------------------------------------
@node strtoul, string
@heading @code{strtoul}
@subheading Syntax

@example
#include <stdlib.h>

unsigned long strtoul(const char *s, char **endp, int base);
@end example

@subheading Description

This is just like @code{strtol} (@pxref{strtol}) except that the result
is unsigned. 

@subheading Return Value

The value.

@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %u\n", strtoul(buf, &bp, 0));
@end example

@c ----------------------------------------------------------------------
@node strupr, string
@heading @code{strupr}
@subheading Syntax

@example
#include <string.h>

char *strupr(char *string);
@end example

@subheading Description

This function converts all lower case characters in @var{string} to
upper case. 

@subheading Return Value

@var{string}

@subheading Example

@example
char buf[] = "Foo!";
strupr(buf);
@end example

@c ----------------------------------------------------------------------
@node strxfrm, locale
@heading @code{strxfrm}
@subheading Syntax

@example
#include <string.h>

size_t strxfrm(char *s1, const char *s2, size_t max);
@end example

@subheading Description

This copies characters from @var{s2} to @var{s1}, which must be able to
hold @var{max} characters.  Each character is transformed according to
the locale such that @code{strcmp(s1b, s2b)} is just like
@code{strcoll(s1, s2)} where @code{s1b} and @code{s2b} are the
transforms of @code{s1} and @code{s2}. 

@subheading Return Value

The actual number of bytes required to transform @var{s2}, including the
@code{NULL}. 

