Difference between revisions of "OSGBPB"

From BeebWiki
Jump to: navigation, search
m (1 revision)
(Specification)
 
(31 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
[[Category:MOS_API]]
 
[[Category:MOS_API]]
Read or write multiple bytes of data
+
{{PageTitle|OSGBPB: Read or write multiple bytes of data}}
 
+
__TOC__
 
==Specification==
 
==Specification==
{| cellpadding="0" cellspacing="0"  
+
{| cellpadding="0" cellspacing="0" border="1"
|  6502  ||  Z80  ||  6809  ||  PDP11  ||  80x86  ||  32016  ||  ARM  || align="left" | '''On entry:''' || align="left" | '''On exit:'''
+
| 6502 || Z80 || 6809 || PDP11 || 80x86 || 32016 || ARM || 68000 || RISC-V || align="left" valign="top" | '''On entry:''' || align="left" valign="top" | '''On exit:'''
 +
|- align="center" valign="top"
 +
| A || A || A || R0 || AL || R1 || R0 || D0 || A0 || align="left" valign="top" | = function code || align="left" valign="top" | = &00 if supported, preserved if not supported, but see notes
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| A || A || A || R0 || AL || R1 || R0 || align="left" | = function code || = &00 if supported, preserved if not supported, but see notes.
+
| YX || HL || X || R1 || BX || || || || || align="left" | =>control block || align="left" valign="top" | undefined, control block updated
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| XY || HL || X || R1 || BX || || || align="left" | =>control block || align="left" | undefined
+
|   ||   ||   ||    ||    || || || || || align="left" | || align="left" valign="top" | Cy=EOF, but see notes
 
|-
 
|-
| colspan="7" | '''Control block'''
+
| colspan="5" align="center" valign="top" | '''Control block''' || colspan="4" | || ||
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| colspan="5" | &00 || R2 || R1 || align="left" | Handle || align="left" | Cycle number
+
| colspan="5" | &00 || R2 || R1 || D1 || A1 || align="left" valign="top" | Handle || align="left" valign="top" | Handle or Cycle Number
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| colspan="5" | &01 || R3 || R2 || align="left" | Data address || align="left" | Updated Data address
+
| colspan="5" | &01 || R3 || R2 || D2 || A2 || align="left" | Data Address || align="left" | Updated Data Address
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| colspan="5" | &05 || R4 || R3 || align="left" | Number of bytes or objects to transfer  || align="left" | Updated Number of bytes or objects
+
| colspan="5" | &05 || R4 || R3 || D3 || A3 || align="left" | Count        || align="left" | Updated Count
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| colspan="5" | &09 || R5 || R4 || align="left" | Pointer to use for transfer || align="left" | Updated Pointer
+
| colspan="5" | &09 || R5 || R4 || D4 || A4 || align="left" | Offset      || align="left" | Updated Offset
 
|- align="center" valign="top"
 
|- align="center" valign="top"
| colspan="5" | &0D || || ||
+
| colspan="5" | &0D ||   ||   || || || align="left" |              || align="left" |
|- align="center" valign="top"
+
|}
| || || || || || || || align="left" | || align="left" | Cy=EOF status (but see notes)
+
<p>
 +
{| cellpadding="0" cellspacing="0" border="0"
 +
| colspan="4" | <font size="+0">'''Function summary'''&nbsp;</font>
 +
|- valign="top"
 +
| colspan="2" | '''Core functions'''    || colspan="2" | '''Extensions'''
 +
|- valign="top"
 +
| &01 || Write bytes using pointer      || &09 || Read names from specified directory
 +
|- valign="top"
 +
| &02 || Write bytes to current pointer  || &0A || Read names and information
 +
|- valign="top"
 +
| &03 || Read bytes using pointer        || &0B || Read names and extended information
 +
|- valign="top"
 +
| &04 || Read bytes from current pointer || &0C || Read names and filetype information
 +
|- valign="top"
 +
| &05 || Read title and boot option      ||
 +
|- valign="top"
 +
| &06 || Read directory name            ||
 +
|- valign="top"
 +
| &07 || Read library name              ||
 +
|- valign="top"
 +
| &08 || Read&nbsp;object&nbsp;names&nbsp;from&nbsp;current&nbsp;dir. ||
 
|}
 
|}
  
<BR>
+
On return:
 +
* The handle is preserved, unless where indicated
 +
* The Data address is incremented by the number of bytes transfered
 +
* The Count is decremented by the number of bytes or objects transfered
 +
* The Offset returns the actual PTR used incremented by the number of bytes transfered, or updated to the next object
 +
 
 +
==Functions==
 
{| cellpadding="0" cellspacing="0"  
 
{| cellpadding="0" cellspacing="0"  
| colspan="2" | '''Functions'''
+
| valign="top" | &01 || Write bytes to open file using new pointer.
|-
 
| valign="top" | &01 || Write bytes to media using new pointer.
 
 
|-
 
|-
| valign="top" | &02 || Write bytes to media ignoring new pointer.
+
| valign="top" | &02 || Write bytes to open file ignoring new pointer.
 
|-
 
|-
| valign="top" | &03 || Read bytes from media using new pointer.
+
| valign="top" | &03 || Read bytes from open file using new pointer.
 
|-
 
|-
| valign="top" | &04 || Read bytes from media ignoring new pointer.
+
| valign="top" | &04 || Read bytes from open file ignoring new pointer.
 
|-
 
|-
 
| valign="top" colspan="2" |
 
| valign="top" colspan="2" |
 
:With functions &01 and &03 the PTR is first set to the supplied value before transferring data.
 
:With functions &01 and &03 the PTR is first set to the supplied value before transferring data.
:On exit the number of bytes actually transferred is subtracted from the 'number of bytes' field and added to the 'data address' field and the PTR.  The new PTR is returned in the 'PTR' field.  The carry flag is returned set if the 'number of bytes' field is not zero on exit -- meaning a read was attempted past EOF. If the read or write extended past end-of-file the EOF error-flag is set and a further read without changing PTR will cause an EOF error.
+
:On exit, the carry flag is returned set if the 'Count' field is not zero on exit -- meaning a read was attempted past EOF (but see notes). If the read or write extended past end-of-file the EOF error-flag is set and a further read without changing PTR will cause an EOF error.
:If a write extends past EOF the file is extended, however the contents of the new part of the file are undefined unless overwritten. An error occurs if the object is not a file or does not have the correct access.
+
:If a write extends past EOF the file is extended, however the contents of the new part of the file are undefined unless overwritten.
:If the handle is 0, action is undefined. Some systems allow multiple bytes to be written to OSWRCH or read from OSRDCH if the handle is 0.
+
:An error occurs if the object is not a file or does not have the correct access.
 +
:If the handle is 0, the action is undefined. Some systems allow multiple bytes to be written to OSWRCH or read from OSRDCH if the handle is 0.
 
|-
 
|-
| valign="top" | &05 || Get media title of CSD disk and boot option into data block:
+
| valign="top" | &05 || Read title and boot option of CSD disk into data block:
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of title (n)  
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of title (n)  
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;title in ASCII characters
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;title in ASCII characters
Line 50: Line 77:
 
:&03+n
 
:&03+n
 
|-
 
|-
| valign="top" | &06 || Get currently selected directory name into data block:
+
| valign="top" | &06 || Read currently selected directory name into data block:
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of drive identity (n)
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of drive identity (n)
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ASCII drive identity (drive number)
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ASCII drive identity (drive number)
Line 58: Line 85:
 
:&03+n+m
 
:&03+n+m
 
|-
 
|-
| valign="top" | &07 || Get current library name into data block:
+
| valign="top" | &07 || Read current library name into data block:
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of drive identity (n)
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of drive identity (n)
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ASCII drive identity (drive number)
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ASCII drive identity (drive number)
Line 66: Line 93:
 
:&03+n+m
 
:&03+n+m
 
|-
 
|-
| valign="top" | &08 || Read filenames from current directory into data block:
+
| valign="top" | &08 || Read object names from current directory into data block:
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of filename 1 (n)
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of filename 1 (n)
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;filename 1 in ASCII characters
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;filename 1 in ASCII characters
Line 72: Line 99:
 
:&02+n &nbsp;&nbsp;&nbsp;&nbsp;filename 2 in ASCII characters
 
:&02+n &nbsp;&nbsp;&nbsp;&nbsp;filename 2 in ASCII characters
 
:&02+n+m etc...
 
:&02+n+m etc...
:The first call to function &08 should be made with the transfer pointer set to zero. This will read the first filename, and the pointer will be updated so that the next call will read the next filename. The cycle number of the current directory is also returned in XY+0. When no filenames are left, the call returns with the 'number of filenames' greater than zero and the carry flag set.
+
:The first call to function &08 should be made with the transfer pointer set to zero. This will read the first filename, and the pointer will be updated so that the next call will read the next filename. The cycle number of the current directory is also returned in XY+0. When no filenames are left, the call returns with the 'Count' unchanged and the carry flag set. See [[Scanning Directories (Reading Directory Entries)]].
 
|-
 
|-
| valign="top" | &09 || Reads work/login filename, command line tail or entries from specified directory. If the handle is zero, reads work/login filename or command tail:
+
| valign="top" | &09 || Reads object names from directory, work/login filename, command line tail:
 +
Reading object names:
 +
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;object name, null terminated
 +
:xxx &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;next record
 +
 
 +
Reading work/login filename or command line tail:
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of drive identity or command line tail (n)
 
:&00 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;length of drive identity or command line tail (n)
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ASCII drive identity (drive number) or comand line tail
 
:&01 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ASCII drive identity (drive number) or comand line tail
Line 81: Line 113:
 
:&02+n+m
 
:&02+n+m
  
:If the handle is a channel number of an open directory, reads a null-terminated list of directory entries. The function is called as for OSGBPB 8, but the updated number of objects is the number of filenames read.
+
If the handle is a channel number of an open directory, reads a null-terminated list of directory entries. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. The function is called as for OSGBPB 8, but the updated 'Count' is the number of filenames read, which is zero when there are no more names to read. See also implementation notes.
 
|-
 
|-
| valign="top" | &0A || Read entries and information from the opened directory whose channel number is passed in the handle. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
+
| valign="top" | &0A &nbsp; || Read object names and information from the opened directory whose channel number is passed in the handle. If the channel is zero the current directory is scanned. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
 
:&00 Load address
 
:&00 Load address
 
:&04 Execution address
 
:&04 Execution address
Line 89: Line 121:
 
:&0C Attributes
 
:&0C Attributes
 
:&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
 
:&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
:&14 Object name, null terminated
+
:&14 Object name, null terminated, padded to four bytes
 
:xxx next record  
 
:xxx next record  
 
|-
 
|-
| valign="top" | &0B || Read entries and information from the opened directory whose channel number is passed in the handle. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
+
| valign="top" | &0B || Read object names and extended information from the opened directory whose channel number is passed in the handle. If the channel is zero the current directory is scanned. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
 
:&00 Load address
 
:&00 Load address
 
:&04 Execution address
 
:&04 Execution address
Line 98: Line 130:
 
:&0C Attributes
 
:&0C Attributes
 
:&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
 
:&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
:&14 Sector start address
+
:&14 System Internal Name (Sector start address)
 
:&18 Five zeros or centisecond time since 1900
 
:&18 Five zeros or centisecond time since 1900
:&1D Object name, null terminated
+
:&1D Object name, null terminated, padded to four bytes
 
:xxx next record
 
:xxx next record
 
|-
 
|-
| valign="top" | &0C || Read entries and information from the opened directory whose channel number is passed in the handle. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
+
| valign="top" | &0C || Read object names and filetype information from the opened directory whose channel number is passed in the handle. If the channel is zero the current directory is scanned. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
 
:&00 Load address
 
:&00 Load address
 
:&04 Execution address
 
:&04 Execution address
Line 110: Line 142:
 
:&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
 
:&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
 
:&14 Object file type (b8-b19 of load address)
 
:&14 Object file type (b8-b19 of load address)
:&18 Object name, null terminated
+
:&18 Object name, null terminated, padded to four bytes
 
:xxx next record  
 
:xxx next record  
 
|}
 
|}
Line 117: Line 149:
 
Some filing systems preserve A even if they support the function.
 
Some filing systems preserve A even if they support the function.
  
Many filing systems do not return Carry consistently. The only consistent way of telling if the end of file has been reached is to test whether the updated number of bytes/objects is unequal to zero.
+
Many filing systems do not return Carry consistently. The only consistent
 +
way of telling if the end of file has been reached is to test whether the
 +
updated number of bytes/objects is unequal to zero.
  
 
==Calling from BBC BASIC==
 
==Calling from BBC BASIC==
Line 131: Line 165:
 
* PDP-11 Entry Address: EMT 11, vector &0B
 
* PDP-11 Entry Address: EMT 11, vector &0B
 
* ARM Entry Address: SWI &0C "OS_GBPB", vector &0C
 
* ARM Entry Address: SWI &0C "OS_GBPB", vector &0C
 +
* 68000 Entry Address: MOV #&0C,A0:TRAP 12
 +
* RISC-V Entry Address: ECALL &AC000B
  
 
==Implementations==
 
==Implementations==
Line 144: Line 180:
  
 
===DFS===
 
===DFS===
Acorn DFS and contemporary filing systems implement functions &01 to &08 inclusive. Watford DFS implements &09 to read the work name.
+
Acorn DFS and contemporary filing systems implement functions &01 to &08
 +
inclusive. Watford DFS implements &09 to read the work name.
 +
 
 +
In Opus EDOS and Slogger Challenger, OSGBPB 5 does not return the CSD drive
 +
number.  In Opus DDOS the drive number byte includes a representation of
 +
the volume letter in bits 6..4.
 +
 
 +
In Opus/Slogger filing systems the drive identity returned by OSGBPB 6 and
 +
7 consists of one or two characters, the first being the ASCII drive digit
 +
<tt>0</tt>..<tt>3</tt> and the second being the optional volume letter
 +
<tt>A</tt>..<tt>H</tt>.
  
 
===ADFS===
 
===ADFS===
Line 155: Line 201:
 
The Z80Tube Z80 emulator implements OSGBPB 9,0 to read the command line tail.
 
The Z80Tube Z80 emulator implements OSGBPB 9,0 to read the command line tail.
  
 +
===65Tube===
 +
The emulator traps implemented in 65Tube allows calls to OSGBPB with A>9 to
 +
pass additional parameters:
 +
{| cellpadding="0" cellspacing="0"
 +
|- valign="top"
 +
| On entry:  || &nbsp; || On exit: || &nbsp;
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY?0  || = ignored          || &nbsp;&nbsp;XY?0  || = directory cycle
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!1  || = address          || &nbsp;&nbsp;XY!1  || = updated address
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!5  || = count            || &nbsp;&nbsp;XY!5  || = returned count
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!9  || = offset            || &nbsp;&nbsp;XY!9  || = updated offset
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!13 || =>directory name    || &nbsp;&nbsp;XY!13 || = preserved
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!17 || =>wildcard to match || &nbsp;&nbsp;XY!17 || = preserved
 +
|}
 +
 +
===6502Em===
 +
The emulator traps implemented in Warm Silence's 6502Em implement OSGBPB 9
 +
to read object names from the current directory, but use the control block
 +
contents differently from the standard:
 +
{| cellpadding="0" cellspacing="0"
 +
|- valign="top"
 +
| On entry:  || &nbsp; || On exit: || &nbsp;
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY?0  || = count            || &nbsp;&nbsp;XY?0  || = returned count
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!1  || = address          || &nbsp;&nbsp;XY!1  || = preserved
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!5  || = buffer length    || &nbsp;&nbsp;XY!5  || = preserved
 +
|- valign="top"
 +
| &nbsp;&nbsp;XY!9  || = offset            || &nbsp;&nbsp;XY!9  || = updated offset
 +
|}
 +
 +
{{Filing}}
 
[[User:Jgharston|Jgharston]] 17:01, 6 November 2009 (UTC)
 
[[User:Jgharston|Jgharston]] 17:01, 6 November 2009 (UTC)
 +
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 15:56, 30 September 2016 (UTC)
 +
[[User:Jgharston|Jgharston]] ([[User talk:Jgharston|talk]]) 00:03, 3 October 2016 (UTC)

Latest revision as of 11:53, 11 February 2024

OSGBPB: Read or write multiple bytes of data

Specification

6502 Z80 6809 PDP11 80x86 32016 ARM 68000 RISC-V On entry: On exit:
A A A R0 AL R1 R0 D0 A0 = function code = &00 if supported, preserved if not supported, but see notes
YX HL X R1 BX =>control block undefined, control block updated
Cy=EOF, but see notes
Control block
&00 R2 R1 D1 A1 Handle Handle or Cycle Number
&01 R3 R2 D2 A2 Data Address Updated Data Address
&05 R4 R3 D3 A3 Count Updated Count
&09 R5 R4 D4 A4 Offset Updated Offset
&0D

Function summary 
Core functions Extensions
&01 Write bytes using pointer &09 Read names from specified directory
&02 Write bytes to current pointer &0A Read names and information
&03 Read bytes using pointer &0B Read names and extended information
&04 Read bytes from current pointer &0C Read names and filetype information
&05 Read title and boot option
&06 Read directory name
&07 Read library name
&08 Read object names from current dir.

On return:

  • The handle is preserved, unless where indicated
  • The Data address is incremented by the number of bytes transfered
  • The Count is decremented by the number of bytes or objects transfered
  • The Offset returns the actual PTR used incremented by the number of bytes transfered, or updated to the next object

Functions

&01 Write bytes to open file using new pointer.
&02 Write bytes to open file ignoring new pointer.
&03 Read bytes from open file using new pointer.
&04 Read bytes from open file ignoring new pointer.
With functions &01 and &03 the PTR is first set to the supplied value before transferring data.
On exit, the carry flag is returned set if the 'Count' field is not zero on exit -- meaning a read was attempted past EOF (but see notes). If the read or write extended past end-of-file the EOF error-flag is set and a further read without changing PTR will cause an EOF error.
If a write extends past EOF the file is extended, however the contents of the new part of the file are undefined unless overwritten.
An error occurs if the object is not a file or does not have the correct access.
If the handle is 0, the action is undefined. Some systems allow multiple bytes to be written to OSWRCH or read from OSRDCH if the handle is 0.
&05 Read title and boot option of CSD disk into data block:
&00         length of title (n)
&01         title in ASCII characters
&01+n     startup option
&02+n     drive number
&03+n
&06 Read currently selected directory name into data block:
&00         length of drive identity (n)
&01         ASCII drive identity (drive number)
&01+n     length of directory name (m)
&02+n     directory name in ASCII characters
&02+n+m ownership: &00 - owner, &FF - public
&03+n+m
&07 Read current library name into data block:
&00         length of drive identity (n)
&01         ASCII drive identity (drive number)
&01+n     length of library name (m)
&02+n     library name in ASCII characters
&02+n+m ownership: &00 - owner, &FF - public
&03+n+m
&08 Read object names from current directory into data block:
&00         length of filename 1 (n)
&01         filename 1 in ASCII characters
&01+n     length of filename 2 (m)
&02+n     filename 2 in ASCII characters
&02+n+m etc...
The first call to function &08 should be made with the transfer pointer set to zero. This will read the first filename, and the pointer will be updated so that the next call will read the next filename. The cycle number of the current directory is also returned in XY+0. When no filenames are left, the call returns with the 'Count' unchanged and the carry flag set. See Scanning Directories (Reading Directory Entries).
&09 Reads object names from directory, work/login filename, command line tail:

Reading object names:

&00         object name, null terminated
xxx         next record

Reading work/login filename or command line tail:

&00         length of drive identity or command line tail (n)
&01         ASCII drive identity (drive number) or comand line tail
&01+n     length of work/login filename (m)
&02+n     work/login filename
&02+n+m

If the handle is a channel number of an open directory, reads a null-terminated list of directory entries. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. The function is called as for OSGBPB 8, but the updated 'Count' is the number of filenames read, which is zero when there are no more names to read. See also implementation notes.

&0A   Read object names and information from the opened directory whose channel number is passed in the handle. If the channel is zero the current directory is scanned. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
&00 Load address
&04 Execution address
&08 Length
&0C Attributes
&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
&14 Object name, null terminated, padded to four bytes
xxx next record
&0B Read object names and extended information from the opened directory whose channel number is passed in the handle. If the channel is zero the current directory is scanned. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
&00 Load address
&04 Execution address
&08 Length
&0C Attributes
&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
&14 System Internal Name (Sector start address)
&18 Five zeros or centisecond time since 1900
&1D Object name, null terminated, padded to four bytes
xxx next record
&0C Read object names and filetype information from the opened directory whose channel number is passed in the handle. If the channel is zero the current directory is scanned. On platforms where the channel is passed in a register this can be a pointer to a directory name, or zero for the current directory. This function is called as for OSGBPB 9. Each record is a whole multiple of four bytes long:
&00 Load address
&04 Execution address
&08 Length
&0C Attributes
&10 Object type (1=file, 2=directory, 3=image file, 4=unresolved symbolic link)
&14 Object file type (b8-b19 of load address)
&18 Object name, null terminated, padded to four bytes
xxx next record

Notes

Some filing systems preserve A even if they support the function.

Many filing systems do not return Carry consistently. The only consistent way of telling if the end of file has been reached is to test whether the updated number of bytes/objects is unequal to zero.

Calling from BBC BASIC

BBC BASIC makes no calls to OSGBPB.

Entry points

  • BBC BASIC Entry Address: &FFD1
  • 6502 Entry Address: &FFD1, vectors via &021A
  • Z80 Entry Address: &FFD1, vectors via &FFD2
  • 6809 Entry Address: &FFD1, vectors via &FFD2
  • 80x86 Entry Address: INT &41, vectors via 0000:0104
  • 32000 Entry Address: SVC &0F
  • PDP-11 Entry Address: EMT 11, vector &0B
  • ARM Entry Address: SWI &0C "OS_GBPB", vector &0C
  • 68000 Entry Address: MOV #&0C,A0:TRAP 12
  • RISC-V Entry Address: ECALL &AC000B

Implementations

CFS

Not implemented, simply returns with an RTS instruction.

The Master 128 implements &02 and &04.

ROMFS

Not implemented, simply returns with an RTS instruction.

The Master 128 implements &04.

DFS

Acorn DFS and contemporary filing systems implement functions &01 to &08 inclusive. Watford DFS implements &09 to read the work name.

In Opus EDOS and Slogger Challenger, OSGBPB 5 does not return the CSD drive number. In Opus DDOS the drive number byte includes a representation of the volume letter in bits 6..4.

In Opus/Slogger filing systems the drive identity returned by OSGBPB 6 and 7 consists of one or two characters, the first being the ASCII drive digit 0..3 and the second being the optional volume letter A..H.

ADFS

ADFS implements &01 to &08

HADFS

HADFS implements &01 to &0B.

Z80Tube

The Z80Tube Z80 emulator implements OSGBPB 9,0 to read the command line tail.

65Tube

The emulator traps implemented in 65Tube allows calls to OSGBPB with A>9 to pass additional parameters:

On entry:   On exit:  
  XY?0 = ignored   XY?0 = directory cycle
  XY!1 = address   XY!1 = updated address
  XY!5 = count   XY!5 = returned count
  XY!9 = offset   XY!9 = updated offset
  XY!13 =>directory name   XY!13 = preserved
  XY!17 =>wildcard to match   XY!17 = preserved

6502Em

The emulator traps implemented in Warm Silence's 6502Em implement OSGBPB 9 to read object names from the current directory, but use the control block contents differently from the standard:

On entry:   On exit:  
  XY?0 = count   XY?0 = returned count
  XY!1 = address   XY!1 = preserved
  XY!5 = buffer length   XY!5 = preserved
  XY!9 = offset   XY!9 = updated offset
Filing System Calls
  • OSFILE : File and directory operations
  • OSARGS : Information on open objects
  • OSBGET : Read (get) a byte
  • OSBPUT : Write (put) a byte
  • OSGBPB : Read or write multiple bytes of data
  • OSFIND : Open or close an object
  • FSCV : Filing system control

Jgharston 17:01, 6 November 2009 (UTC) Jgharston (talk) 15:56, 30 September 2016 (UTC)

Jgharston (talk) 00:03, 3 October 2016 (UTC)