LIBSROFF

(SROFF Support Library)

Contents

 


* INTRODUCTION TO LIBSROFF

The LIBSROFF library is intended to help those who which to develop utility software that manipulates SROFF based files (SROFF is the object format used within the QDOS and SMS family of operating systems). It provides a standard set of routines that carry out some of the analysis and manipulation of the SROFF library so that users of this library do not have to write such functionality for themselves.

The LIBSROFF library was actually developed while building new versions of the C68 linker and associated utilities that manipulate SROFF libraries. These programs all use the LIBSROFF library themselves to avoid unnecessary duplication of effort to develop similar code in each of the relevant programs.

The LIBSROFF library provides a large number of methods and properties that allow you to manipulate all aspects of a SROFF file. For most purposes you will not need to use the vast majority of these methods and properties, but they are available if needed.

 

LIBLIST library

The LIBSROFF library internally makes use of the LIBLIST library to build up the internal memory structures used to store SROFF information by the various LIBSROFF functions. This means it is necessary to have a copy of the LIBLIST library available at the time you link any program that uses the LIBSROFF library. The actual details of how the LIBSROFF makes use of the LIBLIST library are hidden within the internal routines, so it is not necessary to understand how the LIBLIST library works to use the LIBSROFF library at a very superficial level. There were various changes in some of the parameters passed between early releases of the LIBLIST library, so you must have Release 1.2 or later.

Having said that, it is quite likely that the sort of program that is going to make use of the LIBSROFF library is also going to want to be able to navigate the various lists that are built up in memory by the LIBSROFF FileLoad and ModuleLoad() routines. These lists are all in the format maintained by the LIBLIST library, and the LIBLIST library supplied functions should be used to navigate these lists.

 


 

* USING THE LIBSROFF LIBRARY

 

Files Supplied

When you get this library, you should have the following files provided:

LIBSROFF.HTM Documentation in HTML format for LIBSROFF library
SROFF.HTM Document in HTML format covering SROFF specification
SROFF.H Header file for use with library (packed format)
SROFF.HDR Annotated (unpacked) version of above header
LIBSROFF.A Statically linked version of library
SROFFSRC.ZIP Source of the LIBSROFF library as a ZIP archive.

Note that you will also need a copy of the LIBLIST library. This is supplied as a separate item, and is not included in the files supplied with the LIBSROFF library.

The MAKEFILE file that is provided within the SROFFSRC.ZIP source archive already has the relevant entries to allow you to build the following alternative versions of the LIBSROFF library

 

Source File Implications

In your source files you must include the libsroff.h header file supplied with this library in any module that is going to make use of any of the methods that are part of this library. This is done by including a line of the form

#include <libsroff.h> in your source at an appropriate point.

It is also possible to define the macro LIBSROFF_MACROS if you want maximum efficiency and speed. One way that this can be done is by inserting a line in your source code of the form

#define LIBSROFF_MACROS somewhere before including the libsroff.h header file. Another way is to define this macro via the command line when running your compiler. Typically this is done by including a parameter of the form
-DLIBSROFF_MACROS although the exact syntax sometimes varies between different compilation systems.

The effect of defining the LIBSROFF_MACROS macro is to cause inline code to be generated for many of the LIBSROFF library calls rather than really making library calls. This will maximise speed and keep code size to a minimum. The downside is that all parameter checking is by-passed, so you should only use this feature if you are sure that your code is bug free.

 

Linking implications

You need to tell the linker that it needs to search the LIBSROFF library to find the routines that you have used. The exact format of the linker commands depends on which variant of the LIBSROFF library you decide to use:

 

Standard version

This is a normal statically linked version of the library, and is provided as the file LIBSROFF.A. To tell the linker to use this version of the library, then you need to give it some additional parameters. The exact format can vary between linkers, but it is likely to be something like:

-lsroff -llist This will result in a version of the program that is optimised for runtime efficiency, and has no dependency on any external files being present at runtime. Note that the above parameters have also specified that the LIBLIST library (available separately) should be searched after the LIBSROFF library. This order is important.

 

Debug Version

If you are doing any detailed manipulation of the low level SROFF format then you could easily make simple logic errors. The debugging version of this library helps identify such problems by including extensive internal checks against you misusing the library and providing silly parameter values. This is extremely useful while in the development phase of a program. The penalty is that there is significantly more overhead in terms of program size, memory usage and processing overhead while using the debugging version of the library.

To use the debugging version of the library that is provided in the file libsroffD.a file you need to provide parameters to the linker to get it searched for required routines. The exact format of the parameter can vary according to the linker used, but would typically be something like:

-lsroffd -llistd to the LD linker. Note that the suggested command line above includes the debugging versions of both the LIBSROFF and the LIBLIST libraries.

While you are using the debugging version of the library, if any of the internal checks fail then your program will be stopped and an assert style message displayed indicating the point at which the error was detected. The text of the assert message will display the details of the internal check that failed. These messages are designed to be largely self-explanatory.

Once you have finished debugging your program, then by simply changing the parameter provided to the LD linker you can switch to a non-debugging version of the library.

 

RLL version

The RLL version of the library can only be used for programs that are to run on QDOS (or compatible) systems. It allows the necessary routines to be picked up dynamically at runtime from a separately loaded RLL library.

To tell the linker to use the RLL variant of the library you need to add the following options to the end of the linker command line (after any of your own object files):

-rsroff -lsroff -rlist -llist Note that both the RLL and standard versions of the libraries are specified. This is to allow for the fact that there are still a few routines (at this release anyway) that can only be statically linked, and so are not present in the RLL version of the library. The order of the parameters is also important to ensure that the ELM versions of the libraries are searched before the non-RLM versions.

To be able to use the version of the program generated using the RLL libraries, then it is necessary to have a copy of the LIBSROFF.RLL and LIBLIST.RLL files at runtime. The user will also need to have the Runtime Link Manager (or RLM) loaded on his system. The RLM is supplied as part of the RLL system to provide runtime support for loading and using RLL libraries.

 


LIBSROFF DATA TYPES

