fopen

NAME
    fopen - open a file

SYNOPSIS
    fopen(filename, mode)

TYPES
    filename    string
    mode        string

    return      file

DESCRIPTION
    This function opens the file named filename.  A file can be
    opened for either reading, writing, or appending.  The mode
    is controlled by the mode flag as follows:

                 allow    allow    file is   positioned   file(*)
       mode     reading  writing  truncated      at       mode
       ----     -------  -------  ---------  ---------    ----
        r          Y        N         N      beginning    text
        rb         Y        N         N      beginning    binary
        r+         Y        N         N      beginning    text
        r+b        Y        N         N      beginning    binary
        rb+        Y        N         N      beginning    binary

        w          N        Y         Y      beginning    text
        wb         N        Y         Y      beginning    binary
        w+         Y        Y         Y      beginning    text
        w+b        Y        Y         Y      beginning    binary
        wb+        Y        Y         Y      beginning    binary

        a          N        Y         Y         end       text
        ab         N        Y         Y         end       binary
        a+         Y        Y         Y         end       text
        a+b        Y        Y         Y         end       binary
        ab+        Y        Y         Y         end       binary

    (*) NOTE on 'b' / binary/text mode:

        The 'b' or fopen binary mode has no effect on POSIX / Linux
        / Un*x-like systems.  On those systems a text file is the
        same as a binary file (as it should be for any modern-day
        operating system).  Adding 'b' to an fopen has no effect
        and is ignored.

        Some non-POSIX systems such as MS Windows treat text files
        and binary files differently.  In text mode MS Windows consider
        "\r\n" an end-of-line character.  On an Apple MAC, the
        text mode end-of-line character is "\r".

    Names of files are subject to ~ expansion just like the C or
    Korn shell.  For example, the file name:

        ~/lib/fizzbin

    refers to the file 'fizzbin' under the directory lib located
    in your home directory.  The file name:

        ~chongo/was_here

    refers to the a file 'was_here' under the home directory of
    the user 'chongo'.

    If the open is successful, a value of type 'file' will be returned.
    You can use the 'isfile' function to test the return value to see
    if the open succeeded.  You should assign the return value of fopen
    to a variable for later use.  File values can be copied to more than
    one variable, and using any of the variables with the same file value
    will produce the same results.

    Standard input, standard output and standard error are always opened
    and cannot be closed.

    The truth value of an opened file is TRUE.

    If the open is unsuccessful, the numeric value of errno is returned.
    You can the strerror() builtin to determine what the errno number means.

EXAMPLE
    ; fd = fopen("/etc/motd", "r")
    ; print fd
    "/etc/motd"
    ; fd
            FILE 3 "/etc/motd" (reading, pos 0)

    ; outfile = fopen("~/tmp/output", "w")
    ; print outfile
    "~/tmp/output"
    ; outfile
            FILE 4 "~/tmp/output" (writing, pos 0)

    ; badfile = fopen("not_a_file", "r");
    ; if (!isfile(badfile)) {
    ;;     printf("error(%d): %s\n", errno(badfile), strerror(badfile));
    ;; }
    error(2): No such file or directory

LIMITS
    none

LINK LIBRARY
    none

SEE ALSO
    errno, fclose, feof, ferror, fflush, fgetc, fgetline, fgets, files, fopen,
    fprintf, fputc, fputs, fseek, fsize, ftell, isfile, printf, prompt,
    fpathopen, strerror

## Copyright (C) 1999-2006,2021  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## Under source code control:   1994/10/27 03:04:17
## File existed as early as:    1994
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/