intro - introduction to the BASIC run-time support library


ld options files /usr/lib/basic/libbasic.a -lm -lc


This section describes the functions, formats and symbols which implement the run-time behavior of Basmark BASIC.  BASIC resembles f77 in that complex functionality is within the bounds of the language whereas C delegates this functionality to “external” libraries of functions.  Libbasic provides this functionality along with the math and C libraries. 

The BASIC run-time support library works invisibly with basic(1) and, along with the BASIC code generator and UNIX libraries, accomplishes all the tasks possible with BASIC.  Thus one need not typically refer to this section.  However, when code written in another language is to be integrated with a BASIC program, it becomes necessary to have some knowledge of the inner workings of BASIC.  This may occur, for example, if the programmer needs to use a tightly coded assembler routine or has available a FORTRAN statistics package or perhaps wants to gain access to UNIX system functions using a C routine. 


The casual user is warned that the use of the information in this section requires expertise in areas other than the BASIC language.  Competence in C programming is assumed as is familiarity with programming in a UNIX environment.  The reader who is venturing into this realm for the first time will find the example in call(stmt) to be a good introduction. 

This section should make BASIC a “good neighbor” to the other UNIX languages, but the methods described here remain trade secrets of Basmark


The functions and formats described in this section are labeled for the categories of operations they implement:

formats given by include files

conversion of values between types and formats

run-time errors

I/O operations

machine dependent operations (involving absolute addresses)

mathematical functions

chaining, terminal dependent operations, files, date and time

string functions

Naming Conventions

Libbasic function names resemble, as closely as possible, the BASIC statements and functions they implement with the following notable differences: the names are in lower case with the ‘$’ (dollar) at the end of BASIC string function names replaced by ‘S’ (capital s).  Names are limited to six characters.  Names that would collide with UNIX function names are prepended with ‘b’ (small b).  Differences also occur when a BASIC statement and BASIC function have the same name, when a BASIC function name has more than one meaning, and when functionally is embedded in BASIC without an alphabetic name.  In these cases names are chosen rationally but there is no pattern. 

Symbol Names

One must avoid collisions with symbol names used by BASIC.  One must avoid names used by the UNIX math and C libraries and this library.  Also, the names of BASIC subprograms must be avoided.  Finally, all names beginning with a capital letter are reserved; these include names beginning with a capital B used by the code generator for communication with the library, names beginning with a capital C which are COMMON block names and names beginning with INT, FLT, DBL and STR which are the transliterations of the names and types of USR functions.  If an error should occur in the code generator such that a name is used but is left undefined, the name will be made external.  If this object file is linked with a module which contains a symbol with the same name, no error will be detected and the resultant executable will be linked improperly. 

The names of the symbols defined by the code generator and the library are:

            Bargc      chain      err      lset      setalarm

Data Types

BASIC integers are implemented as C short integers which are 16-bit 2’s complement quantities.  BASIC single-precision and double-precision floating point numbers are handled as C floats and doubles, respectively.  Most systems implement floating point numbers according to ANSI/IEEE Standard 754-1985, but there is no guarantee of this.  A BASIC string is implemented with a C structure for the header with space allocated (except for constants and “fielded” strings) by malloc(3) (see string(inc)). 

Error Handling

Most errors that occur in the use of the functions in this library are semantic and readily detected.  These error conditions are handled with runerr (see runerr(err)) and are cataloged under the DIAGNOSTICS sub-heading on the pages of this section. 

Other errors generally can not be anticipated and are the result of error conditions detected by UNIX system calls.  These errors are handled by mapping the UNIX error number, errno (see intro(2)), into the most appropriate BASIC error number.  Although code could be written to produce the UNIX error number, the following list describes the mapping to help the user discover which UNIX error code caused the BASIC error condition:

                  BASIC Error            UNIX Error
  5Illegal function call  1Not owner
  5Illegal function call13Permission denied
  6Overflow34Result too large
  7Out of memory12Not enough space
11Division by zero33Math argument
53File not found  2No such file or directory
58File already exists17File exists
61Disk full28No space left on device
64Bad file name21Is a directory
70Disk Write Protect30Read-only file system
71Disk not Ready  6No such device or address
72Disk Media Error  5I/O Error




call(stmt), string(inc), runerr(err)
basic(1) in the Supplemental Documentation section
malloc(3), intro(2) in the UNIX Programmer’s Manual

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber