OSARGS

OSARGS: Information on open objects or the filing system

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	preserved if not supported, but see notes.
Y	E	Y	R1	AH	R2	R1	D1	A1	= file handle or 0	preserved
X									=>four-byte data word in zero page	preserved, data word updated
	HL	X	R2	BX					=>four-byte data word	preserved, data word updated
					R3	R2	D2	A2	= four-byte data word	any returned four-byte data word

If the data word is not used, then it is ignored and so X/HL/R2/BX/R3/R2/D2/A2 may be left set to anything on entry.

Functions	handle<>0	handle=0
&80	Read file handle internal info
&FD	Write context	Return version and capabilities
&FE	Read context	Return last drive used
&FF	Ensure open file to media	Ensure all open files to media
&00	Read PTR	Read filing system number
&01	Write PTR	Read address of command tail
&02	Read EXT	Read NFS version
&03	Write EXT	Read libfs number
&04	Read size allocated to file	Read disk space used
&05	Read EOF	Read disk free space
&06	Ensure file size of open file
&07	Convert file handle to filename
&08	Inform change in image filestamp

Functions, handle<>0

&00	Reads the sequential pointer of the open object.
&01	Writes the sequential pointer of the pen file. If PTR is moved past the end of an output file, the file is extended with zeroes and zero returned in A, otherwise A = &FF on exit. Some filing systems do not write zeroes; the contents of the new part of the file are undefined. If PTR is moved past the end of an input file, an error is generated. The EOF-error-flag is cleared. The PTR of an open directory cannot be written.
&02	Reads the extent of the open object.
&03	Writes the extent of the open object. If the length of the file is reduced, the end disappears. If the length is increased, the file is extended as with function &01 and zero is returned in A, otherwise A = &FF on exit. The EOF-error-flag is cleared. The EXT of an open directory cannot be written.
&04	Reads the space allocated to the open object. This will be at least the current extent of the object, and determines how many more bytes can be written to the object before the object has to be extended or the write fails with a "Can't extend" error.
&05	Reads the EOF for the open object. If PTR=EXT then &FFFFFFFF is returned, otherwise 0 is returned.
&06	Ensures the open file is allocated the specified amount of space. Returns the actual amount of space allocated.
&07	Convert file handle to filename (RISC OS). The data word in R2 points to a buffer, the size of which is given in R5. On exit, the data word in R2 is preserved, the buffer contains the filename as a NUL-terminated string, and R5 is decreased by the number of characters in the filename excluding the NUL. The NUL is addressed by R2 + R5entry - R5exit.
&08	Inform the underlying file system of new image stamp in data word.
&80	Read information on handle. Returns four bytes of data: byte 0 = handle in internal format byte 1-2 = fileserver station number byte 3 = handle information:    b0: sequence number    b1: known to be a directory    b2: thought to be the URD   <li>b3: thought to be the CSD    b4: thought to be the LIB    b5: current context    b6: EOF flag, next BGET will generate an error    b7: writable
&FD	Write filing system context. HADFS implements: 25: Currently Selected Directory 26: Currently Selected Library 27: User Root Directory
&FE	Read filing system context. HADFS implements: 25: Currently Selected Directory 26: Currently Selected Library 27: User Root Directory RISC OS: Returns the filing system information word in the data word and the stream information for the handle in A or R0. On 8-bit systems only the bottom 8 bits of the stream information word will be returned. b0 b1 b2 b3: Interactive stream b4: Unbuffered stream that directly supports OSGBPB b5: Object is a directory b6: Object is readable b7: Object is writable b8: Object has been written to b9: EOF flag, next BGET will generate an error b10: Stream is unbuffered b11: Stream is unopened, no other bits have any significance b12: Stream is critical b13: Data lost on this stream b14: Image file busy b15
&FF	Ensures any buffered data for the open file is written to the media.

Functions, handle=0

