

SLB(5)                    Programmer's Manual                     SLB(5)




pNAMEq
        SLB shared library file format

pDESCRIPTIONq
        An  SLB  shared  library  is  a  normal GEMDOS executable with a
        specific start of the text segment:
        
        typedef
        {
        	long magic;
        #define SLB_MAGIC	0x70004afcL
        	char *name;
        	long version;
        	long flags;
        	void (*slb_init) (void);
        	void (*slb_exit) (void);
        	void (*slb_open) (BASPAG *);
        	void (*slb_close) (BASPAG *);
        	long opt;
        	long res[8];
        	long fun_cnt;
        	long fun_table[];
        } SLB;
        
        It is recommended that bit 3 of byte 25 of the program header is
        set to indicate that the module can be loaded into a TPA of "any
        sufficient" size.    This  will  help  preventing  memory  frag-
        mentation  under  MagiC, see prunopts(1)q for a description of ex-
        isting program   flags.      prunopts(1)q   is   available    from
        http://www.muenster.de/~reschke/soft_e.hmtl#mupftool.

        magic
                must be the first four octets of the text segment and be
                equal to pSLB_MAGIC.q

        name
                is a pointer (relative to the start of the text segment)
                to  a  C  style  string  with  the  name  of  the shared
                library.

        version
                is  the  version  number  of  the  shared  library  (see
                pSlbopen(2)q ).

        flags
                is reserved and must be set to 0 for now.

        slb_init
                is  a  pointer  to  the  init  function  of  the  shared
                library.   This  function  gets  called  once  when  the
                library  is  initially  loaded and is executed under the
                context of the  shared  library  (MagiC)  or  the  first
                caller's program  (MetaDOS).  This call will be executed



Atari TOS                 Release: 1998-09-24                     Page 1




SLB(5)                    Programmer's Manual                     SLB(5)



                in supervisor mode.
                The path name of the shared library file  is  passed  in
                the command  line  area of the SLB's basepage.  Contrary
                to a GEMDOS process, the string is in C format  (no  in-
                itial length  byte,  zero  terminated).   An SLB can use
                this information to find additional files in the  direc-
                tory from where the SLB was loaded.  Note that this file
                name  might contain a relative path and thus needs to be
                evaluated during slb_init.

        slb_exit
                is  a  pointer  to  the  exit  function  of  the  shared
                library.   It  gets  called before the shared library is
                unloaded from memory (because the last owner has  closed
                it)  and  is  executed  under  the context of the shared
                library  (MagiC)  or  the     first   caller's   program
                (MetaDOS).  This  call  will  be  executed in supervisor
                mode.

        slb_open
                points to  the  SLB  open  function.    It  gets  called
                everytime a process opens the shared library.  A pointer
                to  the  caller's  basepage  is  passed  on  the  stack.
                Depending on the operating system,  this  call  will  be
                executed  in  supervisor  mode  (MetaDOS)  or  user mode
                (MagiC).

        slb_close
                points to the  SLB  close  function.    It  gets  called
                everytime  a process closes  the shared library (or ter-
                mininates without explicitly closing it).  A pointer  to
                the caller's basepage is passed on the stack.  Depending
                on the operating system, this call will be  executed  in
                supervisor mode (MetaDOS) or user mode (MagiC).

        opt
                is reserved.

        res[]
                is reserved.

        fun_cnt
                is the total number of library function pointers.  It is
                used  to  do  a sanity check on the number argument when
                the shared library is called.

        fun_table[]
                is an array with the pointers to the  individual  shared
                library functions, starting with function 0. Note that a
                function pointer may be zero, in  which case the library
                exec function will return EINVFN.
                Shared  library  functions  will  be  receive parameters
                exactly in the way the caller passed  them.    The  only
                difference  is  that the library function will receive a



Atari TOS                 Release: 1998-09-24                     Page 2




SLB(5)                    Programmer's Manual                     SLB(5)



                pointer to the caller's  BASEPAGE  instead  of  the  SLB
                pointer as first argument.

pCAVEATq
        Note  that  under  plain  TOS,  the  same restrictions apply for
        shared library usage as for  GEMDOS  allocated  memory  or  file
        handles: accessories aren't real GEMDOS processes, the ownership
        thus belongs to the currently running GEMDOS process.

pBUGSq
        The  command  line area of the basepage is limited to 128 bytes,
        thus the name of the SLB file needs to fit into 127 characters.

pSEE ALSOq
        runopts(1), Slbopen(2)










































Atari TOS                 Release: 1998-09-24                     Page 3


