help/fopen

   1 NAME
   2     fopen - open a file
   3
   4 SYNOPSIS
   5     fopen(filename, mode)
   6
   7 TYPES
   8     filename    string
   9     mode        string
  10
  11     return      file
  12
  13 DESCRIPTION
  14     This function opens the file named filename.  A file can be
  15     opened for either reading, writing, or appending.  The mode
  16     is controlled by the mode flag as follows:
  17
  18                  allow    allow    file is   positioned   file(*)
  19        mode     reading  writing  truncated      at       mode
  20        ----     -------  -------  ---------  ---------    ----
  21         r          Y        N         N      beginning    text
  22         rb         Y        N         N      beginning    binary
  23         r+         Y        N         N      beginning    text
  24         r+b        Y        N         N      beginning    binary
  25         rb+        Y        N         N      beginning    binary
  26
  27         w          N        Y         Y      beginning    text
  28         wb         N        Y         Y      beginning    binary
  29         w+         Y        Y         Y      beginning    text
  30         w+b        Y        Y         Y      beginning    binary
  31         wb+        Y        Y         Y      beginning    binary
  32
  33         a          N        Y         Y         end       text
  34         ab         N        Y         Y         end       binary
  35         a+         Y        Y         Y         end       text
  36         a+b        Y        Y         Y         end       binary
  37         ab+        Y        Y         Y         end       binary
  38
  39     (*) NOTE on 'b' / binary/text mode:
  40
  41         The 'b' or fopen binary mode has no effect on POSIX / Linux
  42         / Un*x-like systems.  On those systems a text file is the
  43         same as a binary file (as it should be for any modern-day
  44         operating system).  Adding 'b' to an fopen has no effect
  45         and is ignored.
  46
  47         Some non-POSIX systems sucn as MS Windoz treat text files
  48         and binary files differently.  In text mode MS Windoz consider
  49         "\r\n" and end-of-line character.  On an Apple MAC, the
  50         text mode end-of-line character is "\r".
  51
  52     Names of files are subject to ~ expansion just like the C or
  53     Korn shell.  For example, the file name:
  54
  55         ~/lib/gleet
  56
  57     refers to the file 'gleet' under the directory lib located
  58     in your home directory.  The file name:
  59
  60         ~chongo/was_here
  61
  62     refers to the a file 'was_here' under the home directory of
  63     the user 'chongo'.
  64
  65     If the open is successful, a value of type 'file' will be returned.
  66     You can use the 'isfile' function to test the return value to see
  67     if the open succeeded.  You should assign the return value of fopen
  68     to a variable for later use.  File values can be copied to more than
  69     one variable, and using any of the variables with the same file value
  70     will produce the same results.
  71
  72     Standard input, standard output and standard error are always opened
  73     and cannot be closed.
  74
  75     The truth value of an opened file is TRUE.
  76
  77     If the open is unsuccessful, the numeric value of errno is returned.
  78     You can the errno() builtin to determine what the errno number means.
  79
  80 EXAMPLE
  81     > fd = fopen("/etc/motd", "r")
  82     > print fd
  83     "/etc/motd"
  84     > fd
  85             FILE 3 "/etc/motd" (reading, pos 0)
  86
  87     > outfile = fopen("~/tmp/output", "w")
  88     > print outfile
  89     "~/tmp/output"
  90     > outfile
  91             FILE 4 "~/tmp/output" (writing, pos 0)
  92
  93     > badfile = fopen("not_a_file", "r")
  94     > if (!isfile(badfile)) print "error #" : badfile : ":", errno(badfile);
  95     error #2: No such file or directory
  96
  97 LIMITS
  98     none
  99
 100 LINK LIBRARY
 101     none
 102
 103 SEE ALSO
 104     errno, fclose, feof, ferror, fflush, fgetc, fgetline, fgets, files, fopen,
 105     fprintf, fputc, fputs, fseek, fsize, ftell, isfile, printf, prompt
 106