stream—a stream.
position-spec—a file position designator.
position—a file position or nil
.
success-p—a generalized boolean.
Returns or changes the current position within a stream.
When position-spec is not supplied,
file-position
returns the current file position in the stream,
or nil
if this cannot be determined.
When position-spec is supplied,
the file position in stream is set to that file position (if possible).
file-position
returns true
if the repositioning is performed successfully,
or false if it is not.
An integer returned by file-position
of one argument
should be acceptable as position-spec for use with the same file.
For a character file,
performing a single read-char
or write-char
operation
may cause the file position to be increased by more than 1 because of
character-set translations (such as translating between the Common Lisp
#\Newline
character and an external ASCII
carriage-return/line-feed sequence) and other aspects of the
implementation. For a binary file, every read-byte
or write-byte
operation increases the file position by 1.
(defun tester () (let ((noticed '()) file-written) (flet ((notice (x) (push x noticed) x)) (with-open-file (s "test.bin" :element-type '(unsigned-byte 8) :direction :output :if-exists :error) (notice (file-position s)) ;1 (write-byte 5 s) (write-byte 6 s) (let ((p (file-position s))) (notice p) ;2 (notice (when p (file-position s (1- p))))) ;3 (write-byte 7 s) (notice (file-position s)) ;4 (setq file-written (truename s))) (with-open-file (s file-written :element-type '(unsigned-byte 8) :direction :input) (notice (file-position s)) ;5 (let ((length (file-length s))) (notice length) ;6 (when length (dotimes (i length) (notice (read-byte s)))))) ;7,... (nreverse noticed)))) → tester (tester) → (0 2 T 2 0 2 5 7) or→ (0 2 NIL 3 0 3 5 6 7) or→ (NIL NIL NIL NIL NIL NIL)
When the position-spec argument is supplied, the file position in the stream might be moved.
The value returned by file-position
increases monotonically
as input or output operations are performed.
If position-spec is supplied, but is too large or otherwise inappropriate, an error is signaled.
file-length, file-string-length, open
Implementations that have character files represented
as a sequence of records of bounded size might choose to encode the
file position as, for example,
«record-number»*«max-record-size»+«character-within-record».
This is a valid encoding because it increases monotonically as
each character is read or written, though not necessarily by 1 at
each step. An integer might then be considered “inappropriate”
as position-spec to file-position
if, when decoded into
record number and character number, it turned out that the
supplied record was too short for the specified character number.