View source for C in RISC OS

<hr>

<h3>Introduction</h3>

<p>The workings of C with RISC&nbsp;OS and its interactions with
various libraries often raise many questions.  All too often these
questions are incompletely answered, leading to more questions or
confusion.  This document attempts for the first time to fully explain
all the concepts in an understandable way.</p>

<p></p>

<h3>Standards</h3>

<p>C is defined by a number of standards.  Probably the most important
one is the ANSI C standard. Among other things, this defines what
functionality must be present in a standard C library implementation.
When the &quot;Shared C Library&quot; is referred to on RISC&nbsp;OS we
are talking about the library developed by Acorn which is ANSI compliant.</p>  

<p>The Shared C Library (SCL) resides in a module in ROM (or RAM if it's softloaded)
and is called by C programs linked to it via &quot;stubs&quot; (see below).
It also provides other functionality required by a C program such as stack
extension and general environment interaction.</p>

<p>POSIX is another standard which defines a considerable number of
behaviour characteristics of Unix operating systems.  Since these are
invarialy C-based, it also defines many C functions that should be
provided by a POSIX-compliant system.</p>

<p>The SCL makes no attempt to implement any functions beyond
those defined by ANSI - indeed it was never intended that it should - but UnixLib
does implement many of these, along with all the functions found in the SCL.
Because of this, UnixLib can be invaluable when making Unix programs
work on RISC&nbsp;OS</p>

<p>While it is certain that UnixLib doesn't conform fully to POSIX, it
makes a good effort, and it is being improved all the time.</p>   

<p></p>

<h3>Programs and Libraries</h3>

<p>When a program is linked (the final stage where the executable is
produced), the program will be linked to one of two things - SCL stubs,
or UnixLib.</p>

<p>Stubs are a small piece of code that is accessed by your program when
making a function call to a C function in the SCL occurs for the first time.
Stubs &quot;fix up&quot; the call, and point it directly at the appropriate
code in the <i>SharedCLibrary</i> module.  The advantage of this is that the
code is shared by all callers, and not duplicated for all programs.  It also
means that when a bug fix occurs, all programs benefit.</p>

<p>On the other hand, when a program is linked to UnixLib, all the library code
used by a program from Unixlib is attached to your program.  This explains why
UnixLib programs end up bigger than ones linked with SCL.  This is referred
to as statically linked.</p>

<p>There is one exception to this.  UnixLib relies on the module
<i>SharedUnixLibrary</i>.  This module implements a small amount of
functionality that cannont safely be put into an application.  It is
hoped that one day more functionality will move into this module to
give the same advantages that the SCL module does.</p>

  
<p></p>

<h3>Compilers and Libraries</h3>

<p>By default, Norcroft uses the SharedCLibrary, and GCC uses UnixLib.
LCC also uses SharedCLibrary by default.</p>

<p>In some cases, it's appropriate that the compiler use the alternate
library.  As with all libraries, these are split into the library's headers
which advertise their functionality, and the library itself, which contains
the code.  The following describes use of each library with the 3 compilers</p>

<ul>
 <li><b>GCC</b>
  <dl>

   <dd>
    <p>Inside the !gcc application are contained headers and library files
    for both UnixLib and SharedCLibrary.  The latter is a free version
    which is functionally identical to the version supplied with Norcroft (with
    a few additions).</p>

    <p>Normal invocation will use Unixlib:</p>

    <pre>
      gcc hello.c -o hello
    </pre>

    <p>Use the -mlibscl switch to use SCL:</p>

    <pre>
      gcc -mlibscl hello.c -o hello
    </pre>

    <p>Note that in older versions of GCC, this switch was -mstubs.</p>
   </dd>
  </dl> 
 </li>

 <li><b>LCC</b>

  <dl>
   <dd>
    <p>LCC is supplied with the same SCL files as are supplied with
    GCC in order to make it a stand-alone compiler.</p>

    <p>Normal invocation will use SCL:</p>

    <pre>
      lcc hello.c -o hello
    </pre>

    <p>Use the -Bunix switch to use UnixLib:</p>

    <pre>
      lcc -Bunix hello.c -o hello
    </pre>

    <p>This assumes that UnixLib is actually available.  Currrently,
    UnixLib is only distributed as part of the !gcc application (in
    the past it wasn't).  There are plans to make a stand-alone version
    for LCC and Norcroft.  For more details, see LCC's !Help file.
    </p>  

   </dd>
  </dl> 
 </li>

 <li><b>Norcroft</b>
  <dl>
   <dd>
    <p>Norcroft is supplied with SharedCLibrary files.</p>

    <p>Normal invocation will use SCL:</p>

    <pre>

      cc hello.c -o hello
    </pre>

    <p>To use UnixLib:</p>

    <pre>
      cc -jUnix: -IUnix: hello.c -o hello
    </pre>

    <p>As for lcc, this assumes the presence of UnixLib.  The comments
    in LCC's !Help file apply equally in this case.
    </p>

   </dd>
  </dl> 
 </li>
</ul>

<p>In bigger programs, compiling and linking is usually split into two
operations.  You should ensure that you use the same flags at each
point, otherwise you will have unexpected results.</p>

<p></p>


<h3>Mixing Libraries and Compilers</h3>

<p>Sometimes it is convenient to try and mix object files or libraries
compiled with one compiler or targeted against different C libraries.</p>

<p>In general, I would discourage this, unless you know what you are
doing.  The reasons are as follows:</p>

<ul>
 <li><p>The size of the FILE structure varies between SharedCLibrary and
     UnixLib, as UnixLib has to hold more data to implement some POSIX
     functionality.  This means that programs accessing members of this
     structure will run into trouble.  Although this is quite rare,
     you should be aware of it.</p>

 <li><p>The file descriptors stdout, stdin and stderr referring to standard
     streams are declared differently in SharedCLibrary and UnixLib
     headers.  This is responsible for the mysterious missing symbol
     &quot;__iob&quot; sometimes seen at link.</p>

 <li><p>Compilers may define some maths operations in terms of differently
     named functions - in particular, division - so that even if object
     files are compiled against the C library, you may see link errors
     if you mix output from two different compilers.</p>

</ul>

<p>This is not to say that mixing output is not impossible - it is, with
care, but you should take note of the differences.</p>

<hr>