OSLib – Open source API for RISC OS development

OSLib Frequently Asked Questions

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.

Questions

Copyright and Licencing

Use of OSLib

Compiler Issues

Compatibility Issues

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.

What is OSLib's license ?

OSLib is now licensed under the GNU General Public Licence (GPL) version 1, or (at your option) any later version with the following clarification and special exception:

Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination.

As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obliged to do so. If you do not wish to do so, delete this exception statement from your version.

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 here and elsewhere, 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 releasing your work under an Open Source approved license. 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 6.00 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 6.30, 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 ?

This is answered in a separate page on How to use OSLib ?.

top Home

Which compilers and assemblers does OSLib support ?

This is answered in a separate page on compiler and assembler support.

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 ?

There are two well known ABIs used in RISC OS : APCS-R and APCS-32. 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 does not make a difference for building for APCS-R or APCS-32. The difference is made in its build settings. The binary distribution in all pre-OSLib 7.00 releases contains two 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.

OSLib 7.00 releases onwards are APCS-32 only and APCS-R support is dropped for good.

So by using OSLib32 (APCS-32), you are supporting the 32-bit architectures, as well the 26-bit ones.

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.

Site Contents