The LIBSROFF library defines some specific data types for use within the LIBSROFF library. These data types can be treated as "objects" that are manipulated by the LIBSROFF library methods and properties. The application programmer should not consider directly accessing the internal details of these objects. Instead they are manipulated using functions supplied with the LIBLIST library (for the list types) and LIBSROFF library (for the remainder). This separation makes it easier to change the internal details of any future release of the LIBSROFF library, while at the same time maintaining the interface exposed to user programs. It also means that application code that uses this library tends to be much cleaner in design and easier to follow.

The actual SROFF specific data types defined are as follows:

 
SROFF_FILE This is a pointer to an object that is used to maintain information about an opened SROFF file.
SROFF_MODULE This is a pointer to an object used to maintain information in memory about a single SROFF module. A typical program object file will only contain a single module, but libraries nearly always contain multiple modules.
SROFF_SECTION This is a pointer to an object used to maintain information in memory about a single SROFF section. This level of information is maintained at module scope, so such information is linked to and accessed via a SROFF_MODULE data type.
SROFF_XDEF This is a pointer to an object used to maintain information in memory about a particular external definition (XDEF). This level of information is maintained with module scope, so such information is linked to and accessed via a SROFF_MODULE data type.
SROFF_XREF This is a pointer to an object used to maintain information in memory about a particular external reference (XREF). This level of information is maintained at section scope, so is always linked to and accessed via a SROFF_SECTION data type.
SROFF_OPER This is a pointer to an object used to maintain information in memory about the operations associated with resolving a particular external reference (XREF). This level of information is maintained at XREF scope, so is always linked to and accessed via a SROFF_XREF data type.
SROFF_ID This is an object used to maintain information in memory about a particular ID. The ID type of data structure can be linked to several of the other data types. However in most cases a method is also supplied to get the name associated with an ID, so the user can often ignore this data type. However manipulating the data structures via the ID tends to be slightly more efficient than navigating them via the name associated with an ID.
SROFF_COMMENT This is a pointer to an object used to maintain information in memory about any comments that were in the SROFF object file. Comments are an optional feature of the SROFF object file format.

These object types are all declared within the libsroff.h header file. Access to their contents is always via the properties defined for use with each data type. No assumptions should be made about the internal structure of these objects as this may change between different releases of the LIBSROFF library. All access to these objects should be via the methods and properties that are defined within the LIBSROFF library.

 


Methods

The descriptions of the methods that are available for the LIBSROFF library are organised as follows:

 
Input_Methods_Summary Methods that relate to loading into memory details from existing SROFF files
Output Methods Summary Methods that relate to creating a new SROFF file.

Note that there are a few methods that are listed in both the Input Methods Summary and Output Methods Summary as they can be used in both contexts.

Input Methods Summary

The following is a summary list of the input related methods provided by the LIBSROFF library.

Scope Method Name Description
File SROFF_FileOpen Open an existing SROFF file for reading
SROFF_FileClose Close a previously opened SROFF file
SROFF_FileLoad Load a complete SROFF file into memory from file
SROFF_FileFree Free memory resources for a loaded SROFF file
SROFF_FileReadByte Read a byte from a SROFF file
SROFF_FileReadLong Read a long from a SROFF file
SROFF_FileReadShort Read a short from a SROFF file
SROFF_FileReadString Read a SROFF string from a SROFF file
Module SROFF_ModuleLoad Load a single SROFF module into memory from file
SROFF_ModuleFree Release memory resources for a previously loaded module

Output Methods Summary

The following is a summary list of the input related methods provided by the LIBSROFF library. In this context, output means creating new SROFF related structures in memory as well as actually writing an SROFF file.

Scope Method Name Description
File SROFF_FileClose Close a previously created or opened SROFF file
SROFF_FileFree Free memory resources for a loaded SROFF file
SROFF_FileNew Create a new SROFF file object in memory.
SROFF_FileReopen Reopen a SROFF file to use a different physical file.
SROFF_FileRewind Reset a SROFF file to the beginning.
SROFF_FileWrite Write an SROFF file that is loaded into memory
SROFF_FileWriteByte Write a byte to a file
SROFF_FileWriteShort Write a short to a file
SROFF_FileWriteLong Write a long to file
SROFF_FileWriteString Write a SROFF string to a file
SROFF_FileWriteData Write data to a SROFF file
SROFF_FileOptimise Optimise a file already loaded into memory
SROFF_FileModuleAdd Add a module a SROFF file object
SROFF_FileCommentAdd Add a comment to a SROFF file object
Module SROFF_ModuleFree Release memory resources for a previously loaded module
SROFF_ModuleNew Create a new SROFF_MODULE object.
SROFF_ModuleCommentAdd Add a SROFF_COMMENT object to a module
SROFF_ModuleSectionAdd Add a SROFF_SECTION object to a module
SROFF_ModuleXdefAdd Add a SROFF_XDEF object to a module
SROFF_ModuleWrite Write a single SROFF module from memory to file
SROFF_ModuleOptimise Optimise a SROFF module already loaded into memory
Comment SROFF_CommentNew Create a new empty SROFF_COMMENT object.
Section SROFF_SectionNew Create a new empty SROFF_SECTION object
SROFF_SectionCommentAdd Add a SROFF_COMMENT object to a section
SROFF_SectionDataAdd Add data to a section.
SROFF_SectionXrefAdd Add a SROFF_XREF object to a section.
Xdef SROFF_XdefNew Create a new empty SROFF_XDEF object.
Xref SROFF_XrefNew Create a new empty SROFF_XREF object
SROFF_XrefOperAdd Add a SROFF_OPER object to a Xref
Oper SROFF_OperNew Create a new empty SROFF_OPER object

* LIBSROFF Properties

The descriptions of the properties that are available for the LIBSROFF library are organised as follows:

Reading Properties_Summary Methods that relate to loading into memory details from existing SROFF files
Setting Properties Summary Methods that relate to creating a new SROFF file.

Reading Properties Summary

The following is a summary list of the readable properties provided by the LIBSROFF library.

