home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / LK_V1.06.LHA / LK V1.06 / HELP / amigalibrary.hlp < prev    next >
Encoding:
INI File  |  1994-11-01  |  6.1 KB  |  170 lines
  1. [LANGUAGE english; PARENT keywords; PAGE 11-6]
  2. [C;6;B]        AMIGALIBRARY or AL
  3. [7]Default: normal executable
  4. [J;1;N]
  5.   NOTE: if this flag is set (or one of the LIBFD, LIBID, \
  6. LIBPREFIX, LIBREVISION or LIBVERSION instructions is used,) \
  7. lk supposes that you want to use the default 'library.o' \
  8. file. Any file which contains the '_LibraryBase' symbol \
  9. (XDEF) will replace the default lk object. lk will \
  10. link that file as the first object and it must be of \
  11. type code. If such symbol does not exist, lk will first \
  12. check for 'LK:LIB/library.o', if that file does not \
  13. exist, the internal one will be used instead. The \
  14. default lk header file does not handle Slink or DICE \
  15. required initialisations.
  16.   Another solution is to use the DEFINE instruction \
  17. to forbid the usage of the default library with:
  18.     DEFINE _LibraryBase=0
  19.  
  20.   This instruction supposes that you are creating an Amiga \
  21. library (like those present into your LIBS: path.) lk will \
  22. automatically generates the table list for the function \
  23. jumps from the corresponding file description ('.fd' file.) \
  24. The name of the '.fd' file will be defined with the LIBFD \
  25. instruction or from the destination file name. The name of \
  26. the library will be the destination file name.
  27.   If you have to define private functions into the file \
  28. description, you should define them with the names \
  29. 'private1', 'private2', etc... and use the DEFINE \
  30. instruction to redirect them on your functions:
  31.     DEFINE private1=<my function1 name>
  32.     DEFINE private2=<my function2 name>
  33.     ...
  34.  
  35.   If you need to receive the parameters on the stack \
  36. you will use LIBSTACKPARAM instruction. By default lk \
  37. supposes that your functions receive registers.
  38.  
  39.   The version and revision numbers of the library are \
  40. defined through the instructions LIBVERSION and LIBREVISION. \
  41. Those will also define the __LIBRARYVERSION and \
  42. __LIBRARYREVISION symbols respectivly. Both values \
  43. are used to define the library identification as well \
  44. than the library version used to bump an open.
  45.  
  46.   The string identification will be defined throught \
  47. one of the COPYRIGHT or LIBID instructions. Only the \
  48. copyright is required because the remained is always \
  49. generated by lk. If no copyright is defined, the default \
  50. identification string is still created by lk.
  51.  
  52.   If you use the default library header given with lk, \
  53. you must define the following functions, and the \
  54. variable '_LibraryBase' is available to you. This \
  55. global variable contains the pointer of your \
  56. library which does not need to be opened by again, \
  57. and can always be used in replacement to the variable \
  58. called 'mylib' given in any of the following functions. \
  59. To avoid the usual auto-init/exit open/close code, you \
  60. may add a definition when you link:
  61.     DEFINE <lib base name>=_LibraryBase
  62. like for instance:
  63.     DEFINE _BOSBase=_LibraryBase
  64. [INDENT 5]
  65.   1. 'LibInit' which contains all necessary initialisations \
  66. for your library. Its C proto-type is:
  67.  
  68. [2]    extern struct Library * _LibInit(
  69. [R]        struct Library *mylib);
  70. [L;1]
  71.      If you have nothing to create, just type:
  72. [2]    long _LibInit(mylib)
  73.        struct Library *struct;
  74.        {
  75.           return (mylib);
  76.        }
  77. [J;1]
  78.      This function must return the library pointer \
  79. (mylib) to accept the library installation, otherwise \
  80. return null (failed) and the complete library will be \
  81. freed by the system. This function should avoid calls \
  82. to other functions of the library.
  83.      If your compiler support register definition you \
  84. may defines 'mylib' as register D0 (and A6 is SysBase.)
  85.  
  86.   2. 'LibOpen' which contains the necessary initialisations \
  87. for each new open intented by user. The system will increment \
  88. the open counter by one when this routine does not fail. \
  89. Its C proto-type is:
  90.  
  91. [2]    extern struct Library * _LibOpen(
  92. [R]        struct Library *mylib);
  93. [L;1]
  94.      If you have nothing to allocate, just type:
  95. [2]    long _LibOpen(mylib)
  96.        struct Library *struct;
  97.        {
  98.           return (mylib);
  99.        }
  100. [J;1]
  101.      This function must return the library pointer if the \
  102. library has been opened with success.
  103.      If your compiler supports register definitions you \
  104. may defines 'mylib' as register D0.
  105.  
  106.   3. 'LibClose' which contains the necessary destructors. \
  107. The system will decrement the open counter by one. Its C proto-type \
  108. is:
  109.  
  110. [2]    extern BOOLEAN _LibClose(
  111. [R]        struct Library *mylib);
  112. [L;1]
  113.      If you have nothing to free, just type:
  114. [2]    long _LibClose(mylib)
  115.        struct Library *struct;
  116.        {
  117.           return (0);
  118.        }
  119. [J;1]
  120.      This function must return FALSE if the library does \
  121. not have to be expunged. Do not forget that you cannot \
  122. expunge your library until all users closes it (however \
  123. the expunge code check the counter.)
  124.      If your compiler supports register definitions you \
  125. may defines 'mylib' as A6.
  126.  
  127.   4. 'LibExpunge' which contains the necessary destructors \
  128. to free the library from memory. If this function is not \
  129. defined lk assume that no expunge is available and the \
  130. default LibExpunge will be used (it does nothing!) Its \
  131. C proto-type is:
  132.  
  133. [2]    extern long _LibExpunge(
  134. [R]        struct Library *mylib);
  135. [L;1]
  136.      If you have nothing to destroy, just type:
  137. [2]    long _LibExpunge(mylib)
  138.        struct Library *struct;
  139.        {
  140.           return (1);
  141.        }
  142. [J;1]
  143.      This function must return FALSE if the library cannot \
  144. be expunged. Otherwise it will return any non zero value \
  145. and the system expunge function will free the library \
  146. memories (base and segment list.) The system expunge \
  147. function automatically prevents the destruction while \
  148. some users still access the library.
  149.      If your compiler supports register definitions you \
  150. may defines 'mylib' as A6.
  151. [INDENT]
  152. [5]
  153.     IMPORTANT:
  154.  
  155.   In the LibInit() and LibExpunge() functions, you MUST \
  156. avoid the usage of the DOS filer system, otherwise the \
  157. Forbid()/Permit() of the system are lost and the system may \
  158. crash.
  159. [1]
  160.   See also:
  161. [L;3][LINK copyright]            COPYRIGHT
  162. [LINK fdlib]                FDLIB
  163. [LINK libfd]                LIBFD
  164. [LINK copyright]            LIBID
  165. [LINK libprefix]            LIBPREFIX
  166. [LINK version]                LIBREVISION
  167. [LINK version]                LIBVERSION
  168. [LINK version]                VERSION
  169. [5; LINK about; GOTO address]        Become Registred
  170.