/*
 * Name   : file.h
 * Desc   : whole/part file handling for manual program
 * Author : James Bye
 * Date   : 15th October 1991
 */

#define __file_h

#ifndef __kernel_h
#include "kernel.h"
#endif


#ifndef BOOL
#define BOOL int
#define TRUE   1
#define FALSE  0
#endif


/*
 * Name : file_lasterror
 * Desc : returns the last error encountered by this module
 * In   : None
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_lasterror ( void );


/*
 * Name : file_memdump
 * Desc : dumps memory to a file
 * In   : char *filename   - pointer to a filename
 *        int   filetype   - filetype number
 *        char *buffer     - pointer to a buffer
 *        int   size       - size of buffer
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_memdump ( char *filename, int filetype,
                                       char *buffer, int size       );


/*
 * Name : file_writecat
 * Desc : a group of functions that deal with catalogue writing
 *        they are prototyped as follows :-
 *
 *    file_writecat1  - writes load address,exec address,attribs to file
 *    file_writecat2  - writes load address only
 *    file_writecat3  - writes execution address only
 *    file_writecat4  - writes attribs only
 *    file_writecat9  - date/time stamp; filetype to data
 *    file_writecat18 - set filetype and stamp
 *
 * In  : int   code- reason code           
 *       char *p   - pathname
 *       int   r2  - register value for R2 - depending on call
 *       int   r3  - register value for R3 - depending on call
 *       int   r5  - register value for R5 - depending on call
 * Out : pointer to error block
 * Info: for call 1  - r2:  load address
 *                     r3:  exec address
 *                     r5:  attribs
 *       for call 2  - r2:  load address
 *       for call 3  - r3:  execution address
 *       for call 4  - r5:  attribs
 *       for call 9  - None
 *       for call 18 - r2:  filetype
 */

#ifndef __writecat_protos
#define file_writecat1(p,load_addr,exec_addr,attribs) file_writecat(1,p,load_addr,exec_addr,attribs)
#define file_writecat2(p,load_addr)                   file_writecat(2,p,load_addr,0,0)
#define file_writecat3(p,exec_addr)                   file_writecat(3,p,0,exec_addr,0)
#define file_writecat4(p,attribs)                     file_writecat(4,p,0,0,attribs)
#define file_writecat9(p)                             file_writecat(9,p,0,0,0)
#define file_writecat18(p,filetype)                   file_writecat(18,p,filetype,0,0)
#endif

extern _kernel_oserror *file_writecat ( int code, char *p, int r2, int r3, int r5 );


/*
 * Name : file_readcat
 * Desc : reads catalogue information for a file
 * In   : char *filename   - pointer to a filename
 *        int  *type       - pointer for the type
 *        int  *laddr      - pointer for load address 
 *        int  *eaddr      - pointer for exec address
 *        int  *length     - pointer for length
 *        int  *attrib     - pointer for attributes
 * Out  : returns pointer to error block
 * Info : any of the destination pointer can set to NULL and if so
 *        then they will not be written to
 *        to find the size only, you would call as follows :-
 *         file_readcat(filename,NULL,NULL,NULL,&size,NULL);
 */                        

extern _kernel_oserror *file_readcat ( char *filename, int *type, int *laddr, int *eaddr,
                                       int *length, int *attrib );



/*
 * Name : file_delete ( char *filename )
 * Desc : deletes a named file
 * In   : char *filename   - the name of the file
 * Out  : pointer to an error block
 */

extern _kernel_oserror *file_delete ( char *filename );


/*
 * Name : file_createfile
 * Desc : creates an empty file of specified size
 * In   : char *filename     - name of file to create
 *        int   filetype     - filetype
 *        int   size         - size of file to create
 * Out  : pointer to an error block
 */

extern _kernel_oserror *file_createfile ( char *filename, int filetype, int size );


/*
 * Name : file_createdir
 * Desc : creates a directory
 * In   : char *filename  - name of directory
 *        int entries     - number of files allowed in directory
 * Out  : pointer to an error block
 */

extern _kernel_oserror *file_createdir ( char *filename, int entries );


/*
 * Name : file_load
 * Desc : loads a named file into memory
 * In   : char *filename    - name of file to load
 *        int   address     - address of memory to load file in
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_load ( char *filename, int address );


/*
 * Name : file_read_seqptr
 * Desc : reads the files sequential pointer
 * In   : int  handle   - file handle
 *        int *seqptr   - desination for seq ptr
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_read_seqptr ( int handle, int *seqptr );

/*
 * Name : file_readline
 * Desc : read a 0x0a terminated line from a file
 * In   : int   handle      - file handle
 *        int   buffer      - pointer to buffer
 *        int   buffer size - max size of buffer
 * Out  : if int = -1, end of file was reached.
 */

