# %open() function

The %open() function opens the host
OS file specified by *str* and sets the file status
flags according to the value of *oflag*.

## Syntax

```
 file.descriptor = %open(str, oflag, pmode)
```

## Parameter(s)

| str | Specifies the file name to open or create. |
| --- | --- |
| oflag | Specifies the status of the file. Valid values are defined in the include file: fcntl.h. Multiple flags can be specified in the syntax. |
| O$APPEND | Moves the file pointer to the end of the file. |
| O$BINARY | Opens in binary mode. |
| O$CREAT | Creates a new file with the name specified in str. Owner-ID and group-ID are set. The mode of the file is set according to the value of mode modified as follows: all bits in the file mode creation mask of the process are cleared and the sticky bit is cleared. If no value for the mode is specified when using the O$CREAT flag, an arbitrary value is used from your stack and undefined permissions are used. |
| O$EXCL | If O$EXCL and O$CREAT are set, open fails if the file exists. |
| O$NDELAY | Nonblocking I/O. The effect of this flag varies depending on the type of the file. See host OS system documentation. |
| O$RDONLY | Opens for reading only. |
| O$RDWR | Opens for reading and writing. |
| O$SYNC | Synchronized writes. |
| O$TEXT | Opens in text mode and translates text (default). For example: ^Z is assumed to be an end of line. |
| O$TRUNC | If the file exists, its length is set to 0. |
| O$WRONLY | Opens for writing only. |
| pmode | Specifies the read-write permissions for newly created files opened with the O$CREAT flag. Valid values are defined in the include file: mode.h. If no value for the mode is specified when using the O$CREAT flag, an arbitrary value is used from your stack and undefined permissions are used. |
| S$IRUSR | UNIX only. Opens a new file with read only permissions. |
| S$IWUSR | UNIX only. Opens a new file with write only permissions. |
| S$IREAD | Windows only. Opens a new file with read only permissions. |
| S$IWRITE | Windows only. Opens a new file with write only permissions. |

## Description

Files opened by %open() are closed automatically when the FlashBASIC program terminates.

The file descriptor is returned as a number or -1 if an error
occurred. system(0) contains the error number.

Note:

- There is a limit on the number of host OS files a process can have opened simultaneously. See your platform documentation.

- Files opened by a FlashBASIC program are normally closed automatically when the program terminates. However, it is a good practice to close them.

## Example(s)

```

 include dm,bp,unix.h fcntl.h
 fd=%open(’fname’, o$wronly+o$append)
 if fd<0 then
 crt ’Cannot open. errno=’:system(0)
 end
```

## See also

- [%close() function](https://d3codex.com/pickbasic-flashbasic/percent-close-function/)
- [%filecheck() function](https://d3codex.com/pickbasic-flashbasic/percent-filecheck-function/)
- [%fsize() function](https://d3codex.com/pickbasic-flashbasic/percent-fsize-function/)
- [%lseek() function](https://d3codex.com/pickbasic-flashbasic/percent-lseek-function/)
- [%rdhex() function](https://d3codex.com/pickbasic-flashbasic/percent-rdhex-function/)
- [%read() function](https://d3codex.com/pickbasic-flashbasic/percent-read-function/)
- [%ttyname() function](https://d3codex.com/pickbasic-flashbasic/percent-ttyname-function/)
- [%unlink ()function](https://d3codex.com/pickbasic-flashbasic/percent-unlink-function/)
- [%whex() function](https://d3codex.com/pickbasic-flashbasic/percent-whex-function/)
- [%write() function](https://d3codex.com/pickbasic-flashbasic/percent-write-function/)
- [FlashBASIC C functions overview](https://d3codex.com/pickbasic-flashbasic/flashbasic-c-functions-overview/)
- [cfunction statement](https://d3codex.com/pickbasic-flashbasic/cfunction-statement/)

---
Source: https://d3codex.com/pickbasic-flashbasic/percent-open-function/ - part of the D3Codex reference.