&00	Return filing system number in A: 0 No current filing system 20 RawKbd: 1 1200 baud cassette filing system 21 DeskFS: 2 300 baud cassette filing system 22 Computer Concepts RomFS: 3 ROM filing system 23 RamFS: 4 Disk filing system 24 RISCiXFS: 5 Econet network filing system 25 Streamer: 6 Teletext/Prestel telesoftware 26 SCSIFS: 7 IEEE filing system 27 Digitiser: 8 Acorn ADFS 28 Scanner: 9 Host filing system 29 MultiFS: 10 Videodisk filing system 11 33 NFS: 12 RAM filing system NetPrint: 37 CDFS: 13 Null: 43 DOSFS: 14 Printer: 46 ResourceFS: 15 Serial: 47 PipeFS: 16 Harston ADFS 17 Vdu: 53 DeviceFS: 18 RawVdu: 54 Parallel: 19 Kbd:
&01	Returns the address of the command line tail, any parameters after a filename. The character at the address is the first non-space character after the name of the command (for example the 2 in *FORM80 2.) The address will always be in the I/O processor.
&02	Returns A=0 for ANFS 4.00+, A=1 if later bug-fixed versions of NFS, returns A=2 if early bug-ridden NFS or if call unsupported.
&03	Returns libfs filing system number in A.
&04	Returns used space on the device with the currently selected directory on.
&05	Returns free space on the device with the currently selected directory on.
&FD	Returns version number*10 in BCD in A and filing system capability flags in the data word.
&FE	Returns the last drive accessed in the data word.
&FF	Ensures any buffered data for all open files is written to the media.

Calling from BBC BASIC

• ptr=PTR#ch calls OSARGS 0,ch
• PTR#chn=ptr calls OSARGS 1,ch
• ptr=EXT#ch calls OSARGS 2,ch
• EXT#ch=ptr calls OSARGS 3,ch
• =EOF#ch calls OSBYTE 127 on 8-bit systems, which vectors via FSCV. Otherwise, =EOF#ch calls OSARGS 5,ch.

Special handles

When reading PTR and EXT from 8-bit BASIC, the data parameter is BASIC's integer store, which will be set to the channel as the last item evaluated. That means that PTR#0 and EXT#0 pass a data value of zero; OSARGS 0,0 and OSARGS 2,0 do not change the data word; this means that in 8-bit BASICs PTR#0 and EXT#0 return zero, being the unchanged data word set to the channel.

This means that other BASIC have the ability to use PTR#0 and EXT#0 to return information specific to that implementation. Some BASICs or operating systems allow other special handles to return specific information. Some operating systems allow BPUT#0 and BGET#0 to access the VDU and keyboard, so allow PTR#0, EXT#0 and EOF#0 to access keyboard or VDU information.

See Special handles.

Entry points

• BBC BASIC Entry Address: &FFDA
• 6502 Entry Address: &FFDA, vectors via &0214
• Z80 Entry Address: &FFDA, vectors via &FFDB
• 6809 Entry Address: &FFDA, vectors via &FFDB
• 80x86 Entry Address: INT &44, vectors via 0000:0110
• 32000 Entry Address: SVC &0C
• PDP-11 Entry Address: EMT 8, vector &08
• ARM Entry Address: SWI &09 "OS_Args", vector &09
• 68000 Entry Address: MOV #&09,A0:TRAP 12
• RISC-V Entry Address: ECALL &AC0008

Implementations

CFS

Not implemented, simply returns with an RTS instruction.

The Master 128 implements &00 fully, and &01 with a handle of 0.

ROMFS

Not implemented, simply returns with an RTS instruction.

The Master 128 implements &00 fully, and &01 with a handle of 0.

DFS

Acorn DFS 0.xx and 1.xx implements &FF to &02. DFS 2.xx and later also implements &03.

HDFS

Andrew Duggan's Hierarchial DFS implements OSARGS &03,Y as 'Read allocated space' instead of 'Write extent'.

Watford DFS

Implements &FE to &02. OSARGS &FE preserves A, so the returned data has to be examined to see if the call has been acted on with code such as:

   drive%=FNargs(&FE,-1)AND&FF

drive% will be &FF if not supported, or the drive number if it is.

NFS

NFS 3.34 returns the command line address incorrectly. It points to the first non-'*' character of the command, not the first character of the parameters. NFS 3.60 and later return the command line address correctly. NFS 3.60 and later return A<>2 from OSARGS 2,0 to indicate this.

HADFS

Implements &FD to &06.

Sprow ARM7 CoPro

When reading the current filing system with OS_Args all three parameters must be zero, including the data parameter. SYS "OS_Args",0,0,data does not return the filing system number unless data is zero. The data parameter cannot be left set to a random value as it can when calling on other platforms. ARM BBC BASIC translates calls to &FFDA correctly setting R2 to zero.

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 16:55, 6 November 2009 (UTC)