Load
Synopsis
buffer = Load(filename, buffer, typeofmem)
D0 A0 A1 D0C Prototype
APTR Load(STRPTR filename, APTR buffer, ULONG typeofmem);Description
Loads any file into memory using dos.library/Open(). This command does NOT perform any relocation of the file. The filename pointer is a string, complete with path, indicating the file to be loaded into memory.
A notable feature is the ability to pre-allocate your own buffer instead of having Load() allocate one. If a buffer is passed in the inputs, the file will be loaded into it. As a general rule, it is strongly recommended to always pass a NULL buffer, leaving the allocation task to Load(). This will allow the use of exec.library/FreeVec() when it is time to free the memory.
Load() allocates an entire block of memory corresponding to the byte size of the file to be loaded. Therefore, its use is recommended in all cases where available memory and its fragmentation are not a concern.
Its use is suitable for files that do not exceed 500K in size, although on systems equipped with large amounts of RAM (Fast or Chip), it can be used with any file size.
Inputs
- filename — Pointer to the name of the file to load.
- buffer — Pointer to a buffer where the data will be loaded. If NULL, the routine will automatically allocate a buffer for the data. In this case, the type of memory to allocate must ALWAYS be specified.
- typeofmem — Type of memory to allocate (e.g.,
MEMF_PUBLIC). This parameter is only considered whenbufferis NULL.
Result
- buffer — If NULL, an error occurred. Otherwise, it is the address of the buffer containing the file data. If a pre-allocated buffer was passed, this address is the same as the one passed in the inputs. Otherwise, it is the buffer allocated by the command.
Notes
None.
Bugs
With heavily fragmented memory, Load() may fail for very large files.
See Also
dos.library/Open(), dos.library/Read(), exec.library/FreeVec()
Implementation
The original 68020 assembly implementation:
; (15-Feb-1995) --- buffer = Load(filename,buffer,typeofmem) (a0/a1/d0)
_LVOLoad
movem.l d2-d7/a2-a6,-(sp)
move.l a6,a5 ; Save AssemblyBase
move.l a0,a4 ; Save FileName
move.l a1,a3 ; Save Buffer
move.l a3,a2 ; Copy buffer for CTRL!!!
move.l d0,d7 ; TypeOfMem?
bne.s Load_OkTypeMem ; Yes?
moveq #MEMF_PUBLIC,d7 ; Default
Load_OkTypeMem
bsr.s _LVOFileInfo
tst.l d0
beq.s Load_Exit
move.l d0,a1
move.l fib_Size(a1),d3 ; byte size in D3
move.l ab_ExecBase(a5),a6 ; Exec
move.l -(a1),d0
jsr _LVOFreeMem(a6)
move.l a3,d0 ; Custom memory?
bne.s Load_NoAlloc ; Yes
addq.l #4,d3 ; For AllocVec()
move.l d3,d0 ; byteLen
move.l d7,d1 ; type of mem
jsr _LVOAllocMem(a6)
tst.l d0 ; Null = error
beq.s Load_Exit
move.l d0,a3 ; Save buffer in A3
move.l d3,(a3)+ ; Bytes to free...
subq.l #4,d3 ; Bytes to read...
Load_NoAlloc
move.l ab_DosBase(a5),a6 ; DosBase
move.l a4,d1 ; filename
lea MODE_OLDFILE.w,a0
move.l a0,d2 ; access type
jsr _LVOOpen(a6) ; in theory it should always open
tst.l d0 ; Null = error
beq.s Load_Exit2
move.l d0,d5 ; BCPL handle in D5
move.l d5,d1 ; handle in D1
move.l a3,d2 ; buffer in D2/ bytelen in D3
jsr _LVORead(a6)
move.l d5,d1
jsr _LVOClose(a6)
move.l a3,d0
Load_Exit
movem.l (sp)+,d2-d7/a2-a6
rts
Load_Exit2
move.l a2,d1 ; Was the buffer allocated by me or passed in??
bne.s Load_Exit ; It was passed in...
move.l a3,a1 ; Ok, since Load() allocated it, then
move.l -(a1),d0 ; free it!!
move.l ab_ExecBase(a5),a6
jsr _LVOFreeMem(a6)
moveq #0,d0 ; Failure...
movem.l (sp)+,d2-d7/a2-a6
rts