📄 mf_fopen.hlp
字号:
{title:Reading and writing in the same file}
{p 4 4 2}
You may read and write from a file opened "{cmd:rw}", using any of the read or
write functions described above. When reading and writing in the same file,
one often uses file repositioning functions, too;
see {it:Repositioning in a file} below.
{title:Reading and writing matrices}
{p 4 4 2}
Functions
{p 8 4 2}
{cmd:fputmatrix(}{it:fh}{cmd:,}
{it:transmorphic matrix X}{cmd:)}
{p 4 4 2}
and
{p 7 4 2}
{cmd:_fputmatrix(}{it:fh}{cmd:,}
{it:transmorphic matrix X}{cmd:)}
{p 4 4 2}
will write a matrix to a file. In the usual fashion, {cmd:fputmatrix()}
returns nothing (it aborts if there is an I/O error) and {cmd:_fputmatrix()}
returns a scalar equal to 0 if all went well and a negative error code
otherwise.
{p 4 4 2}
Functions
{p 8 4 2}
{cmd:fgetmatrix(}{it:fh}{cmd:)}
{p 4 4 2}
and
{p 7 4 2}
{cmd:_fgetmatrix(}{it:fh}{cmd:)}
{p 4 4 2}
will read a matrix written by {cmd:fputmatrix()} or {cmd:_fputmatrix()}. Both
functions return the matrix read, or return {cmd:J(0,0,.)} on end-of-file
(both functions) or error ({cmd:_fgetmatrix()} only). Since {cmd:J(0,0,.)}
could be the matrix that was written, distinguishing between that and
end-of-file requires subsequent use of {cmd:fstatus()}. {cmd:fstatus()} will
return 0 if {cmd:fgetmatrix()} or {cmd:_fgetmatrix()} returned a written
matrix, -1 if end-of-file, or (after {cmd:_fgetmatrix()}) a negative error
code.
{p 4 4 2}
{cmd:fputmatrix()} writes matrices in a compact, efficient, and portable
format; a matrix written on a Windows computer can be read back on a Macintosh
or Unix computer and vice versa.
{p 4 4 2}
The following code creates a file containing three matrices
{cmd}fh = fopen(filename, "w")
fputmatrix(fh, a)
fputmatrix(fh, b)
fputmatrix(fh, c)
fclose(fh){txt}
{p 4 4 2}
and the following code reads them back:
{cmd}fh = fopen(filename, "r")
a = fgetmatrix(fh)
b = fgetmatrix(fh)
c = fgetmatrix(fh)
fclose(fh){txt}
{hline}
{title:Technical note}
{p 8 8 2}
You may even write pointer matrices
{cmd}mats = (&a, &b, &c, NULL)
fh = fopen(filename,"w")
fput(fh, mats)
fclose(fh){txt}
{p 8 8 2}
and read them back:
{cmd}fh = fopen(filename, "r")
mats = fget(fh)
fclose(fh){txt}
{p 8 8 2}
When writing pointer matrices, {cmd:fputmatrix()} writes NULL for any
pointer-to-function value. It addition, it is recommended that you do not
write self-referential matrices (matrices that point to themselves, either
directly or indirectly), although the elements of the matrix may be cross
linked and even recursive themselves. To wit, if you are writing pointer
matrix {cmd:p}, no element of {cmd:p}, {cmd:*p}, {cmd:**p},
etc., should contain {cmd:&p}. That one address cannot be preserved
because in the assignment associated with reading back the matrix (the
"{it:result}{cmd:=}" part of {it:result}{cmd:=fgetmatrix(}{it:fh}{cmd:)},
a new matrix with a different address is associated with the contents.
{p_end}
{hline}
{title:Repositioning in a file}
{p 4 4 2}
The function
{p 8 8 2}
{cmd:ftell(}{it:fh}{cmd:)}
{p 4 4 2}
returns a real scalar reporting where you are in a file, and function
{p 8 8 2}
{cmd:fseek(}{it:fh}{cmd:,}
{it:real scalar offset}{cmd:,}
{it:real scalar whence}{cmd:)}
{p 4 4 2}
changes where you are in the file to be
{it:offset} bytes from the
beginning of the file ({it:whence} == -1),
{it:offset} bytes from the current position ({it:whence} == 0),
or {it:offset} bytes from the end of the file ({it:whence} == 1).
{p 4 4 2}
Functions {cmd:_ftell()} and {cmd:_fseek()} do the same thing as
{cmd:ftell()} and {cmd:fseek()}, the difference being that, rather
than aborting on error, the underscore functions return negative error
codes. {cmd:_ftell()} is pretty well useless as the only error that
can arise is I/O error, and what else are you going to do other than abort?
{cmd:_fseek()}, however, has a use, because it allows you to try out a
repositioning and check whether it was successful. With {cmd:fseek()},
if the repositioning is not successful, execution is aborted.
{p 4 4 2}
Say you open a file for read
{cmd:fh = fopen(filename, "r")}
{p 4 4 2}
After opening the file in mode "{cmd:r}", you are positioned at the beginning
of the file or, in the jargon of file processing, at position 0.
Now say you read ten bytes from the file:
{cmd:part1 = fread(fh, 10)}
{p 4 4 2}
Assuming that was successful, you are now at position 10 of the file.
Say you next read a line from the file
{cmd:line = fget(fh)}
{p 4 4 2}
and assume that {cmd:fget()} returns "abc". You are now at position 14 or
15. (No, not 13: {cmd:fget()} read the line and the newline characters
and returned the line. "abc" was followed by carriage-return and linefeed
(two characters) if the file was written under Windows, and
a carriage return or linefeed alone
(one character) if the file was written under Macintosh or Unix).
{p 4 4 2}
{cmd:ftell(}{it:fh}{cmd:)} and {cmd:_ftell(}{it:fh}{cmd:)} tell you where you
are in the file. Coding
{cmd:pos = ftell(fh)}
{p 4 4 2}
would store 14 or 15 in {cmd:pos}. Later in your code, after reading more
of the file, you could return to this position by coding
{cmd:fseek(fh, pos, -1)}
{p 4 4 2}
You could return to the beginning of the file by coding
{cmd:fseek(fh, 0, -1)}
{p 4 4 2}
and you could move to the end of the file by coding
{cmd:fseek(fh, 0, 1)}
{p 4 4 2}
{cmd:ftell(}{it:fh}{cmd:)} is equivalent to
{cmd:_fseek(}{it:fh}{cmd:, 0, 0)}.
{p 4 4 2}
Repositioning functions cannot be used when the file has been opened
"{cmd:a}".
{title:Truncating a file}
{p 4 4 2}
Truncation refers to making a longer file shorter.
If a file was opened "{cmd:w}" or "{cmd:rw}", you may truncate it at its
current position by using
{p 9 8 2}
{cmd:ftruncate(}{it:fh}{cmd:)}
{p 4 4 2}
or
{p 8 8 2}
{cmd:_ftruncate(}{it:fh}{cmd:)}
{p 4 4 2}
{cmd:ftruncate()} returns nothing; {cmd:_ftruncate()} returns 0 on success
and otherwise returns a negative error code.
{p 4 4 2}
The following code shortens a file to its first 100 bytes:
{cmd}fh = fopen(filename, "rw")
fseek(fh, 100, -1)
ftruncate(fh)
fclose(fh){txt}
{title:Error codes}
{p 4 4 2}
If you use the underscore I/O functions, if there is an error, they
will return a negative code. Those codes are
negative
code meaning
{hline 61}
0 all is well
-1 end of file
-601 file not found
-602 file already exists
-603 file could not be opened
-608 file is read-only
-610 file format error
-630 web files not supported in this version of Stata
-631 host not found
-632 web file not allowed in this context
-633 web file not allowed in this context
-660 proxy host not found
-662 proxy server refused request to send
-663 remote connection to proxy failed
-665 could not set socket nonblocking
-669 invalid URL
-670 invalid network port number
-671 unknown network protocol
-672 server refused to send file
-673 authorization required by server
-674 unexpected response from server
-678 could not open local network socket
-679 unexpected web error
-691 I/O error
-699 insufficient disk space
-3601 invalid file handle
-3602 invalid filename
-3611 too many open files
-3621 attempt to write read-only file
-3622 attempt to read write-only file
-3623 attempt to seek append-only file
-3698 file seek error
{hline 61}
{p 8 8 10}
Other codes in the -600 to -699 range are possible. The codes
in this range correspond to the negative of the corresponding Stata return
code, see {bf:[P] error}.
{p 4 4 2}
Underscore functions that return a real scalar will return one of these
codes if there is an error.
{p 4 4 2}
If an underscore function does not return a real scalar, then you obtain the
outcome status using {cmd:fstatus()}. For instance, the read-string functions
return a string scalar or {cmd:J(0,0,"")} on end-of-file. The underscore
variants do the same, and they also return {cmd:J(0,0,"")} on error, meaning
error looks like end-of-file. You can determine the error code using the
function
{cmd:fstatus(}{it:fh}{cmd:)}
{p 4 4 2}
{cmd:fstatus()} returns 0 (no previous error) or one of the negative codes
above.
{p 4 4 2}
{cmd:fstatus()} may be used after any underscore I/O command to obtain
the current error status.
{p 4 4 2}
{cmd:fstatus()} may also be used after the nonunderscore I/O commands;
in that case, {cmd:fstatus()} will return -1 or 0 because all other problems
would have stopped execution.
{title:Conformability}
{p 4 4 2}
{cmd:fopen(}{it:fn}{cmd:,} {it:mode}{cmd:,} {it:public}{cmd:)},
{cmd:_fopen(}{it:fn}{cmd:,} {it:mode}{cmd:,} {it:public}{cmd:)}:
{p_end}
{it:fn}: 1 {it:x} 1
{it:mode}: 1 {it:x} 1
{it:public}: 1 {it:x} 1
{it:result}: 1 {it:x} 1
{cmd:fclose(}{it:fh}{cmd:)}:
{it:fh}: 1 {it:x} 1
{it:result}: {it:void}
{cmd:_fclose(}{it:fh}{cmd:)}:
{it:fh}: 1 {it:x} 1
{it:result}: 1 {it:x} 1
{p 4 4 2}
{cmd:fget(}{it:fh}{cmd:)},
{cmd:_fget(}{it:fh}{cmd:)},
{cmd:fgetnl(}{it:fh}{cmd:)},
{cmd:_fgetnl(}{it:fh}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:result}: 1 {it:x} 1 or 0 {it:x} 0 if end-of-file
{p 4 4 2}
{cmd:fread(}{it:fh}{cmd:,} {it:len}{cmd:)},
{cmd:_fread(}{it:fh}{cmd:,} {it:len}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:len}: 1 {it:x} 1
{it:result}: 1 {it:x} 1 or 0 {it:x} 0 if end-of-file
{p 4 4 2}
{cmd:fput(}{it:fh}{cmd:,} {it:s}{cmd:)},
{cmd:fwrite(}{it:fh}{cmd:,} {it:s}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:s}: 1 {it:x} 1
{it:result}: {it:void}
{p 4 4 2}
{cmd:_fput(}{it:fh}{cmd:,} {it:s}{cmd:)},
{cmd:_fwrite(}{it:fh}{cmd:,} {it:s}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:s}: 1 {it:x} 1
{it:result}: 1 {it:x} 1
{p 4 4 2}
{cmd:fgetmatrix(}{it:fh}{cmd:)},
{cmd:_fgetmatrix(}{it:fh}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:result}: {it:r x c} or 0 {it:x} 0 if end-of-file
{p 4 4 2}
{cmd:fputmatrix(}{it:fh}{cmd:,} {it:X}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:X}: {it:r x c}
{it:result}: {it:void}
{p 4 4 2}
{cmd:_fputmatrix(}{it:fh}{cmd:,} {it:X}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:X}: {it:r x c}
{it:result}: 1 {it:x} 1
{p 4 4 2}
{cmd:fstatus(}{it:fh}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:result}: 1 {it:x} 1
{p 4 4 2}
{cmd:ftell(}{it:fh}{cmd:)},
{cmd:_ftell(}{it:fh}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:result}: 1 {it:x} 1
{p 4 4 2}
{cmd:fseek(}{it:fh}{cmd:,} {it:offset}{cmd:,} {it:whence}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:offset}: 1 {it:x} 1
{it:whence}: 1 {it:x} 1
{it:result}: {it:void}
{p 4 4 2}
{cmd:_fseek(}{it:fh}{cmd:,} {it:offset}{cmd:,} {it:whence}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:offset}: 1 {it:x} 1
{it:whence}: 1 {it:x} 1
{it:result}: 1 {it:x} 1
{p 4 4 2}
{cmd:ftruncate(}{it:fh}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:result}: {it:void}
{p 4 4 2}
{cmd:_ftruncate(}{it:fh}{cmd:)}:
{p_end}
{it:fh}: 1 {it:x} 1
{it:result}: 1 {it:x} 1
{title:Diagnostics}
{p 4 4 2}
{cmd:fopen(}{it:fn}{cmd:,} {it:mode}{cmd:)} aborts with error if
{it:mode} is invalid or if {it:fn} cannot be opened or if an attempt
is made to open too many files simultaneously.
{p 4 4 2}
{cmd:_fopen(}{it:fn}{cmd:,} {it:mode}{cmd:)} aborts with error if {it:mode} is
invalid or if an attempt is made to open too many files simultaneously.
{cmd:_fopen()} returns the appropriate negative error code if {it:fn} cannot
be opened.
{p 4 4 2}
All remaining I/O functions -- even functions with leading underscore -- abort
with error if {it:fh} is not a handle to a currently open file.
{p 4 4 2}
In addition, the functions that do not begin with an underscore abort with
error when a file was opened read-only and a request requiring write access is
made, when a file is opened write-only and a request requiring read access is
made, etc. See {bf:Error codes} above; all problems except code -1 (end of
file) cause the nonunderscore functions to abort with error.
{p 4 4 2}
Finally, the following functions will also abort with error for the
following specific reasons:
{p 4 4 2}
{cmd:fseek(}{it:fh}{cmd:,} {it:offset}{cmd:,} {it:whence}{cmd:)}
and
{cmd:_fseek(}{it:fh}{cmd:,} {it:offset}{cmd:,} {it:whence}{cmd:)}
abort with error if {it:offset}
is outside the range +/-2,147,483,647 on 32-bit computers,
if {it:offset} is outside the range
+/-9,007,199,254,740,991 on 64-bit computers;
or, on all computers, if
{it:whence} is not -1, 0, or 1.
{title:Source code}
{p 4 4 2}
{view ftell.mata, adopath asis:ftell.mata};
other functions are built-in.
{title:Also see}
{p 4 13 2}
Manual: {hi:[M-5] fopen()}
{p 4 13 2}
Online: help for
{bf:{help mf_cat:[M-5] cat}},
{cmd:sprintf()} in {bf:{help mf_printf:[M-5] printf()}};
{bf:{help m4_io:[M-4] io}}
{p_end}
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -