Sign in Join
FPDoc Onlineexperiment

FileCreate function

In unit sysutils

Create a new file and return a handle to it.

Declaration

pascal
function FileCreate(const FileName: UnicodeString): THandle

Description

FileCreate creates a new file with name FileName on the disk and returns a file handle which can be used to read or write from the file with the FileRead and FileWrite functions.

If a file with name FileName already existed on the disk, it is overwritten.

The ShareMode parameter determines how file sharing is handled for the new file. It can have one or more of the following values, OR-ed together:

NameDescription
fmShareCompat

Open file in DOS share-compatibility mode.
fmShareDenyNone

Do not lock file.
fmShareDenyRead

Lock file so other processes cannot read.
fmShareDenyWrite

Lock file so other processes can only read.
fmShareExclusive

Lock file for exclusive use.

The optional Rights parameter only has an effect under UNIX, where it can be used to set the mode (read, write, execute, sticky bit, setgid and setuid flags) of the created file to the specified custom value. On other platforms, the Rights parameter is ignored.

Errors

If an error occurs (e.g. disk full or non-existent path), the function returns THandle(-1).

See also

Example: ex37

pascal
Program Example37;

{ This program demonstrates the FileCreate/FileSeek/FileReed/FileTruncate functions }

Uses sysutils;

Var I,J,F : Longint;

Begin
  F:=FileCreate ('test.dat');
  If F=-1 then
    Halt(1);
  For I:=0 to 100 do
    FileWrite(F,I,SizeOf(i));
  FileClose(f);
  F:=FileOpen ('test.dat',fmOpenRead);
  For I:=0 to 100 do
    begin
    FileRead (F,J,SizeOF(J));
    If J<>I then
      Writeln ('Mismatch at file position ',I)
    end;
  FileSeek(F,0,fsFromBeginning);
  Randomize;
  Repeat
    FileSeek(F,Random(100)*4,fsFromBeginning);
    FileRead (F,J,SizeOf(J));
    Writeln ('Random read : ',j);
  Until J>80;
  FileClose(F);
  F:=FileOpen('test.dat',fmOpenWrite);
  I:=50*SizeOf(Longint);
  If FileTruncate(F,I) then
    Writeln('SuccessFully truncated file to ',I,' bytes.');
  FileClose(F);
End.

An experiment, built from development snapshots. Not the official Free Pascal or Lazarus documentation.