OSLib Frequently Asked Questions

Site Contents

This page summarizes some of the most frequently asked questions regarding the operation and use of OSLib. We hope it will be helpful. If you have any questions that are not covered here, please feel free to ask on the OSLib-users mail-list.

Who owns the Copyright in OSLib?

Jonathan Coxhead wrote OSLib as a private project during he time that he was employed by Acorn. He is the sole copyright owner of the library, together with the OSLib maintainers who share the copyright of certain aspects of the package. OSLib is now in the public domain under the GNU General Public Licence (GPL), nonetheless, we ask you to respect Jonathan's copyright.

Can I distribute my proprietary applications built with OSLib?

The GNU General Public Licence stipulates that any program which embodies any GPL code must itself be distributed under the terms of the GPL. In particular this means that source code must be made available for any such program. This is clearly unacceptable for any proprietary, commercial, code.
The GNU Lesser General Public Licence relaxes this requirement somewhat in only requiring that binary object files be freely available, thus protecting investment in proprietary code to some extent.
The OSLib copyright owner has relaxed even this requirement, as explained elsewhere and any code linked with OSLib may be distributed in whichever way the developer sees fit. In other words, OSLib may be freely used in the construction of proprietary software. However, do please consider joining the ever increasing free software movement, by placing your work in the public domain. Free source is good; hoarded source bad!

What are wide file handles and why are 8-bit handles retained?

OSLib originally defined file handles to be 8 bits wide. This was based on inside knowledge of the OS, and even under RISC OS 4, no file handle greater than &FF is ever issued. However, the PRMs do specify that file handles should be 32 bits wide for future compatibility.
This has left the OSLib maintainers with a bit of a dilemma. It is our faithful promise to never break an existing interface, but, clearly, the present situation could not be allowed to continue.
OSLib V6.0 went some way to resolving the problem by defining a 32 bit file handle, OS_FW, and a set of functions to use it. The intention is that they would be used in place of the legacy OS_F and its associated functions. However, many users felt this was non-intuitive behaviour, and pleaded for the return of OS_F, but in a 32-bit guise. Unfortunately, it was impossible to simply change the type of OS_F, because that would cause many programs to break if they relied on 8 bit file handles.
The problem was finally resolved in OSLib V6.3, by adding extra header files which, by default, makes OS_F a synonym of OS_FW, and does likewise with their associated functions. However, it leaves OS_F and its friends as symbols in the library, to allow legacy code to be linked correctly. Therefore, any new compilations will, by default, use 32-bit file handles, but 8-bit compatibility is assured.
One further refinement to this scheme is that this name translation can be disabled by defining the constant OSLIB_F8, which will cause the headers to revert to their previous behaviour, and thus allowing anyone who particularly needs to retain 8-bit handles to do so. This is best achieved by passing -DOSLIB_F8 in any makefile or command line when invoking the compiler.

top Home

Why are file sizes and os_t typed as signed ints?

A rule has been adopted throughout OSLib that any 32-bit field upon which arithmetic can be performed is typed as a signed int. This makes it straightforfard to do comparisons. It is acknowledged that using an unsigned int gives an extra bit of information in the absence of a long long int, but this would be at the expense of usability, and therefore considered a bodge. If you really need the extra range, cast it to unsigned yourself.
Regarding os_t, code such as the following from PRM 3-185, is made much simpler with a signed int, and correctly handles wrap-around - which an unsigned wouldn't:
os_t newtime = os_read_monotonic_time();
while ((newtime-oldtime) > 0 )
   oldtime += 100;

top Home

What command line should I use for compiling or assembling a program using OSLib?

There is really nothing special about using OSLib with C or assembler programs.
A generalised command line for Acorn (Norcroft) C using standard C, OSLibSupport, and OSLib would be something like this:

cc -IC:,OSLibSupport:,OSLib: C:o.stubs OSLib:o.OSLib OSLibSupport:o.OSLibSupport -o program.o program.c
or:
cc -IC:,OSLibSupport:,OSLib: -c program.c -o program.o link program.o C:o.stubs OSLib:o.OSLib OSLibSupport:o.OSLibSupport -output program

For GCC (with UnixLib) this becomes somewhat simpler with the compile and link steps merged:

gcc program.c -I OSLib: -I OSLibSupport: OSLib:o.OSLib OSLibSupport:o.OSLibSupport -o program
or:
gcc -I OSLib: -I OSLibSupport: -c program.c -o program gcc program.o OSLib:o.OSLib OSLibSupport:o.OSLibSupport -o program

ObjASM doesn't seem to be able to expand path variables in the command line, so it is necessary to bodge things a bit:

do ObjASM -I <OSLibPath> program.s program.o link program.o -output program

The GCC assembler can get invoked by:

gcc -I OSLib: -I OSLibSupport: -c program.s -o program.o gcc program.o OSLib:o.OSLib OSLibSupport:o.OSLibSupport -o program

top Home

Which compilers does OSLib support?

OSLib is, with one exception, completely compiler independent. It was originally built and used using the Acorn (Norcroft) compiler, and many people are successfully using it with GCC and GC++.

top Home

Why does my compiler reject the __swi symbol?

The Acorn (Norcroft) compiler reserves the special symbol "__swi", as an optimizing hint. Other compilers don't recognise it, and fault it. Also, for some reason best known to themselves, when using Acorn's compiler through CFront, it also faults __swi. In these instances you need to define the symbol to nothing by placing "#define __swi" in your code files before #including any OSLib headers, or by putting -D__swi in any command line or makefile command when calling your compiler.

top Home

Templates in other C++ libraries clash with some typedefs/structures in OSLib

This problem is evident wen using CathLibCPP (map.h) with OSLib (os.h) under CFront, when the map field clashes. There appears to be a problem with Cfront (its template handling was never very good) which causes a template name to clash with other symbols. As a work-round try the following:
#define map addr
#include "os.h"
#undef map
#include "map.h"
#define map addr

top Home

Does OSLib support 32-bit architectures?

OSLib can be built using APCS-R and APCS-32 ABIs. The former can only be used for running on 26-bit architectures, while the latter can run on both 26-bit and 32-bit architectures. APCS-R is deprecated and it is recommmended to have your programs built using APCS-32 for future compatibility with new ARM hardware.
The OSLib source code is identical for either. The binary distribution contains two ALF images: OSLib (APCS-R) and OSLib32 (APCS-32). The 32 bit version does not preserve the caller's processor flags, the 26 bit one does; this may raise compatibility issues when migrating from one to the other so choose the correct one you're linking.
Note that the last version of APCS-R OSLibSupport is 6.70. All later versions of OSLibSupport library are APCS-32 only.
It is expected that OSLib 7.00 release will be APCS-32 only and that APCS-R support will be dropped for good.

top Home

Why does my toolbox application crash when linked with OSLib and tboxlibs?

Never do that! Whilst the syntax of the OSLib toolbox calls may look similar to those provided by Acorn's tboxlibs, they are subtly different in the parameters they pass. Unless you really know what you're doing, and can guarantee which one is called, never mix the two libraries. OSLib provides a complete, and better, coverage of the toolbox API, and there is no need to use tboxlibs.

top Home