extern int file_readline  ( int handle, char *buffer, int buf_size);

/*
 * Name : file_writealine
 * Desc : Write a 0x0a terminated line to a file
 * In   : int   handle      - file handle
 *        int   string      - pointer to string
 *        int   buffer size - max size of string
 * Out  : 
 * Info : if seqptr == -1 then writing will start from current
 *        sequential file pointer
 */

extern int file_writealine  ( int handle, char *string, int string_size);


/*
 * Name : file_write_seqptr
 * Desc : writes the files sequential pointer
 * In   : int  handle  - file handle
 *        int  seqptr  - new seq ptr
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_write_seqptr ( int handle, int seqptr );


/*
 * Name : file_read_ext
 * Desc : reads a files open extent
 * In   : int  handle   - file handle
 *        int *ext      - destination for extent
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_read_ext ( int handle, int *ext );


/*
 * Name : file_write_ext
 * Desc : writes a files open extent
 * In   : int  handle   - file handle
 *        int  ext      - new extent
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_write_ext ( int handle, int ext );


/*
 * Name : file_read_allocsize
 * Desc : reads a files allocated size
 * In   : int  handle   - file handle
 *        int *size     - destination for size
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_read_allocsize ( int handle, int *size );


/*
 * Name : file_read_EOF
 * Desc : reads a files EOF state
 * In   : int  handle - files handle
 * Out  : TRUE if EOF else FALSE
 */

extern BOOL file_read_eof ( int handle );


/*
 * Name : file_ensure_size
 * Desc : Ensures an open files size
 * In   : int  handle  - file handle
 *        int  size    - size to ensure to
 * Out  : Pointer to error block
 */

extern _kernel_oserror *file_ensure_size ( int handle, int size );


#ifndef FILE_INFO_BITS_DEFINED
#define FILE_INFO_BITS_DEFINED
#define STREAM_INTERACTIVE       4
#define STREAM_SUPPORTS_GBPB     8
#define OBJECT_DIRECTORY        16
#define READ_ACCESS             32
#define WRITE_ACCESS            64
#define OBJECT_WRITTEN         128
#define END_OF_FILE            256
#define STREAM_UNBUFFERED      512
#define STREAM_UNALLOCATED    1024
#define STREAM_CRITICAL       2048
#define DATA_LOST             4096
#endif
 

/*
 * Name : file_read_handleinfo 
 * Desc : reads information on a files handle
 * In   : int handle   - file handle
 * Out  : status of file handle
 */

extern int file_read_handleinfo ( int handle );


/*
 * Name : file_readabyte
 * Desc : reads a byte from an open file
 * In   : int handle   - file handle
 * Out  : int          - byte read
 * Info : will return -1 if an error is encountered
 */

extern int file_readabyte ( int handle );



/*
 * Name : file_writeabyte
 * Desc : writes a byte to an open file
 * In   : int handle    - file handle
 *        int byte      - byte to write
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_writeabyte ( int handle, int byte );


/*
 * Name : file_writebytes
 * Desc : writes a buffer to an open file
 * In   : int   handle     - file handle
 *        char *buffer     - pointer to buffer to write
 *        int   offset     - offset in buffer to write from
 *        int   nwrite     - number of bytes to write to file
 *        int   seqptr     - sequential file pointer
 * Out  : pointer to error block    
 * Info : if seqptr == -1 then writing will start from current
 *        sequential file pointer
 */

extern _kernel_oserror *file_writebytes ( int handle, char *buffer,
                                          int offset, int nwrite,
                                          int seqptr               );


/*
 * Name : file_readbytes
 * Desc : writes a buffer to an open file
 * In   : int   handle     - file handle
 *        int   buffer     - pointer to buffer 
 *        int   nread      - number of bytes to read
 *        int   seqptr     - sequential file pointer
 * Out  : pointer to error block    
 * Info : if seqptr == -1 then writing will start from current
 *        sequential file pointer
 */

extern _kernel_oserror *file_readbytes  ( int handle, char *buffer,
                                          int nread,  int seqptr  );



#ifndef OPEN_TYPES
#define OPEN_TYPES
#define OPEN_EXIST_READ         "r"
#define OPEN_NEW_READ_WRITE     "wr"
#define OPEN_EXIST_READ_WRITE   "wr+"
#endif

/*
 * Name : file_open 
 * Desc : opens a specified file
 * In   : char *filename    - the file to open
 *        int  *handle      - destination for file handle
 *        char *oa          - open access indicator
 * Out  : pointer to error block
 */

extern _kernel_oserror *file_open ( char *filename, int *handle, char *oa );



/*
 * Name : file_close 
 * Desc : closes a file
 * In   : int handle  -  file handle
 * Out  : pointer to error block
 */
     
extern _kernel_oserror *file_close ( int handle );