Scope Property Name Description
File SROFF_FileNameGet Get filename for a SROFF file object
SROFF_FileModulesGet Get list of modules for a file
SROFF_FileCommentsGet Get list of comments for a file
Module SROFF_ModuleNameGet Get the name of a module
SROFF_ModuleInfoGet Get additional info for a module
SROFF_ModuleCommentsGet Get list of comments for a module
SROFF_ModuleSectionsGet Get list of sections for a module
SROFF_ModuleXdefsGet Get list of XDEFs for a module
Comment SROFF_CommentTextGet Get text of a comment
SROFF_CommentLengthGet Get length of a comment
SROFF_CommentOffsetGet Get offset in section of comment
SROFF_CommentSectionGet Get section containing the Comment
Section SROFF_SectionIdGet Get the ID for a given section
SROFF_SectionIsDefined Find out if section already defined
SROFF_SectionDataGet Get the start of the data for the section
SROFF_SectionSizeGet Get the size of the data for the section
SROFF_SectionXrefsGet Get the list of XREFs for a given section
SROFF_SectionOffsetGet Get the offset of a given XREF
SROFF_SectionTypeGet Get the type of a given XREF
Xdef SROFF_XdefIsDefined Find if a XDEF is defined
SROFF_XdefIdGet Get the Id for a given XDEF
SROFF_XdefNameGet Get the name for a given XDEF
SROFF_XdefOffsetGet Get the Offset for a given XDEF
Xref SROFF_XrefOffsetGet Get the offset value of an XREF.
SROFF_XrefIsDefined Find out if an XREF is defined
SROFF_XrefIsSigned Find out whether result is signed.
SROFF_XrefIsUnsigned Find out whether result is signed.
SROFF_XrefOpersGet Get list of opers for a given XREF
SROFF_XrefRelocRuleGet Get the relocation rule for an XREF
SROFF_XrefSignedGet Get the sign for an XREF
SROFF_XrefTruncSizeGet Get size for result of XREF
Oper SROFF_OperOpGet Get the op for a given OPER
SROFF_OperIdGet Get the ID for a given OPER
Id SROFF_IdIsDefined See if given ID is defined
SROFF_IdIsSection Does the given ID refer to a section
SROFF_IdIsSymbol Does the given ID refer to a symbol
SROFF_IdTypeGet Get the type for a given ID
SROFF_IdNameGet Get the Name for a given ID
SROFF_IdSectionGet Get the section for a given ID

 

Setting Properties Summary

The following is a summary list of the writable properties provided by the LIBSROFF library.

Scope Property Name Description
File SROFF_FileNameSet Set filename for a SROFF_FILE object
Module SROFF_ModuleNameSet Set the name of a module
SROFF_ModuleInfoSet Set additional info for a module
Comment SROFF_CommentTextSet Set text of a comment
SROFF_CommentLengthSet Set length of a comment
SROFF_CommentOffsetSet Set offset in section of comment
SROFF_CommentSectionSet Set section containing the Comment
Section SROFF_SectionIdSet Set the ID for a given section
SROFF_SectionOffsetSet Set the offset of a given XREF 
SROFF_SectionTypeSet Set the type of a given XREF 
Xdef SROFF_XdefIdSet Set the Id for a given XDEF
SROFF_XdefNameSet Set the name for a given XDEF
SROFF_XdefOffsetSet Set the Offset for a given XDEF
Xref SROFF_XrefOffsetSet Set the offset value of an XREF.
SROFF_XrefRelocRuleSet Set the relocation rule of an XREF
SROFF_XrefSignedSet Set the sign for an XREF
SROFF_XrefTruncSizeSet Set the size of that an XREF resolves to
Oper SROFF_OperOpset Set the op for a given OPER
SROFF_OperIdSet Set the ID for a given OPER
Id SROFF_IdTypeSet Set the type for a given ID
SROFF_IdNameSet Set the Name for a given ID
SROFF_IdSectionSet Set the section for a given ID

 


METHODS and PROPERTY DESCRIPTIONS

The following is an alphabetical list of all the methods and properties that are available in the LIBSROFF library.

 


int SROFF_CommentLengthGet (SROFF_COMMENT pComment)

Property that returns the length of a comment. The SROFF standard allows comments to contain NULL characters, so if you simply use the SROFF_CommentTextGet property and use strlen() to find its length you may miss data beyond any embedded NULL characters. You will only need to use this property in cases where such embedded NULL characters are a possibility - normally comments restrict themselves to printable text. If any error occurs then an appropriate (negative) error code will be returned.

 


int SROFF_CommentLengthSet (SROFF_COMMENT pComment, int length)

Set this property to specifies the length of a comment. The SROFF standard allows comments to contain NULL characters, so you need to set this property for such comments before you use the SROFF_CommentTextSet property or you will miss data beyond any embedded NULL characters. You will only need to use this property in cases where such embedded NULL characters are a possibility - normally comments restrict themselves to printable text. If any error occurs then an appropriate (negative) error code will be returned.

 


SROFF_COMMENTSROFF_CommentNew (void)

Method that creates a new SROFF_COMMENT object.

On success an empty SROFF_COMMENT object will be returned, and on a failure NULL will be returned, and the global error variable errno set to an appropriate error code.

The object returned will then need to be added at either the module level using the SROFF_ModuleCommentAdd method (which is the normal level within SROFF) or at the file level using the SROFF_FileCommentAdd method (which is an extension to the normal SROFF standard).

 


long SROFF_CommentOffsetGet (SROFF_COMMENT pComment)

Property that gives the offset within the section within which the comment occurs. Normally a comment will not occur within a section but will instead be at module level. If any error occurs or the comment was not within a section then an appropriate (negative) error code will be returned.

 


int long SROFF_CommentOffsetSet (SROFF_COMMENT pComment, long Offset)

Set this property to specify the offset within the section within which the comment occurs. Normally a comment will not occur within a section but will instead be at module level. On success, SROFF_ERROR_NONE will be returned and if any error occurs then an appropriate error code will be returned.

 


SROFF_SECTIONSROFF_CommentSectionGet (SROFF_COMMENT pComment)

Property that returns a SROFF_SECTION object if the comment occurred within a section. If an error occurred, or the comment was not within a section, then NULL is returned and the global error variable errno set to an appropriate error code.

 


