Functions

#include <lfp/lfp.h>

int lfp_close(lfp_protocol*)

Close the file and release resources.

Close a file and release resources recursively - if the pointer argument is NULL, nothing happens.

This is similar to fclose(), and will release the handle. It is undefined behaviour to call close more than once on the same file.

Using an lfp* after it has been lfp_close()d is undefined behaviour.

int lfp_readinto(lfp_protocol*, void *dst, int64_t len, int64_t *nread)

Read len bytes into dst.

Read up to len bytes into dst. The exact number of bytes read are written to nread, which will always be *nread <= len. nread is usually only smaller than len at EOF.

nread can be NULL. If it is, it is not possible to determine how many bytes were written to dst when less-than-len bytes were asked for.

This function returns LFP_OKINCOMPLETE when not enough bytes were available, but the read was otherwise successful. This is common when reading from pipes.

Return values:

  • LFP_OK – Success

  • LFP_OKINCOMPLETE – Successful, but incomplete read

  • LFP_EOF – Successful, but end of file was reach during the read

int lfp_seek(lfp_protocol*, int64_t n)

Set the file position to (absolute) byte offset n.

Protocols are not required to implement seek, e.g. file streams (pipes) are usually not seekable.

Parameters:

n – byte offset to seek to, must not be negative

Return values:

  • LFP_OK – Success

  • LFP_INVALID_ARGS – N is negative

  • LFP_NOTIMPLEMENTED – Layer does not support seek

int lfp_tell(lfp_protocol*, int64_t *n)

Get current position.

Obtain the current logical value of the file position. The value is relative to the used protocol, 0-based, in bytes.

int lfp_ptell(lfp_protocol*, int64_t *n)

Get current physical position.

Obtain the current physical value of the file position. The value is absolute with regards to the underlying handle of the leaf protocol, 0-based, in bytes. As a consequence, same value will be returned for all the protocols stacked together.

int lfp_peel(lfp_protocol *outer, lfp_protocol **inner)

Peels off the current protocol to expose the underlying one.

Conceptually this is similar to calling release() on a std::unique_ptr. lfp_peel() is not implemented for leaf protocols such as the cfile protocol.

Parameters:

  • outer – Outer protocol that will be peeled off

  • inner – Reference to the underlying protocol

Return values:

  • LFP_OK – Success

  • LFP_LEAF_PROTOCOL – Leaf protocols does not support peel

  • LFP_IOERROR – There is no underlying protocol to peel into. Typically this would be the case if peel is called multiple times on the same protocol.

int lfp_peek(lfp_protocol *outer, lfp_protocol **inner)

Expose a const view of the underlying protocol.

Conceptually, this function is similar to calling get() on a std::unique_ptr. Performing a non-const operation such as lfp_seek() and lfp_readinto() on the exposed protocol will leave the outer protocol in an undefined state.

Like lfp_peel(), peek is not implemented for leaf protocols such as the cfile protocol.

Parameters:

  • outer – Outer protocol

  • inner – Reference to the underlying protocol

Return values:

  • LFP_OK – Success

  • LFP_LEAF_PROTOCOL – Leaf protocols does not support peek

  • LFP_IOERROR – There is no underlying protocol to peek into. Typically this would be the case if the protocol is already been peel’ed.

int lfp_eof(lfp_protocol*)

Checks if the end of file is reached.

This does not return a lfp_status code.

Return values:

  • non-zero – End-of-file reached

  • 0 – End-of-file not reached

const char *lfp_errormsg(lfp_protocol*)

Get last set error message.

Obtain a human-readable error message, or NULL if no error is set. This does not return a status code.

This function should be called immediately after the error occured, to accurately describe the nature of the error. The string is human readable, not guaranteed to be stable, and is not suited for parsing.