[Overview][Constants][Types][Classes][Procedures and functions][Variables][Index] | Reference for unit 'sysutils' (#rtl)

# FileOpen

Open an existing file and return a file handle

## Declaration

Source position: filutilh.inc line 171

`function FileOpen(`
`const FileName: unicodestring;`
`Mode: Integer`
`):THandle; function FileOpen(`
`const FileName: RawByteString;`
`Mode: Integer`
`):THandle;`

## Description

FileOpen opens a file with name FileName with mode Mode. Mode can be one of the following constants:

fmOpenRead
  Open file in read-only mode
fmOpenWrite
  Open file in write-only mode
fmOpenReadWrite
  Open file in read/write mode.

Under Windows and Unix, the above mode can be or-ed with one of the following sharing/locking flags:

fmShareCompat
  Open file in DOS share-compatibility mode
fmShareExclusive
  Lock file for exclusive use
fmShareDenyWrite
  Lock file so other processes can only read.
fmShareDenyRead
  Lock file so other processes cannot read.
fmShareDenyNone
  Do not lock file.

If the file has been successfully opened, it can be read from or written to (depending on the Mode parameter) with the FileRead and FileWrite functions.

Remark: | Remark that you cannot open a file if it doesn't exist yet, i.e. it will not be created for you. If you want tp create a new file, or overwrite an old one, use the FileCreate function.

There are some limitations to the sharing modes.

1. Sharing modes are only available on Unix and Windows platforms.
2. Unix only support sharing modes as of 2.4.0.
3. fmShareDenyRead only works under Windows at this time, and will always result in an error on Unix platforms because its file locking APIs do not support this concept.
4. File locking is advisory on Unix platforms. This means that the locks are only checked when a file is opened using a file locking mode. In other cases, existing locks are simply ignored. In particular, this means that fmShareDenyNone has no effect under Unix, because this can only be implemented as ``use no locking'' on those platforms. As a result, opening a file using this mode will always succeed under Unix as far as the locking is concerned, even if the file has already been opened using fmShareExclusive.
5. Under Solaris, closing a single file handle associated with a file will result in all locks on that file (even via other handles) being destroyed due to the behaviour of the underlying API (fcntl). Because of the same reason, on Solaris you cannot use fmShareDenyWrite in combination with fmOpenWrite, nor fmShareExclusive in combination with fmOpenRead although both work with fmOpenReadWrite.

For an example, see FileCreate

## Errors

On Error, THandle(-1) is returned.

## See also

fmOpenRead |  | Open file in read-only mode
fmOpenWrite |  | Open file in write-only mode
fmOpenReadWrite |  | Open file in read/write mode.
fmShareDenyWrite |  | Lock file so other processes can only read.
fmShareExclusive |  | Lock file for exclusive use
fmShareDenyRead |  | Lock file so other processes cannot read.
fmShareDenyNone |  | Do not lock file.
fmShareCompat |  | Open file in DOS share-compatibility mode
FileClose |  | Close a file handle.
FileWrite |  | Write data from a buffer to a given file handle.
FileCreate |  | Create a new file and return a handle to it.
FileRead |  | Read data from a file handle in a buffer.
FileTruncate |  | Truncate an open file to a given size.
FileSeek |  | Set the current file position on a file handle.

Documentation generated on: May 14 2021