int SROFF_CommentSectionSet (SROFF_COMMENT pComment, SROFF_SECTION pSection)

Set this property to specify the section within which a comment occurred. If an error occurred, or the comment was not within a section, then NULL is returned and the global error variable errno set to an appropriate error code.

 


char * SROFF_CommentTextGet (SROFF_COMMENT pComment)

Property that gives the text of the specified comment. If any error occurs then NULL will be returned instead.

 


int SROFF_CommentTextSet (SROFF_COMMENT pComment, char * Text)

Set this property to specify the text of the given comment. If at the time this property is set, the SROFF_CommentLengthGet property is zero, then it will be assumed that this is a C style NULL terminated string, and the SROFF_CommentLengthGet property will also be set appropriately. If the SROFF_CommentLengthGet property is non-zero, then the Text will be assumed to be of that length. If any error occurs then NULL will be returned instead.

 


int SROFF_FileClose (SROFF_FILE pSroffFile);

Method that closes a file previously opened using SROFF_FileOpen method. It will release all memory resources associated with that file. On completion, the pSroffFile pointer will no longer be valid for use. If this routine completes without error, then it will return 0. If for any reason an error occurs, then the relevant error code will be returned. However, the pSroffFile pointer should still be considered invalid as the data structures linked to it could be in an inconsistent state.

 


int SROFF_FileCommentAdd (SROFF_FILE pSroffFile, SROFF_COMMENT pComment);

Method to add a SROFF_COMMENT object to an existing SROFF_FILE object

If this routine completes without error, then it will return SROFF_ERROR_NONE. If for any reason an error occurs, then the relevant error code will be returned.

 


list_t SROFF_FileCommentsGet (SROFF_FILE pSroffFile)

Property that gives the list of comments associated with the current file. If there are no comments at this level (which would normally be the case), then NULL is returned. If there are comments, then a pointer to the list will be returned. The nodes within the list will be of type SROFF_COMMENT. Note that the support for file level comments is an extension to the SROFF standard that only specifies comments within a module context.

 


int SROFF_FileFree (SROFF_FILE pSroffFile);

Method to release all resources associated with a currently loaded SROFF_FILE object. It is rarely used directly as it is called implicitly whenever you use the SROFF_FileClose method.

If this routine completes without error, then it will return SROFF_ERROR_NONE. If for any reason an error occurs, then the relevant error code will be returned. However, the pSroffFile object should still be considered invalid as the data structures linked to it could be in an inconsistent state.

 


int SROFF_FileLoad (SROFF_FILE pSroffFile);

Method to read into a memory all modules in the given SROFF file.

On success, the number of modules read in will be returned. This could potentially be 0 if the SROFF file is empty. If any failure occurs, then an (always negative) error code will be returned.

 


int SROFF_FileModuleAdd (SROFF_FILE pSroffFile, SROFF_MODULE pModule);

Method to add an SROFF_MODULE object to an existing SROFF_FILE object.

If this method completes without error, then it will return SROFF_ERROR_NONE. If for any reason an error occurs, then the relevant error code will be returned.

 


list_t SROFF_FileModulesGet (SROFF_FILE pSroffFile)

Property that gives the list of modules associated with the current file. It would normally be used after a SROFF_FileLoad method had been used. If there are no modules, then NULL will be returned, and otherwise a pointer to the list will be returned. The nodes within the list will be of type SROFF_MODULE.

 


char * SROFF_FileNameGet (SROFF_FILE pSroffFile)

Property that gives the filename associated with a SROFF_FILE object.

On success returns a pointer to the filename and on failure returns NULL with the global error variable errno set to indicate the error condition.

 


int SROFF_FileNameSet (SROFF_FILE pSroffFile, char * FileName)

Setting this property sets the filename associated with a SROFF_FILE object. It is only relevant if you are later intending to do a SROFF_FileWrite or SROFF_ModuleWrite method for a file that has not already been opened.

 


SROFF_FILE SROFF_FileNew (void);

Method to create a new SROFF_FILE object in memory. It is used when it is needed to build up a new set of SROFF structures in memory from scratch rather than reading them from an existing SROFF file.

On success an empty SROFF_FILE object will be returned, and on a failure NULL will be returned, and the global error variable errno set to an appropriate error code.

 


SROFF_FILE SROFF_FileOpen (char * FileName);

Method to open an SROFF file ready for use with SROFF_FileLoad or SROFF_ModuleLoad routines.

If there are any problems opening the file, then NULL will be returned, and the global error variable errno will contain an error code. This could be one of the LIBSROFF specific ones, or a standard system error code depending on what was the cause of the failure.

 


int SROFF_FileOptimise (SROFF_FILE pSroff);

Method to optimise an SROFF file already loaded into memory with the SROFF_FileLoad method.

On success (which should normally be the case) this method will return SROFF_ERROR_NONE. If there is any failure then an appropriate error code will be returned.

Optimisation involves omitting any references to sections or symbols that are defined but then never used. The AS68 assembler always inserts entries to define TEXT, DATA and UDATA sections even if they are not used within the file. This makes the resulting SROFF files larger than is strictly speaking necessary.

 


int SROFF_FileReadByte (SROFF_FILE pSroffFile, char * pTarget)

Method to read a byte from the given SROFF file into the given location. Works correctly regardless of whether the char data type is signed or unsigned for the compiler in use. Returns SROFF_ERROR_NONE on success, and an appropriate error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileReadLong (SROFF_FILE pSroffFile, long * pTarget);

Method to read a long from the given SROFF file into the given location. Will work correctly regardless of the byte order on the machine. Returns SROFF_ERROR_NONE on success and an appropriate error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileReadShort (SROFF_FILE pSroffFile, short * pTarget);

Method to read a short from the given SROFF file into the given location. Will work correctly regardless of the byte order on the machine. Returns SROFF_ERROR_NONE on success and an appropriate error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileReadString (SROFF_FILE pSroffFile, char * pTarget);

