The new release of OSLib, version 5.0, is available on the Acorn FTP 
server. 

   OSLib is a set of functions and C headers to provide complete 
coverage of the RISC OS application programmer's interface from C. It 
provides access from C code to all SWI calls which is 

      efficient: often, memory access is completely avoided; 
      type-safe: every argument can be type-checked by the compiler; 
      obvious: a SWI is called by the "obvious" syntax; 
      complete: every SWI is covered; 
      register-safe: hides register allocation; 
      language-independent: although the headers are specific to C, the 
         library is not - any APCS-conformant language can call it. 

It also provides names for all the data structures and reason codes used by 
the A P I. Code that uses it is superior to the same code using 
_kernel_swi() or _swix(), both in terms of the compile-time checking 
that is available, and the size and speed of the code generated. 

   There is also a complete set of help files using StrongHelp to 
provide function prototypes, constant values and structure definitions 
at your fingertips from Zap or StrongEd. If you haven't tried this, do - 
it's really good! The feature requires StrongHelp, SparkFS and either 
Zap or StrongEd, none are which are supplied. 

   In addition, all the coding examples from PRM vols 1-3 and 5 have been 
translated into OSLib-based C, and there is a ReadMe file which contains more 
information. 

   These files are to be found at site ftp.acorn.co.uk in directory 
/pub/riscos/releases/oslib. Although this is Acorn's F T P site OSLib is 
*not* an Acorn product: it is free software. For support information, 
see the last paragraph. 

   There are many changes since the last release: see the ChangeLog for 
details. The most major are: 

 * Support for the RISC O S 3.6 A P I (as released with the A7000) and 
some Acorn expansion cards, including all the Toolbox functions, CD, 
CDFS, SCSI, SCSIFS, Freeway, ShareFS, Socket, NFS, 16-bit sound, 
DrawFile, ColourPicker, JPEG, CompressJPEG, Portable. 

 * There are now (well) over 77 headers, so they have been split into 4 
directories. After running SetVars, use -IOS: on the cc command to pick 
up the headers, and link with OSLib:o.OSLib. See the ReadMe file for a 
way of using StrongHelp with more than 77 help files in its help 
directory. 

 * Added *lots* of new type names (most of which are defined as |int| or 
|bits|) and 'Values:' sections to help on types. (See, e g, the help on 
|wimp_colour|.) In most cases, this allows you in a single click to see 
all the values that are allowed in a given argument position. For 
example, given the prototype for os_read_mode_variable(), you can find 
out the names of the legal mode variables. Moved some filing system 
constants into "fileswitch.h" to support this. 

 * Add |const| qualifiers in places where they are valid, i e, where the 
function takes a pointer to an object which it does not use to modify 
the object. 

 * Moved most of the macros in "types.h" into a new "macros.h," in 
response to popular demand. 

 * Use inline SWI's where possible: 252 out of 2429 SWI veneers happen 
to be A P C S-conformant, and may be replaced by single SWI instructions 
in the caller. Only supported by Norcroft C release 5, but enabled by 
default: IF YOU ARE NOT USING NORCROFT C RELEASE 5 OR LATER, you must 
disable the feature by using the -D__swi option on the compiler command 
line (e g, 

      cc -D__swi c.progfile 

with a hyphen, a capital 'D', 2 underscores, and 'swi' in lower case). 
The reason this feature is experimental is that the relevant flavour of 
A P C S requires that function calls should preserve flags, which is not 
guaranteed (an inlinable SWI will always be an x-clear SWI, and will 
therefore definitely clear V). If this is a problem in practice, the 
feature will be reviewed; however, it is believed that all RISC O S 
SWI's preserve Z, N and that the compiler does not make use of V, C. 

   Thanks to everyone who has helped by submitting fault reports, and 
especially to Simon Middleton of Uniqueway Ltd who performed heroic 
feats on the toolbox headers. 

   OSLib is copyright ) 1994, 1995 Acorn Computers Ltd. It is 
distributed in the hope that it will be useful, but without any 
warranty; without even the implied warranty of merchantability or 
fitness for a particular purpose. 

   Fault reports and suggestions for improvement may be sent to the 
author, Jonathan Coxhead <jcoxh...@acorn.co.uk>. Although this is an 
Acorn address, OSLib is not a formally supported Acorn product.