hSeek

Computation hSeek hdl mode i sets the position of handle hdl depending on mode. The offset i is given in terms of 8-bit bytes. If hdl is block- or line-buffered, then seeking to a position which is not in the current buffer will first cause any items in the output buffer to be written to the device, and then cause the input buffer to be discarded. Some handles may not be seekable (see hIsSeekable), or only support a subset of the possible positioning operations (for instance, it may only be possible to seek to the end of a tape, or to a positive offset from the beginning or current position). It is not possible to set a negative I/O position, or for a physical file, an I/O position beyond the current end-of-file. This operation may fail with:

• isIllegalOperationError if the Handle is not seekable, or does not support the requested seek mode.
• isPermissionError if a system resource limit would be exceeded.

Lifted version of hSeek

The file seek functions work much like hseek with the exception that the non-audio data is ignored and the seek only moves within the audio data section of the file. In addition, seeks are defined in number of (multichannel) frames. Therefore, a seek in a stereo file from the current position forward with an offset of 1 would skip forward by one sample of both channels. like lseek(), the whence parameter can be any one of the following three values:

• AbsoluteSeek - The offset is set to the start of the audio data plus offset (multichannel) frames.
• RelativeSeek - The offset is set to its current location plus offset (multichannel) frames.
• SeekFromEnd - The offset is set to the end of the data plus offset (multichannel) frames.

Internally, libsndfile keeps track of the read and write locations using separate read and write pointers. If a file has been opened with a mode of ReadWriteMode, calling either hSeekRead or hSeekWrite allows the read and write pointers to be modified separately. hSeek modifies both the read and the write pointer. Note that the frames offset can be negative and in fact should be when SeekFromEnd is used for the whence parameter. hSeek will return the offset in (multichannel) frames from the start of the audio data, or signal an error when an attempt is made to seek beyond the start or end of the file.

Seek to the end of a tar file, to the position where new entries can be appended, and return that TarEntryOffset. If you have a valid TarIndex for this tar file then you should supply it because it allows seeking directly to the correct location. If you do not have an index, then this becomes an expensive linear operation because we have to read each tar entry header from the beginning to find the location immediately after the last entry (this is because tar files have a variable length trailer and we cannot reliably find that by starting at the end). In this mode, it will fail with an exception if the file is not in fact in the tar format.

Set the Handle position to the entry content position corresponding to the given TarEntryOffset. This position is where the entry content can be read using ordinary I/O operations (though you have to know in advance how big the entry content is). This is only valid if you already know the entry has a body (i.e. is a normal file).

Set the Handle position to the position corresponding to the given TarEntryOffset. This position is where the entry metadata can be read. If you already know the entry has a body (and perhaps know it's length), you may wish to seek to the body content directly using hSeekEntryContentOffset.

Like hSeek, but only the read pointer is modified.

Like hSeek, but only the write pointer is modified.