c_cpp/etc/calc/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 strerror() 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)) {
  95     ;;     printf("error(%d): %s\n", errno(badfile), strerror(badfile));
  96     ;; }
  97     error(2): No such file or directory
  98
  99 LIMITS
 100     none
 101
 102 LINK LIBRARY
 103     none
 104
 105 SEE ALSO
 106     errno, fclose, feof, ferror, fflush, fgetc, fgetline, fgets, files, fopen,
 107     fprintf, fputc, fputs, fseek, fsize, ftell, isfile, printf, prompt,
 108     fpathopen, strerror
 109
 110 ## Copyright (C) 1999-2006  Landon Curt Noll
 111 ##
 112 ## Calc is open software; you can redistribute it and/or modify it under
 113 ## the terms of the version 2.1 of the GNU Lesser General Public License
 114 ## as published by the Free Software Foundation.
 115 ##
 116 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 117 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 118 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 119 ## Public License for more details.
 120 ##
 121 ## A copy of version 2.1 of the GNU Lesser General Public License is
 122 ## distributed with calc under the filename COPYING-LGPL.  You should have
 123 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 124 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 125 ##
 126 ## @(#) $Revision: 30.1 $
 127 ## @(#) $Id: fopen,v 30.1 2007/03/16 11:10:42 chongo Exp $
 128 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/fopen,v $
 129 ##
 130 ## Under source code control:   1994/10/27 03:04:17
 131 ## File existed as early as:    1994
 132 ##
 133 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 134 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/