file-position stream => position
file-position stream position-spec => success-p
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.
section file-length [Function] , section file-string-length [Function] , section open [Function]
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.
Go to the first, previous, next, last section, table of contents.