st

Algorithms for Image Processing and Computer Vision Source Code

@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