Method to read a SROFF string from the given SROFF file into the given location. The target should be of at least SROFF_MAX_STRING_LENGTH+1 in size (this constant is defined in the libsroff.h header file) to guarantee it is large enough to hold the largest string that can be returned. The length byte that is present in the SROFF file is not written to pTarget, but is checked as being within range of the legal values allowed for a SROFF string. A NULL byte will be appended to the end. Returns string length on success, and an appropriate (negative) error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileReopen (SROFF_FILE pSroffFile, char * filename);

Method that reopens a file previously opened using SROFF_FileOpen method to use a different underlying phsycial file. All resources attached to the pSroffFile will be left intact. It will typically used just before doing a SROFF_FileWrite to write out a new file, although it is not limited to this use. If this routine completes without error, then it will return 0. If for any reason an error occurs, then the relevant error code will be returned. However, the pSroffFile pointer should now be considered invalid as the data structures linked to it could be in an inconsistent state.

 


int SROFF_FileRewind (SROFF_FILE pSroffFile);

Method that resets a file previously opened using SROFF_FileOpen method to the start. All resources attached to the pSroffFile will be left intact. It will typically used just before doing a SROFF_FileWrite to write out a changed file overwriting the original. If this routine completes without error, then it will return 0. If for any reason an error occurs, then the relevant error code will be returned. However, the pSroffFile pointer should now be considered invalid as the data structures linked to it could be in an inconsistent state.

 


long SROFF_FileWrite (SROFF_FILE pOutputFile);

Method to write all the modules that have been loaded by previous SROFF_FileLoad or SROFF_ModuleLoad methods on the given target file, or have been created by starting with a SROFF_FileNew method and building up the structures programatically..

 


int SROFF_FileWriteByte (SROFF_FILE pFile, char * pSource)

Method to write a byte to the given file from the given location. Will work correctly regardless of whether the char data type is treated as signed or unsigned by the compiler in use. Returns SROFF_ERROR_NONE on success and an appropriate error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileWriteData (SROFF_FILE pFile, char * pSource, size_t Length)

Method to write data to the given file from the given location. Will automatically write any bytes whose value is SROFF_DIRECTIVE_FLAG out twice as required by the SROFF standard. Returns SROFF_ERROR_NONE on success and an appropriate error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileWriteLong (SROFF_FILE pSroffFile, long * pSource);

Method to write a long to the given file from the given location. Will work correctly regardless of the byte order on the machine. Returns SROFF_ERROR_NONE on success and an appropriate error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileWriteShort (SROFF_FILE pSroffFile, short * pSource);

Method to write a long to the given SROFF file from the given location. Will work correctly regardless of the byte order on the machine. Returns SROFF_ERROR_NONE on success and an appropriate error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


int SROFF_FileWriteString (SROFF_FILE pSroffFile, char * pSource, size_tLength);

Method to write a SROFF string to the given SROFF file from the given location. Will automatically add the required length byte at the start of the string as it writes it to the file. Returns SROFF_ERROR_NONE on success and an appropriate (negative) error code on failure.

It would be rare for this method to be used directly - mainly it is expected to be used internally by the LIBSROFF library.

 


SROFF_ID SROFF_IdIsDefined (char * name, int type)

Property that lets you determine if an Id for a particular symbol name is defined. The type parameter is the same as the values that can be returned by the SROFF_IdTypeGet property mentioned above.

On success a SROFF_ID object for the Id found is returned, and on failure NULL is returned.

 


int SROFF_IdIsSection (SROFF_ID pId)

Property that is a (positive) non-zero value if the pId object refers to a section, and zero otherwise. If pId does not refer to a valid SROFF_ID object, then can also return a (negative) error code.

 


int SROFF_IdIsSymbol (SROFF_ID pId)

Property that is a (positive) non-zero value if the pId object refers to a symbol, and zero otherwise. If pId does not refer to a valid SROFF_ID object, then can also return a (negative) error code.

 


char * SROFF_IdNameGet (SROFF_ID * pId)

Property to give the name that corresponds to the given Id within the current module.

On success a pointer to a string containing the name will be returned. If you wish to use this name beyond the lifetime of the node specified in the pId parameter, then you should use the LIST_NameSpace_Use method from the LIBLIST library to register your usage. If there is any error then NULL will be returned and the global error variable errno set to indicate the error type.

 


int SROFF_IdNameSet (SROFF_ID pId, char * FileName)

Set this property to associate the given name with the specified id.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code.

 


SROFF_SECTION SROFF_SectionIdGet (SROFF_ID pId)

Property that gives the section that this ID refers to. On success a pointer to a SROFF_SECTION data object will be returned. On error NULL will be returned, and the global error variable errno set to indicate the error condition.

 


int SROFF_IdSectionSet (SROFF_ID pId, SROFF_SECTION pSection)

Set this property to specify the section that this ID refers to.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


int SROFF_IdTypeGet (SROFF_ID pId)

Property to get the operation type. It can be any of the following:

SROFF_ID_SYMBOL This ID refers to a symbol
SROFF_ID_SECTION This ID refers to a section
Can also return a (negative) error code if pId does not refer to a valid SROFF_ID object.

 


int SROFF_ModuleCommentAdd (SROFF_MODULE pModule, SROFF_COMMENT pComment);

Method to add a SROFF_COMMENT object to a previously existing SROFF_MODULE object. If this routine completes without error, then it will return 0. If for any reason an error occurs, then the relevant error code will be returned.

 


list_t SROFF_ModuleCommentGet (SROFF_MODULE pModule);

Property that lets you obtain a list of any comments that were embedded in the module. Comments are completely optional, but can be included at almost any point within a SROFF module. If there are no comments, then NULL will be returned, and otherwise a pointer to the list will be returned. The nodes within the list will be of type SROFF_COMMENT

 


int SROFF_ModuleFree (SROFF_FILE pSroffFile, SROFF_MODULE pModule);

Method to release all resources associated with a currently loaded module. If this routine completes without error, then it will return SROFF_ERROR_NONE. If for any reason an error occurs, then the relevant error code will be returned. In this case the pModule pointer should still be considered invalid as the data structures linked to it could be in an inconsistent state.

 


char * SROFF_ModuleInfoGet (SROFF_MODULE pModule);

