OSFIND

OSFIND: Open or close an object

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	= Handle of opened file, or &00 if not opened or unsupported
Y	H	Y	R1	BX	R2	R1	D1	A1	= handle if function=0	preserved
YX	HL	X	R1	BX	R2	R1	D1	A1	=>filename if function<>0	undefined

Functions
&00	Close the file specified by the handle. If handle=0, then close all files.
&4X	Open file for input. Returns 0 if the file does not exist.
&8X	Open file for output. If the file exists, sets its length to zero. Otherwise creates a file with load and execution addresses set to &FFFFFFFF and length set to zero.
&CX	Open file for update. Returns 0 if the file does not exist. Otherwise, the PTR (file pointer) is set to zero. Allows reading and writing, which both take place at the PTR.

In some filing systems the bottom bits of A control how the file is opened:

• b4 - a proposed extension is to open a file locked by another process.

• b3 - if set, returns an error if file not found, instead of zero handle.

• b2 - if set, error is generated if attempt to open a directory.

• b1-b0 - if 00, search for file with File$Path.

• b1-b0 - if 01, search for file with path pointed to by R2.

• b1-b0 - if 10, search for file with path pointed to by system variable pointed to by R2.

• b1-b0 - if 11, do not use any search path.

Note that it is possible to open a directory, but no input or output operations can be done.

Opening multiple times

Unless using a filing system that implements multiplexed file access:

• a file can be opened multiple times for input as long as the file has not already been opened for output.
• a file can be opened for output only as long as it has not already been opened for anything.

Overwriting existing files

When opening a file for output, if there is no pre-existing file a default amount of disk space is allocated to the new file. If there is a pre-existing file, then the space occupied by that file is used to write the new file to. If the programmer knows what size the written file will be it can be useful to create a dummy file of the correct size first with SAVE or CREATE before opening it.

Calling from BBC BASIC

• OPENIN f$ calls OSFIND &40. In BASIC I it calls OSFIND &C0.
• OPENOUT f$ calls OSFIND &80
• OPENUP f$ calls OSFIND &C0
• CLOSE#ch calls OSFIND &00

If OPENIN is typed into a BASIC I listing, SAVEd, and LOADed into BASIC II or later it will appear as OPENUP and still call OSFILE &C0 when executed. Likewise in the opposite direction. BASIC I does not recognise the word "OPENUP", or later BASIC's token for OPENIN. For further details see the B+ User Guide, chapter 49, p.476.

Entry points

• BBC BASIC Entry Address: &FFCE
• 6502 Entry Address: &FFCE, vectors via &021C
• Z80 Entry Address: &FFCE, vectors via &FFCF
• 6809 Entry Address: &FFCE, vectors via &FFCF
• 80x86 Entry Address: INT &40, vectors via 0000:0100
• 32000 Entry Address: SVC &0B
• PDP11 Entry Address: EMT 12, vector &0C
• ARM Entry Address: SWI &0D "OS_Find", vector &0D
• 68000 Entry Address: MOV #&0D,A0:TRAP 12
• RISC-V Entry Address: ECALL &AC000C

Implementations

File Addresses

There is inconsistency between systems as to what the load and execute addresses of a newly created file is given. Some systems set the load and execution addresses to &FFFFFFFF, some set them to 0, some leave them unchanged from any pre-existing file. If the addresses need to be set, they should be done after closing the file.

CFS

CFS allows one input file and one output file to be opened.

ROMFS

ROMFS allows one input file to be opened. Files cannot be opened for output. Any call with A=&8x or A=&Cx will give a Bad command error.

DFS

DFS allows up to five files to be opened. A newly created output file is allocated &4000 (16K) bytes of disk space.

HDFS

HDFS allows up to six files to be opened.

NFS

NFS allows up to eight objects to be opened, including the user's context directories. Up to three handles will be used for each of the user root directory, the current directory and the library directory. If any of the context directories are the same they will use the same handle. So, if all three context directories are the same, only one handle will be used.

Consequently, there will normally be five file handles available.

ANFS claims to allow up to 16 handles to be used, but I have never been able to get more than 8 file handles returned.

ADFS

ADFS allows up to eight objects to be opened. A newly created output file is allocated &10000 (64K) bytes of disk space.

HADFS

HADFS allows up to five objects to be opened. A newly created output file is allocated &4000 (16K) bytes of disk space. HADFS recognises the flags in b2 and b3 of the OPEN function code.

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:00, 6 November 2009 (UTC) Jgharston (talk) 22:48, 9 March 2015 (UTC)