file file management

## Syntax

                [unit, err] = file("open", file-name [,status] [,access [,recl]] [,format])
                file("close", unit)
                file("rewind", unit)
                file("backspace", unit)
                file("last", unit)
                [units, typ, nams, mod, swap] = file()
                [units, typ, nams, mod, swap] = file(unit)

## Arguments

file-name

  string, file name of the file to be opened

  This function can not open files whose path has non-ascii UTF characters (accented, etc). In this case, mopen() must be used.
status

  string, The status of the file to be opened

  "new"

    file must not exist new file (default)

  "old"

    file must already exists.

  "unknown"

    unknown status

  "scratch"

    file is to be deleted at end of session

access

  string, The type of access to the file

  "sequential"

    sequential access (default)

  "direct"

    direct access. The next input argument `recl` is then mandatory.

format

  string,

  "formatted"

    for a formatted file (default)

  "unformatted"

    binary record.

recl

  integer,is the size of records in bytes when `access="direct"`

unit

  integer, logical unit descriptor of the opened file

units

  integer vector, logical unit descriptor of the opened files. Units 5 and 6 (%io) are reserved by the system for input and output devices.

typs

  Character string vector, type (C or Fortran) of opened files.

nams

  Character string vector, pathnames of opened files.

mod

  file opening mode. Formed by three digits abc:

  >Fortran files
  a | 0 stands for formatted and 1 for unformatted (binary)
  b | 0 stands for sequential access and 1 for direct access
  c | 0 stands for "new", 1 for "old", 2 for "scratch" and 3 for "unknown"
  C files
  a | 1 stands for "r" (read), 2 stands for "w" (write) and 3 for "a" (append)
  b | is 1 if file has been opened with a "+" (updating) mode
  c | is 1 if file has been opened with a "b" (binary) mode

swap

  automatic swap switch. swap=1 if automatic swap is on. swap is always 0 for Fortran files.

err

  integer code returned if opening the file fails. If `err` is omitted, an error message is issued.

  65 | File already used
  66 | Too many files opened!
  67 | Unknown file format
  240 | The file already exists or directory write access denied.
  241 | The file does not exist or read access denied.

## Description

`file(…)` selects a logical unit `unit` and manages the file `file-name`.

[unit [,err]]=file("open", file-name [,status] [,access [,recl]][,format])

  allows to open a file with specified properties and to get the associated unit number `unit`. This unit number may be used for further actions on this file or as file descriptor in `read`, `write`, `save`, `load` function calls.

file("close", unit)

  allows to close the file, or move the current file pointer.

file("rewind", unit)

  puts the pointer at the beginning of the file.

file("backspace", unit)

  puts the pointer at the beginning of last record.

file("last", unit)

  puts the pointer after last record.

file()

  returns the descriptors of the opened files.

  To test whether a file whose unit is `id` is opened, `file(id)~=[]` may be used.

  To close all user opened files (C or Fortran type), `file("close",file())` may be used.

## Examples

    u=file("open",TMPDIR+"/foo","unknown")
    for k=1:4
      a=rand(1,4)
      write(u,a)
    end
    file("rewind",u)
    x=read(u,2,4)
    file("close",u)
    //
    u1=file("open",TMPDIR+"/foo","unknown")
    u2=mopen(TMPDIR+"/foo1","wb")
    [units,typs,nams]=file()
    file("close",u1);
    mclose(u2);

## See also

- isfile
- read
- write
- mopen
- save
- load
- uigetfile

## History

6.0.0 stderr is inserted in the output of file() as units(1)=0, typ(1)="STD" and nams(1)="stderr".