Property that gives the Module additional information (if any). This is additional information that is inserted into a SROFF module as part of the SROFF SOURCE directive, but separated from the module name by a space. This is often not present, but some assemblers insert information such as the compilation date and time. Also some utility software might explicitly insert comment information into the module.

If present, then a pointer to the string containing the additional information is returned. If there is no additional information, then NULL is returned. . If you wish to use this string beyond the lifetime of the node specified in the pModule parameter, then you should the LIST_Namespace_Use method from the LIBLIST library to register your usage.

 


int SROFF_ModuleInfoSet (SROFF_MODULE pModule, char * Info);

Set this property to specify the Module additional information (if any). This is additional information that is inserted into a SROFF module as part of the SROFF SOURCE directive, but separated from the module name by a space. This is often not present, but some assemblers insert information such as the compilation date and time. Also some utility software might explicitly insert comment information into the module.

If at the time you try and set this property the Length property for the module is zero, then the Info parameter is assumed to point to a NULL terminated string and the Length property will also be set accordingly. If the Length property is non-zero, then it is assumed that the Info parameter may contain NULL bytes, and that the number of bytes specified by the Length property are relevant.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


void * SROFF_ModuleLoad (SROFF_FILE pSroffFile);

Method to read into a memory a single module from the given SROFF file. It is assumed that the module begins at the current offset into the SROFF file.

On success, a pointer to a SROFF_MODULE object will normally be returned, although occasionally an SROFF_COMMENT object can be returned. The setting of the global error variable errno will allow you to decide what type of object was returned as it will be set even on success as follows:

SROFF_ERROR_NONE This is the normal termination condition. In this case the pointer value returned will be to a SROFF_MODULE object.
SROFF_ERROR_COMMENT This termination code can occasionally happen. It indicates a comment was encountered at file level (i.e. outside a module). The pointer value returned will be to a SROFF_COMMENT object
SROFF_ERROR_NOMODULE The end-of-file was reached before a module was found. This is a normal condition as long as at least one module has already been successfully read from the file. If the end-of-file condition was encountered unexpectedly, then the SROFF_ERROR_EOF condition would be returned instead.
If any failure occurs, then NULL will be returned and the global error variable errno set to an appropriate (negative) error code.

 


char * SROFF_ModuleNameGet (SROFF_MODULE pModule);

Property that gives the name of the specified module.

On success a pointer to a string containing the name will be returned. If you wish to use this name beyond the lifetime of the node specified in the pModule parameter, then you should the LIST_NameSpace_Use method from the LIBLIST library to register your usage.

If there is any error then NULL will be returned and the global error variable errno set to indicate the error type.

 


int SROFF_ModuleNameSet (SROFF_MODULE pModule, char * ModuleName);

Set this property to specify the name of the given module.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


SROFF_MODULE SROFF_ModuleNew (void);

Method to create a new SROFF_MODULE object in memory. It is used when it is needed to build up a new set of SROFF structures in memory from scratch rather than reading them from an existing SROFF file.

On success a pointer to an empty SROFF_MODULE object will be returned, and on a failure NULL will be returned, and the global error variable errno set to an appropriate error code.

 


int SROFF_ModuleOptimise (SROFF_MODULE pModule);

Method to optimise an SROFF module already loaded into memory with the SROFF_FileLoad or SROFF_ModuleLoad methods.

Optimisation involves omitting any references to sections or symbols that are defined but then never used. The AS68 assembler always inserts entries to define TEXT, DATA and UDATA sections even if they are not used within the file. This makes the resulting SROFF files larger than is strictly speaking necessary.

 


int SROFF_ModuleSectionAdd (SROFF_MODULE pModule, SROFF_SECTION pSection);

Method to add a SROFF_SECTION object to a previously existing SROFF_MODULE object. If this routine completes without error, then it will return SROFF_ERROR_NONE. If for any reason an error occurs, then the relevant error code will be returned.

 


list_t SROFF_ModuleSectionsGet (SROFF_MODULE pModule);

Property that gives the list of sections associated with a particular module. On success a pointer to the list is returned. The list will consist of nodes of type SROFF_SECTION. On error NULL is returned and the global error variable errno set to an appropriate error code.

 


long SROFF_ModuleWrite (SROFF_FILE pOutputFile, SROFF_MODULE pModule);

Method to write a single module that has been loaded by previous SROFF_FileLoad or SROFF_ModuleLoad method calls to the given target file. The value of the optimise_flag parameter has the same meaning as defined for the SROFF_FileWrite method.

 


int SROFF_ModuleXdefAdd (SROFF_MODULE pModule, SROFF_XDEF pXdef);

Method to add a SROFF_XDEF object to a previously existing SROFF_MODULE object. If this routine completes without error, then it will return SROFF_ERROR_NONE. If for any reason an error occurs, then the relevant error code will be returned.

 


list_t SROFF_ModuleXdefsGet (SROFF_MODULE pModule);

Property that gives the list of external definitions (XDEFs) associated with a particular module. On success a pointer to the list is returned. The list will consist of nodes of type SROFF_XDEF. On error NULL is returned and the global error variable errno set to an appropriate error code.

 


SROFF_ID SROFF_OperIdGet (SROFF_OPER pOp);

Property that gives the SROFF_ID object associated with a particular SROFF_OPER object.

If any error occurs, NULL will be returned and the global error variable errno set to indicate the error condition.

 


int SROFF_OperIdSet (SROFF_OPER pOp, SROFF_ID pId);

Set this property to associate the given SROFF_ID a particular SROFF_OPER object.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


char SROFF_OperOpGet (SROFF_OPER pOp);

Property that gives the op operation type. It can be any of the following:

SROFF_OPER_PLUS The result of this op is to be added to the XREF value
SROFF_OPER_MINUS The result of this op is to be subtracted from the XREF value.

 


int SROFF_OperOpset (SROFF_OPER * pOp, char Op);

Set this property to define the operation type of the SROFF_OPER object specified by pOp. It can be any of the following:

SROFF_OPER_PLUS The result of this op is to be added to the XREF value
SROFF_OPER_MINUS The result of this op is to be subtracted from the XREF value.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


