c_cpp/etc/calc/help/fpathopen

   1 NAME
   2     fpathopen - open an absolute or relative filename along a search path
   3
   4 SYNOPSIS
   5     fpathopen(filename, mode [,searchpath])
   6
   7 TYPES
   8     filename    string
   9     mode        string
  10     searchpath  string
  11
  12     return      file
  13
  14 DESCRIPTION
  15     This function opens the file named filename, potentially searching
  16     for the file along a search path given by searchpath.  If searchpath
  17     is not given, then CALCPATH search path is used.
  18
  19     If the filename is absolute, or it has an implied path, then
  20     searchpath is ignored and the filename is opened directly.
  21     Absolute filenames, and filenames with an implied path are files
  22     that begin with:
  23
  24         /       # absolute path
  25         ./      # implied path through the current working directory
  26         ../     # implied path through the current working directory parent
  27         ~       # absolute path going through a home directory
  28
  29     A search path is a :-separated list of directories used to search for
  30     a filename.  For example:
  31
  32         fpathopen("whey", "r", ".:/tmp:/var/tmp:~chongo/pub:~/tmp");
  33
  34     will cause this function to open the first readable file it
  35     files while searching through these paths in order:
  36
  37         ./whey
  38         /tmp/whey
  39         /var/tmp/whey
  40         ~chongo/pub/whey
  41         ~/tmp/whey
  42
  43     IMPORTANT NOTE:
  44
  45     This function searches along a path by attempting
  46     to open files under the given mode.  If the mode allows for
  47     writing and a file can be created, then that file is returned.
  48
  49     This call open "./gleet" for writing if the current directory is
  50     writable, even if "./gleet" did not previously exist:
  51
  52         fpathopen("gleet", "r", ".:/tmp:/var/tmp:~chongo/pub:~/tmp");
  53
  54     This call will likely open (and create if needded) for appending,
  55     the file "/tmp/log" assuming that the user is not allowed to
  56     create files in the previous system directories:
  57
  58         fpathopen("log", "a", "/:/etc:/bin:/usr/bin:/tmp");
  59
  60     The CALCPATH search path is taken from the $CALCPATH environment
  61     variable or if no such variable exists, a compiled in default search
  62     path is used.  See "help environment" and "help calcpath" for more
  63     information on CALCPATH.
  64
  65     It should be noted that while CALCPATH is typically used to find
  66     resource files (*.cal files), this function is not restricted those
  67     files.  Any filename may be opened.
  68
  69     A file can be opened for either reading, writing, or appending.
  70     The mode is controlled by the mode flag as follows:
  71
  72                  allow    allow    file is   positioned   file(*)
  73        mode     reading  writing  truncated      at       mode
  74        ----     -------  -------  ---------  ---------    ----
  75         r          Y        N         N      beginning    text
  76         rb         Y        N         N      beginning    binary
  77         r+         Y        N         N      beginning    text
  78         r+b        Y        N         N      beginning    binary
  79         rb+        Y        N         N      beginning    binary
  80
  81         w          N        Y         Y      beginning    text
  82         wb         N        Y         Y      beginning    binary
  83         w+         Y        Y         Y      beginning    text
  84         w+b        Y        Y         Y      beginning    binary
  85         wb+        Y        Y         Y      beginning    binary
  86
  87         a          N        Y         Y         end       text
  88         ab         N        Y         Y         end       binary
  89         a+         Y        Y         Y         end       text
  90         a+b        Y        Y         Y         end       binary
  91         ab+        Y        Y         Y         end       binary
  92
  93     (*) NOTE on 'b' / binary/text mode:
  94
  95         The 'b' or fopen binary mode has no effect on POSIX / Linux
  96         / Un*x-like systems.  On those systems a text file is the
  97         same as a binary file (as it should be for any modern-day
  98         operating system).  Adding 'b' to an fopen has no effect
  99         and is ignored.
 100
 101         Some non-POSIX systems sucn as MS Windoz treat text files
 102         and binary files differently.  In text mode MS Windoz consider
 103         "\r\n" and end-of-line character.  On an Apple MAC, the
 104         text mode end-of-line character is "\r".
 105
 106     Names of files are subject to ~ expansion just like the C or
 107     Korn shell.  For example, the file name:
 108
 109         ~/lib/gleet
 110
 111     refers to the file 'gleet' under the directory lib located
 112     in your home directory.  The file name:
 113
 114         ~chongo/was_here
 115
 116     refers to the a file 'was_here' under the home directory of
 117     the user 'chongo'.
 118
 119     If the open is successful, a value of type 'file' will be returned.
 120     You can use the 'isfile' function to test the return value to see
 121     if the open succeeded.  You should assign the return value of fopen
 122     to a variable for later use.  File values can be copied to more than
 123     one variable, and using any of the variables with the same file value
 124     will produce the same results.
 125
 126     Standard input, standard output and standard error are always opened
 127     and cannot be closed.
 128
 129     The truth value of an opened file is TRUE.
 130
 131     If the open is unsuccessful, the numeric value of errno is returned.
 132     You can the errno() builtin to determine what the errno number means.
 133
 134 EXAMPLE
 135     ; fd = fpathopen("motd", "r", "/etc:.")
 136     ; print fd
 137     "/etc/motd"
 138     ; fd
 139             FILE 3 "/etc/motd" (reading, pos 0)
 140
 141     ; fd2 = fpathopen("lucas.cal", "r")
 142     ; print fd2
 143     "/usr/share/calc/lucas.cal"
 144     ; fd2
 145             FILE 4 "/usr/share/calc/lucas.cal" (reading, pos 0)
 146
 147     ; fd3 = fpathopen("randmprime.cal", "r", calcpath())
 148     ; print fd3
 149     "/usr/share/calc/randmprime.cal"
 150     ; fd3
 151             FILE 5 "/usr/share/calc/randmprime.cal" (reading, pos 0)
 152
 153     ; fd4 = fpathopen("output", "w", "~/tmp:/tmp:/var/tmp")
 154     ; print fd4
 155     "/home/chongo/tmp/output"
 156     ; fd4
 157             FILE 6 "/home/chongo/tmp/output" (writing, pos 0)
 158
 159     ; !mkdir -p /tmp/log
 160     ; !touch /tmp/log/file
 161     ; logfile = fpathopen("log/file", "a", "/tmp:/var/tmp")
 162     ; print logfile
 163     "/tmp/log/file"
 164     ; logfile
 165             FILE 7 "/home/chongo/tmp/output" (writing, pos 0)
 166
 167     ; badfile = fpathopen("no_such_file", "r")
 168     ; if (!isfile(badfile)) print "error #" errno(badfile) : \
 169       ":" : strerror(badfile);
 170     error #2: No such file or directory
 171
 172 LIMITS
 173     none
 174
 175 LINK LIBRARY
 176     none
 177
 178 SEE ALSO
 179     errno, fclose, feof, ferror, fflush, fgetc, fgetline, fgets, files, fopen,
 180     fprintf, fputc, fputs, fseek, fsize, ftell, isfile, printf, prompt,
 181     environment, calcpath
 182
 183 ## Copyright (C) 2006  Landon Curt Noll
 184 ##
 185 ## Calc is open software; you can redistribute it and/or modify it under
 186 ## the terms of the version 2.1 of the GNU Lesser General Public License
 187 ## as published by the Free Software Foundation.
 188 ##
 189 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 190 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 191 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 192 ## Public License for more details.
 193 ##
 194 ## A copy of version 2.1 of the GNU Lesser General Public License is
 195 ## distributed with calc under the filename COPYING-LGPL.  You should have
 196 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 197 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 198 ##
 199 ## @(#) $Revision: 30.2 $
 200 ## @(#) $Id: fpathopen,v 30.2 2013/08/11 08:41:38 chongo Exp $
 201 ## @(#) $Source: /usr/local/src/bin/calc/help/RCS/fpathopen,v $
 202 ##
 203 ## Under source code control:   2006/05/07 23:56:04
 204 ## File existed as early as:    2006
 205 ##
 206 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 207 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/