file

早期freebsd实现

Using files

	The calculator provides some functions which allow the program to
	read or write text files.  These functions use stdio internally,
	and the functions appear similar to some of the stdio functions.
	Some differences do occur, as will be explained here.

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

		~/.rc.cal
	
	refers to the file '.rc.cal' under your home directory.  The
	file name:

		~chongo/.rc.cal

	refers to the a file 'rc.cal' under the home directory of 'chongo'.

	A file can be opened for either reading, writing, or appending.
	To do this, the 'fopen' function is used, which accepts a filename
	and an open mode, both as strings.  You use 'r' for reading, 'w'
	for writing, and 'a' for appending.  For example, to open the file
	'foo' for reading, the following could be used:

		fd = fopen('foo', 'r');

	If the open is unsuccessful, the numeric value of errno is returned.
	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.

	If you overwrite a variable containing a file value or don't save the
	result of an 'fopen', the opened file still remains open.  Such 'lost'
	files can be recovered by using the 'files' function.  This function
	either takes no arguments or else takes one integer argument.  If no
	arguments are given, then 'files' returns the maximum number of opened
	files.  If an argument is given, then the 'files' function uses it as
	an index into an internal table of open files, and returns a value
	referring to one the open files.  If that entry in the table is not
	in use, then the null value is returned instead.  Index 0 always
	refers to standard input, index 1 always refers to standard output,
	and index 2 always refers to standard error.  These three files are
	already open by the calculator and cannot be closed.  As an example
	of using 'files', if you wanted to assign a file value which is
	equivalent to stdout, you could use:

		stdout = files(1);

	The 'fclose' function is used to close a file which had been opened.
	When this is done, the file value associated with the file remains
	a file value, but appears 'closed', and cannot be used in further
	file-related calls (except fclose) without causing errors.  This same
	action occurs to all copies of the file value.  You do not need to
	explicitly close all the copies of a file value.  The 'fclose'
	function returns the numeric value of errno if there had been an
	error using the file, or the null value if there was no error.

	File values can be printed.  When this is done, the filename of the
	opened file is printed inside of quote marks.  If the file value had
	been closed, then the null string is printed.  If a file value is the
	result of a top-level expression, then in addition to the filename,
	the open mode, file position, and possible EOF, error, and closed
	status is also displayed.

	File values can be used inside of 'if' tests.  When this is done,
	an opened file is TRUE, and a closed file is FALSE.  As an example
	of this, the following loop will print the names of all the currently
	opened non-standard files with their indexes, and then close them:

		for (i = 3; i < files(); i++) {
			if (files(i)) {
				print i, files(i);
				fclose(files(i));
			}
		}

	The functions to read from files are 'fgetline' and 'fgetc'.
	The 'fgetline' function accepts a file value, and returns the next
	input line from a file.  The line is returned as a string value, and
	does not contain the end of line character.  Empty lines return the
	null string.  When the end of file is reached, fgetline returns the
	null value.  (Note the distinction between a null string and a null
	value.)  If the line contained a numeric value, then the 'eval'
	function can then be used to convert the string to a numeric value.
	Care should be used when doing this, however, since eval will
	generate an error if the string doesn't represent a valid expression.
	The 'fgetc' function returns the next character from a file as a
	single character string.  It returns the null value when end of file
	is reached.

	The 'printf' and 'fprintf' functions are used to print results to a
	file (which could be stdout or stderr).  The 'fprintf' function
	accepts a file variable, whereas the 'printf' function assumes the
	use of 'files(1)' (stdout).  They both require a format string, which
	is used in almost the same way as in normal C.  The differences come
	in the interpretation of values to be printed for various formats.
	Unlike in C, where an unmatched format type and value will cause
	problems, in the calculator nothing bad will happen.  This is because
	the calculator knows the types of all values, and will handle them
	all reasonably.  What this means is that you can (for example), always
	use %s or %d in your format strings, even if you are printing a non-
	string or non-numeric value.  For example, the following is valid:

		printf("Two values are %d and %s\n", "fred", 4567);

	and will print "Two values are fred and 4567".

	Using particular format characters, however, is still useful if
	you wish to use width or precision arguments in the format, or if
	you wish to print numbers in a particular format.  The following
	is a list of the possible numeric formats:

		%d		print in currently defined numeric format
		%f		print as floating point
		%e		print as exponential
		%r		print as decimal fractions
		%x		print as hex fractions
		%o		print as octal fractions
		%b		print as binary fractions

	Note then, that using %d in the format makes the output configurable
	by using the 'config' function to change the output mode, whereas
	the other formats override the mode and force the output to be in
	the specified format.

	Using the precision argument will override the 'config' function
	to set the number of decimal places printed.  For example:

		printf("The number is %.100f\n", 1/3);

	will print 100 decimal places no matter what the display configuration
	value is set to.

	The %s and %c formats are identical, and will print out the string
	representation of the value.  In these cases, the precision argument
	will truncate the output the same way as in standard C.

	If a matrix or list is printed, then the output mode and precision
	affects the printing of each individual element.  However, field
	widths are ignored since these values print using multiple lines.
	Field widths are also ignored if an object value prints on multiple
	lines.

	The final file-related functions are 'fflush', 'ferror', and 'feof'.
	The 'fflush' function forces buffered output to a file.  The 'ferror'
	function returns nonzero if an error had occurred to a file.  The
	'feof' function returns nonzero if end of file has been reached
	while reading a file.

	The 'strprintf' function formats output similarly to 'printf',
	but the output is returned as a string value instead of being
	printed.