BBC Small-C Functions ------------------------------- Release 0.73, xx-xxx-2005, J.G.Harston -------------------------------------- Original by A.J.Travis, 01-May-89 --------------------------------- -------------------------------------------------------------------------- NAME fopen SYNOPSIS FILE *fopen(name, mode) char *name; char *mode; DESCRIPTION Attempts to open a file. If mode is "w", the file is first deleted, if it exists, then opened for writing. If mode is "r", the file is opened for reading. If the file could not be opened, then NULL is returned. Otherwise, the file descriptor is returned. --------------------------------------------------------------------------- NAME fclose SYNOPSIS fclose(fp) FILE *fp; /* (pseudo) i/o stream pointer */ DESCRIPTION Closes the file pointed to by fp. -------------------------------------------------------------------------- NAME fgets SYNOPSIS char *fgets(s, n, fp) char *s; int n; /* maximum number of characters */ FILE *fp; DESCRIPTION Reads in characters from the file pointed to by fp, up to a maximum of n into the string s. Entry is terminated by either a '\n' character, a '\r' character or n characters being read in. DELETE (character 127) deletes the previous character, if not at the begining of the string. Returns the read string, or NULL if EOF was encountered before anything else. NOTES With version 0.7, DELETE does not decrease the count of characters read in, so if 10 characters are asked for, and five characters are entered, then five DELETE characters, the function terminates. Also, when the routine terminates on overflow, the end marker is a bit dodgy. -------------------------------------------------------------------------- NAME fputs SYNOPSIS fputs(s, fp) char *s; FILE *fp; DESCRIPTION Outputs the string s to the file pointed to by fp. If the output is to stdout or stdout, then any '\n' characters are converted to '\r' characters. -------------------------------------------------------------------------- NAME creat SYNOPSIS FILE *creat(name, pmode) char *name; /* filename */ int pmode; /* ignored in v0.70 */ DESCRIPTION Attempts to create a file for output using osfind &C0, and returns the file decriptor, or -1 if the attempt was unsuccessful. -------------------------------------------------------------------------- NAME open SYNOPSIS FILE *open(name, rwmode) char *name; /* filename */ int rwmode; /* mode of opening */ DESCRIPTION Attempts to open the named file using osfind, first checking that it exists. The method of opening is controlled by rwmode: rwmode = 0 /* open for input */ rwmode = 1 /* open for output (deletes old file) */ rwmode = 2 /* open for input and output */ Returns -1 if the file doesn't exist, otherwise the file descriptor is returned. -------------------------------------------------------------------------- NAME close SYNOPSIS close(fd) FILE *fd; /* file decriptor */ DESCRIPTION Closes the file pointed to by fd using osfind 0. -------------------------------------------------------------------------- NAME read SYNOPSIS int read(fd, buf, count) FILE *fd; /* file descriptor */ char *buf; /* address of buffer */ int count; /* number of bytes to read */ DESCRIPTION Reads in data into memory pointed to by buf, using osgbpb 4. Before transfering anything, tests the status of the file, and returns 0 if it is at EOF. Otherwise, it returns the number of bytes actually transfered. If this is less than the number requested, then the end of the file has been hit. The data is read from the current PTR value. NOTES Version 0.7 does not have the ability to read from stdin with this call. -------------------------------------------------------------------------- NAME write SYNOPSIS int write(fd, buf, count) FILE *fd; /* file descriptor */ char *buf; /* address of buffer */ int count; /* number of bytes to write */ DESCRIPTION Writes data out from memory pointed to by buf, using osgbpb 2, or to the standard output or error output. Returns the number of bytes transfered. NOTES If writing to stdout or stderr, then '\n' is converted to "\r\n". This can cause problems when sending a "\n\r" sequence to a file which gets converted to "\r\n\r", but has no visual effect. Returns the number of bytes transfered. -------------------------------------------------------------------------- NAME getc SYNOPSIS int getc(fd) FILE *fd; /* file descriptor */ DESCRIPTION Reads a byte from the file, or stdin, returning -1 if EOF occured. NOTES Version 0.7 sign extends the character received. This makes character 255 into -1, exactly the same as EOF. When reading from stdin, the characters are echoed to the screen. -------------------------------------------------------------------------- NAME putc SYNOPSIS putc(c, fd) char c; /* character */ FILE *fd; /* file descriptor */ DESCRIPTION Writes a character out to a file or the standard output or error output. NOTES When writing to stdout or stderr, '\n' is converted to "\r\n". This means that a "\n\r" sequence becomes "\r\n\r". -------------------------------------------------------------------------- NAME gets SYNOPSIS char *gets(s) char *s; DESCRIPTION Reads in a string from stdin into the string s. Input is terminated by either a NULL (character 0) or a '\n' (character 10). No length checking is done, so make sure that s has enough space researved for it for the longest string that you expect. -------------------------------------------------------------------------- NAME puts SYNOPSIS puts(s) char *s; DESCRIPTION Puts the string s out to stdout, followed by a '\n'. -------------------------------------------------------------------------- NAME printf SYNOPSIS printf(fmt, arg) char *fmt; /* output format */ int arg; /* argument list */ DESCRIPTION Sends output to stdout by calling fprintf. See below. -------------------------------------------------------------------------- NAME fprintf SYNOPSIS fprintf(fp, fmt, arg) FILE *fp; /* output stream */ char *fmt; /* output format */ int arg; /* argument list */ DESCRIPTION Sends output to a file. See _doprint(). -------------------------------------------------------------------------- NAME sprintf SYNOPSIS char *sprintf(s, fmt, arg) char *s; /* output string */ char *fmt; /* output format */ int arg; /* argument list */ DESCRIPTION Writes output into a string. Returns the output string. See _doprint(). -------------------------------------------------------------------------- NAME _doprint SYNOPSIS _doprint(buf, fmt, arg) char *buf; /* output buffer */ char *fmt; /* output format */ int *arg[]; /* argument list */ DESCRIPTION The internal function called by the printf functions. The character exceptions recognised are: %d print decimal %x print lower case hex %X print upper case hex %d, %x and %X can be padded with n counts of character c using %ncx, for example, %02x. %s print string %c print character \n newline character (10) \r return character (13) \t tab character (9) \0 null character (0) \0nnn character 0nnn (where 0nnn is an octal number) NOTES For more detailed descriptions of the printf functions, see a good C reference book (eg Kernighan & Ritchie). -------------------------------------------------------------------------- NAME scanf SYNOPSIS scanf(fmt, arg) char *fmt; int arg; DESCRIPTION Reads input from stdin by calling fscanf(). See _doscan() below. -------------------------------------------------------------------------- NAME fscanf SYNOPSIS fscanf(fp, fmt, arg) FILE *fp; char *fmt; int arg; DESCRIPTION Reads input from a file. See _doscan() below. -------------------------------------------------------------------------- NAME sscanf SYNOPSIS sscanf(s, fmt, arg) char *s; char *fmt; int arg; DESCRIPTION Reads input in from a supplied string. See _doscan() below. -------------------------------------------------------------------------- NAME _doscan SYNOPSIS _doscan(fp, buf, fmt, arg) FILE *fp; /* input stream */ char *buf; /* i/o buffer */ char *fmt; /* conversion format */ int *arg[]; /* argument list */ DESCRIPTION The internal function called by the scanf functions. The character exceptions recognised are: %d read a decimal number %x read a hex number %c read a character %s read a string NOTES For a more detailed description of the scanf functions, see a good C reference book, (eg Kernighan & Ritchie). -------------------------------------------------------------------------- NAME _cmdinit SYNOPSIS _cmdinit(enter) unsigned enter; /* entry point (should be int *()) */ DESCRIPTION Extracts the command line arguments from the invocation text and stores them in memory. The routine then calls the enter entry point with argc and argv as parameters. The entry point is usually main(). NOTES Because of a bug in the compiler, the array of string pointers (char *argv[];) is treated as an array of integers (int argv[];). This means that each offset contains two characters. This is not a problem if you just compare the strings to other strings, but if you want to check an individual character, like the '-' preceding command options, you need to mask out the top with if ((argv[n] & 0xff) == '-') Where this occurs in the source programs it is marked /* BUG in compiler */ -------------------------------------------------------------------------- NAME toupper, tolower, toascii SYNOPSIS char toupper(c); char c; char tolower(c); char c; char toascii(c); char c; DESCRIPTION Standard C functions, normally defined as macros, but this implementation defines them as built-in functions for speed and compactness. -------------------------------------------------------------------------- NAME exit SYNOPSIS exit(status) int status; /* exit value */ DESCRIPTION Exits from user program. The exit status is passed to osbyte 1. -------------------------------------------------------------------------- NAME unlink SYNOPSIS unlink(name) char *name; /* filename */ DESCRIPTION Deletes the named file using osfile 6. -------------------------------------------------------------------------- NAME stat SYNOPSIS int stat(name, fcb) char *name; /* filename */ int *fcb; /* file control block */ DESCRIPTION Uses osfile 5 to get information on the named file. Returns -1 if no file exists, and 0 if one does. The file control block is filled with the following data: fcb[0] & 0xFF file type: 1=file, 2=directory, 255=run only fcb[1] load address low 2 bytes fcb[2] load address high 2 bytes fcb[3] execute address low 2 bytes fcb[4] execute address high 2 bytes fcb[5] length low 2 bytes fcb[6] length high 2 bytes fcb[7] & 0xFF access byte fcb[7] & 0x1F00 day of month file created fcb[7] & 0xE000 (year-1981) bits 6 to 4 fcb[8] & 0x0F month file created fcb[8] & 0xF0 (year-1981) bits 3 to 0 fcb[8] & 0xFF00 undefined -------------------------------------------------------------------------- NAME system SYNOPSIS int system(string) char *string; /* command string */ DESCRIPTION Passes a string to the system oscli routine. The return value in osbyte 1 is returned. NOTE This doesn't spawn a subprocess, just passes on control. If the command is a language initialisation or a Small-C program, there won't be a return. Also, be careful with the *compact and *backup commands as they use the main memory as workspace, and will so write over the executing program, if it is not a ROM-based one. -------------------------------------------------------------------------- NAME itoa SYNOPSIS int itoa(n, s, base) unsigned n; /* input value */ char *s; /* output buffer */ int base; /* conversion base */ DESCRIPTION Converts the supplied number to a string in s, using the supplied conversion base. The function returns the number of digits in the converted string. -------------------------------------------------------------------------- NAME atoi SYNOPSIS int atoi(s) char *s; /* The string to convert */ DESCRIPTION Converts the string s into an integer. Converts in decimal, unless the string starts with 0x (eg 0xff20) where hexadecimal is used, ignoring the case of any letters, or 0 (eg 0377) where octal is used. This means than decimal numbers should not have any preceding zeros. --------------------------------------------------------------------------