Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File5.10.6  Fcreate                                                    TOS

 Name:         »File create« - Create a file.

 Opcode:       60

 Syntax:       int16_t Fcreate ( const int8_t *fname, int16_t attr );

 Description:  The GEMDOS routine Fcreate creates a new file, or 
               truncates an existing one, with a given name and 
               attributes. The following apply:

                Parameter  Meaning

                fname      Pointer to the filename.
                attr       File attributes:
                            Bit 0:  File is write-protected
                            Bit 1:  File is hidden
                            Bit 2:  File is a system file
                            Bit 3:  Volume label (diskette name)
                            Bit 5:  Archive bit

               Note: In a network, the creation of a file sets the 
               exclusivity. Whether the underlying GEMDOS is network 
               capable can be established via the cookie _FLK.

               Note about MagiC: If bit 3 in attr is set, then the XFS 
               function xfs_wlabel will be called. If this function 
               can be executed without an error, then the value 
               0x0000fffc will be returned. This corresponds to a 
               handle for the file NUL: or U:\DEV\NULL. However, this 
               feature is only present for reasons of compatibility; 
               as of MagiC 3, it is better to fall back on the 
               function Dwritelabel.

               The specified attributes exist only under DOS file- 
               systems and are ignored or emulated by other file- 
               systems. With the Macintosh file-system (HFS), for 
               instance, only bit 0 of attr is supported.

               Incidentally, symbolic links are dereferenced by this 
               function, so that if the file already exists as a 
               symbolic link, the file referenced from this link will 
               be set to zero length.

 Return value: The function returns the following results:

                EPTHNF :     Access path is incorrect.
                ENHNDL :     No more file handles left.
                EACCDN :     Write access denied.
                Otherwise :  ID of the file.

 Availability: All GEMDOS versions. However, GEMDOS Version 0.13 
               creating a read-only file returns a handle that is of 
               not much use. GEMDOS versions below 0.15 wrongly allow 
               more than one volume label per disk.

 Group:        File functions

 See also:     Binding   Fopen   XFS-concept in MagiC