void * SROFF_SectionDataGet (SROFF_SECTION pSection);

Property that gives the start of the section data.

If there is no data or an error occurs, then NULL will be returned and the global error variable errno set to indicate the error condition.

 


SROFF_ID SROFF_SectionIdGet (SROFF_SECTION pSection);

Property returns the section id of the section specified by pSection.

If an error occurs, then NULL will be returned and the global error variable errno set to indicate the error condition.

 


int SROFF_SectionIdSet (SROFF_SECTION pSection, SROFF_ID pId);

Set this property to associate the given section id with the section specified by pSection.

Returns SROFF_ERROR_NONE on success, and an error code on failure.

 


SROFF_SECTION SROFF_SectionIsDefined (SROFF_MODULE pModule);

Property that lets you find out if a given section is already defined.

Returns a SROFF_SECTION object if it is, and NULL if it is not.

 


long SROFF_SectionSizeGet (SROFF_SECTION pSection);

Property that gives the size of the data associated with the section.

If an error occurs then the (negative) error condition will be returned instead..

 


int SROFF_SectionTypeGet (SROFF_SECTION pSection);

Property that gives the section type of the section specified by pSection. It can be any of the following:

SROFF_SECTION_PCREL The section is PC relative
SROFF_SECTION_COMMON The section is a Common section.
SROFF_SECTION_ABSOSLUTE The section is an absolute section. The value returned by SROFF_SectionValue method is the absolute address as an offset from 0.

 


int SROFF_SectionTypeSet (SROFF_SECTION pSection, int Type);

Set this property to set the type of a section. The Type parameter can be any of the following:

SROFF_SECTION_PCREL The section is PC relative
SROFF_SECTION_COMMON The section is a Common section.
SROFF_SECTION_ABSOSLUTE The section is an absolute section. The value returned by the SROFF_SectionValueGet method is the absolute address as an offset from 0.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


long SROFF_SectionValueGet (SROFF_SECTION pSection);

Property that gives value associated with the section specified by pSection. For an absolute section the value indicates the start address in memory. For a PC Relative or Common section, it represents the offset from the start of the section of the start of the data - normally this would be 0.

 


int SROFF_SectionValueSet (SROFF_SECTION pSection, long Value);

Set this property to set value associated with the given section. For an absolute section this indicates the start address in memory. For a PC Relative of Common section, this represents the offset from the start of the section of the start of the data - normally this would be 0.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


list_t SROFF_SectionXrefsGet (SROFF_MODULE pSection);

Property that gives the list of external references associated with a particular section. This list will consist of nodes of type SROFF_XREF.

If an error occurs, then NULL will be returned and the global error variable errno set to indicate the error condition. Note that this could be SROFF_ERROR_EMPTYLIST if there are no external references for this section.

 


SROFF_ID SROFF_XdefIdGet (SROFF_XDEF pXdef);

Property that gives the Id for a given external definition (XDEF).

If an error occurs, then NULL is returned and the global error variable errno set to indicate the error condition.

 


SROFF_XDEF SROFF_XdefIdDefined (SROFF_MODULE pModule, char * name);

This property allows you to determine if a given XDEF has already been defined.

Returns a pointer to a SROFF_XDEF object on success and NULL on failure.

 


int SROFF_XdefIdSet (SROFF_XDEF pXdef, SROFF_ID pId);

Set this property to specify the Id for a given external definition (XDEF).

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


char * SROFF_XdefNameGet (SROFF_XDEF pXdef);

Property to give the Name for a given external definition (XDEF). If an error occurs, then NULL is returned and the global error variable errno set to indicate the error condition.

 


int SROFF_XdefNameSet (SROFF_XDEF pXdef, char * XdefName);

Set this property to specify the Name for a given external definition (XDEF). If an error occurs, then NULL will be returned and the global error variable errno set to indicate the error condition.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


long SROFF_XdefOffsetGet (SROFF_XDEF pXdef);

Property to give the offset associated with a particular XDEF. For an absolute XDEF this will be an absolute address in memory, while for a relative XDEF this will be the offset from the start of the section to which the XREF belongs.

If an error occurs, then a (negative) error code will be returned.

 


>int SROFF_XdefOffsetSet (SROFF_XDEF pXdef, long Offset);

Set this property to specify the offset associated with a particular XDEF. For an absolute XDEF this will be an absolute address in memory, while for a relative XDEF this will be the offset from the start of the section to which the XREF belongs.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


int SROFF_XrefIsSigned (SROFF_XREF pXref);

Property that specifies whether the SROFF_XREF object referred to by pXref is signed.

On success returns a (positive) non-zero value.

If an error occurs, then a (negative) error code is returned, but this should not happen except perhaps in development mode.

 


int SROFF_XrefIsUnsigned (SROFF_XREF pXref);

Property that specifies whether the SROFF_XREF object referred to by pXref is unsigned. On success returns a positive non-zero value.

If an error occurs, then a (negative) error code is returned, but this should not happen except perhaps in development mode.

 


long SROFF_XrefOffsetGet (SROFF_XREF pXref);

Property that gives the fixed value (always positive) that is associated with the SROFF_XREF object that is specified by pXref. Except for absolute references, this will then normally be modified by a list of type SROFF_OPER operations.

If an error occurs, then an appropriate (negative) error code is returned.

 


int SROFF_XrefOffsetSet (SROFF_XREF pXref, long Value);

Set this property to specify the fixed value (always positive) that is associated with the SROFF_XREF object that is specified by pXref. Except for absolute references, this will then normally be modified by a list of type SROFF_OPER operations.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


list_t SROFF_XrefOpersGet (SROFF_XREF pXref);

Property that gives the list of operations that are needed to resolve this external reference. The list will consist of nodes of type SROFF_OPER. If any error occurs, then NULL will be returned and the global variable errno set to indicate the error condition. 

 


int SROFF_XrefRelocRuleGet (SROFF_XREF pXref);

Property that gives the Relocation Rule property.

On success it will be one of the following (positive) values:

