;
; chunk.sh
;
; Loading and management of options chunks
;
; © 1995-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;----- Overview -------------------------------------------------------------
;
; Functions provided:
;
;  chunk_create
;  chunk_destroy
;  chunk_claim
;  chunk_makeBinary
;  chunk_read
;  chunk_enum
;  chunk_save

		[	:LNOT::DEF:chunk__dfn
		GBLL	chunk__dfn

; --- chunk_create ---
;
; On entry:	--
;
; On exit:	R0 == chunk file handle
;		May return an error
;
; Use:		Creates a new chunk file structure and returns a handle to
;		it.

		IMPORT	chunk_create

; --- chunk_destroy ---
;
; On entry:	R0 == chunk file handle
;
; On exit:	--
;
; Use:		Removes a chunk file structure from memory.  Chunk data in
;		flex blocks is freed; chunk claimers who free flex blocks
;		should clear the anchors to 0.

		IMPORT	chunk_destroy

; --- chunk_claim ---
;
; On entry:	R0 == chunk file handle
;		R1 == pointer to chunk name
;		R2 == pointer to saver routine, or 0 for none, or -1 for no
;			change
;		R3 == R10 value to pass to saver
;		R4 == R12 value to pass to saver
;
; On exit:	R1 == chunk handle/anchor
;		CS if the chunk already existed
;		May return an error
;
; Use:		Claims a chunk, installing a save handler for it.  The chunk
;		handle returned is actually the address of a flex anchor for
;		the chunk's data (use flex_size to find the block's size).
;		If the save handle is 0, the data in the flex block (which
;		may be modified) is saved directly from the block.  Otherwise
;		the save routine is expected to save its data, using xsave.
;
;		The anchor is followed by 3 unused words -- you can use them
;		for whatever you want.
;
;		Warning: this routine may move flex blocks.

		IMPORT	chunk_claim

; --- chunk_makeBinary ---
;
; On entry:	R0 == chunk file handle
;		R1 == chunk handle
;
; On exit:	--
;
; Use:		Marks a given chunk as containing binary data.

		IMPORT	chunk_makeBinary

; --- chunk_read ---
;
; On entry:	R0 == chunk file handle
;		R1 == address of a flex anchor
;
; On exit:	May return an error
;
; Use:		Merges the data contained in the flex block with that already
;		in the chunk file.  If the chunk file is empty, this is
;		equivalent to a load.  Data from the flex block is appended
;		to chunks already loaded where appropriate.
;
;		Warning: this routine may move flex blocks.

		IMPORT	chunk_read

; --- chunk_enum ---
;
; On entry:	R0 == chunk file handle
;		R1 == 0 for first call or continuation value
;
; On exit:	CC if this isn't over yet, and
;		  R1 == continuation value for next call
;		  R2 == pointer to chunk name
;		else CS and
;		  R1 == 0
;		  R2 preserved
;
; Use:		Allows you to enumerate the chunks in a chunk file structure.

		IMPORT	chunk_enum

; --- chunk_save ---
;
; On entry:	R0 == chunk file handle
;
; On exit:	May return an error
;
; Use:		Saves a chunk file to xsave's current output.

		IMPORT	chunk_save

		]

;----- That's all, folks ----------------------------------------------------

		END