Filing Systems

FileSwitch

Enumerate Handles

A reason code is available within FileSwitch version 2.44 onward to enumerate file handles. This allows clients to obtain information on open files using a defined interface rather than relying on knowledge of the earlier restriction within FileSwitch of 255 file handles, allocated sequentially downward from 255.

OS_FSControl 58 (enumerate file handles)

On entry

   R0 = 58 (reason code)
   R1 = last handle, or -1 to start at first handle

On exit

   R0 = stream status word, or preserved if no more handles exist
   R1 = file handle, or -1 if no more handles exist
   R2 = filing system info word, or preserved if no more handles exist

This reason code is used by clients wishing to enumerate open file handles. Clients should be aware that filing system operations may occur during the enumeration process and should take appropriate action.

Catalogue filename width

A variable, FileSwitch$NameWidth, can be set to give the width of filenames in the *Cat display. It has a minimum value of 12, and a maximum value of 255. This can be set at any time and will be read per-use of *Cat. It is present in all versions of FileSwitch since RISC OS 4.

IOCtl operations

From FileSwitch 2.36 onward support has been added for IOCtl calls. These allow 'control' commands from the client opening the file. An OS_Args reason code has been added to support this, and a new bit added to the extra filing system information word.

OS_Args 9 (IOCtl)

On entry

   R0 = 9 (reason code)
   R1 = file handle
   R2 = pointer to parameter block

On exit

   R0-R2 preserved

This call is used by clients wishing to control devices at the other end of a file handle. This may be used for filing specific operations. This operation will be passed to the FileSystem Args entry as reason code 11.

The IOCtl parameter block takes the following form :

   +0 - Flags:
         bits 0-15  = IOCtl reason code
         bits 16-23 = IOCtl group code :
               0 = Serial group operations
               1 = Parallel group operations
               255= Generic group operations
                     bits 24-29 = reserved (must be 0)
                     bit  30  = set to read data
                     bit  31  = set to write data
   +4... Data for operation

Parallel IOCtl operations

The following parallel IOCtl operation reason codes are supported by the parallel device driver :

1. Read Device ID size
2. Read Device ID data
3. Read Reverse Nibble status size
4. Read Reverse Nibble status data

In each case the first word of the data indicates the size of the buffer.

Serial IOCtl operations

The following serial IOCtl operation reason codes are defined for serial devices :

    1 Baud rate
      One word containing the baud rate (bits per second)
    2 Data format
      One word containing flags indicating data format:
        bit 0-7 = data length (5,6,7 or 8)
        bit 8-15 = number of stop bits (1 or 2)
        bit 16-23 = parity encoded as
                       0 = no parity
                       1 = even parity
                       2 = odd parity
                    others reserved
        bit 24-31 = reserved
    3 Handshake
      One word containing the handshaking type:
         0 = no handshaking
         1 = RTS/CTS handshaking
         2 = XON/XOFF handshaking
         3 = DTR/DSR handshaking
      others reserved
    4 Buffer size
      Size of buffer used for transfers
    5 Buffer Threshold
      Trigger for handshaking or upcall notification
    6 Control lines
      One word containing flags :
        bits 0-15 read/write:
          bit 0 : DTR
          bit 1 : RTS
          bit 2-15 : reserved
        bits 16-31 read only:
          bit 16 : CTS
          bit 17 : DSR
          bit 18 : RI
          bit 19 : DCD
          bit 20 : FIFOs enabled
          bit 21-31 : reserved
    7 FIFO trigger
      Number of bytes in FIFO before an interrupt is generated.
    8 Read number of baud rates
      Returns a word containing the number of baud rates available
    9 Read baud rate index
      Supplies one word of index numbers and reads the baud rate associated
      with that index.
   10 Flush buffer
      Flushes buffer on write; undefined on read
   11 Read IR capabilities
      One word containing flags :
        bit 0 = IrDA capable
        bit 1 = Consumer IR capable
        bit 2 = ASK-IR capable
        bit 3-31 = reserved
   12 IR status
      One word containing the type of IR:
        0 : Wired
        1 : IrDA
        2 : ConsumerIR
        3 : Ask-IR
      Others reserved

Generic IOCtl operations

The following IOCtl operations have been defined for generic operations :

1. Non-blocking operation. A word containing 0 for blocking operation, any other value indicating non-blocking operation

2. Buffer threshold. A word indicating a point in the buffer at which a notification will be raised.

3. Flush stream. No data; writing causes all pending data to be discarded

4. Timeout. Time in centiseconds before a blocking operation should be considered failed.

Filing system redeclaration

As a reminder, PRM 2-524 indicates that filing systems should redeclare themselves to FileSwitch when Service_FSRedeclare is issued. Some external filing systems do not do this and thus cannot cope when the FileSwitch module is restarted.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015