SROFF_XREF_PCREL The result of this op is relative to the start address of the section.
SROFF_XREF_RELOC The result of this op requires runtime relocation.
If an error occurs, then a (negative) error code will be returned instead. An error would indicate something seriously wrong, so would not normally occur except perhaps while in development mode.

 


int SROFF_XrefRelocRuleSet (SROFF_XREF pXref, int TruncRule);

Set this property to specify the Truncation rule associated with the SROFF_XREF object that is specified by pXref. The value of TruncRule should be one of the following.

 
SROFF_XREF_PCREL The result of this op is relative to the start address of the section.
SROFF_XREF_RELOC The result of this op requires runtime relocation.

On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


int SROFF_XrefSignedGet (SROFF_XREF pXref);

Property that gives the signed/unsigned attributes for this XREF. On success it will be one of the following (positive) values:

SROFF_XREF_SIGNED The XREF result is signed
SROFF_XREF_UNSIGNED The XREF result is unsigned.
SROFF_XREF_NOTSIGNED This indicates that no sign value is set. Normally this is interpreted as being equivalent to the SROFF_XDEF_SIGNED value.
SROFF_XREF_BOTHSIGNS This indicates that both sign options are set. This should not ever occur as it would indicate that the SROFF generated is invalid
If an error occurs, then a (negative) error code will be returned instead. An error would indicate something seriously wrong, so would not normally occur except perhaps while in development mode.

 


int SROFF_XrefSignedSet (SROFF_XREF pXref, int Value);

Set this property to define the signed/unsigned attributes for the SROFF_XREF object that is specified by pXref.

Value will be one of the following:

SROFF_XREF_SIGNED The XREF result is signed
SROFF_XREF_UNSIGNED The XREF result is unsigned.
SROFF_XREF_NOTSIGNED This indicates that no sign value is set. Normally this is interpreted as being equivalent to the SROFF_XDEF_SIGNED value.
SROFF_XREF_BOTHSIGNS This indicates that both sign options are set. This should not ever occur as it would indicate that the SROFF generated is invalid
On success SROFF_ERROR_NONE is returned, and on failure an appropriate (negative) error code

 


int SROFF_XrefTruncSizeGet (SROFF_XREF pXref);

Property that gives the size that a result must be truncated to. On success it will always be one of the following (positive) values:

SROFF_TRUNC_BYTE The result must be a single byte in size
SROFF_TRUNC_SHORT The result must be two bytes in size
SROFF_TRUNC_LONG The result must be 4 bytes in size
If an error occurs, then a (negative) error code will be returned instead. An error would indicate something seriously wrong, so would not normally occur except perhaps while in development mode.

 


int SROFF_XrefTruncSizeSet (SROFF_XREF pXref, int Size);

Sets this property to specify the size that a result of a relocation must be truncated to. It will always be one of the following values:

SROFF_TRUNC_BYTE The result must be a single byte in size
SROFF_TRUNC_SHORT
SROFF_TRUNC_LONG The result must be 4 bytes in size
On success the value SROFF_ERROR_NONE will be returned, and on error the appropriate error code.

 


 

* LIBSROFF ERROR CODES

The following symbolic names are used for the error codes that can be set or returned by the methods and properties in the LIBSROFF library.

These values are always negative to help distinguish them from success code, and they will not overlap the error code used by the standard libraries (i.e. the ones defined in the errno.h header file)

Error Code Description
SROFF_ERROR_NONE This is returned (where relevant) when no error has occurred
SROFF_ERROR_EMPTYLIST This is returned when you try to read a property that would normally return a list, and the list is empty.
SROFF_ERROR_BADOBJECT This is returned if you pass in a reference to an object that is the wrong type of object for the method or property that you are trying to use.

Note that this error is not always detected in the standard version of the library. The debug version of the library includes additional checks to try and detect this type of error.

SROFF_ERROR_BADPARAM This is returned if there is something wrong with the parameter supplied to a method or property call. This would typically be something like passing in an object reference for a object that either does not exist.

Note that this error is not always detected in the standard version of the library. The debug version of the library includes additional checks to try and detect this type of error.

SROFF_ERROR_NOMEMORY There was insufficient free memory to complete the operation required.
SROFF_ERROR_NOTSROFF The physical file was opened correctly, but from looking at the data at the start of the file it does not appear to be a valid SROFF file.
SROFF_ERROR_READ A failure occurred while reading a SROFF file.
SROFF_ERROR_WRITE A failure occurred while writing a SROFF file.

 


* RELATED DOCUMENTS

The following documents are likely to be useful when trying to make use of the LIBSROFF library.

SROFF.HTM SROFF Specification
This is the formal specification of the SROFF object format as supported by the LIBSROFF library.
LIBLIST.HTM List Handling Support Library
This library provides methods and properties for manipulating all types of lists in memory. This library is used extensively within the LIBSROFF library, and this documentation will allow you to make use of the same facilities within your own programs. In particular you will need methods and properties from the LIBLIST library to manipulate any lists set up by the LIBSROFF methods.
LIBRLL.HTM RLL Support Library
This library handles manipulation of the binaries of RLL programs or libraries. You will only need it if you wish to manipulate this kind of file.

 


 

* AUTHOR AND COPYRIGHT

This library and associated documentation has been produced by:

Dave Walker,
22 Kimptons Mead,
Potters Bar,
Herts,
EN6 3HZ
United Kingdom

Web: http://www.itimpi.freeserve.co.uk
Email: dave.walker@icl.com
   or: libsroff@itimpi.freeserve.co.uk

This library and its associated documentation are copyright 1997-1998 by D.J.Walker. All rights are reserved.

Every effort has been made to ensure that the LIBSROFF software operates correctly as specified in this document. However no guarantee of any kind is given that the software is reliable or that the descriptions contained in this document is accurate. It is up to the user of the LIBSROFF library to satisfy himself that it is suitable for the use to which it will be put.

Permission is given to freely distribute this library, including its documentation and source as long as the following terms are adhered to:

If anyone wishes to distribute the LIBSROFF library under any other terms, then they should contact the author to discuss the terms.

 


* CHANGE HISTORY

August 1997

May 1998

July 1998: Release 1.0