libwget-io(3) Introduction to Library Functions libwget-io(3)

NAME

libwget-io - I/O helper routines

SYNOPSIS

Functions

ssize_t wget_fdgetline (char **buf, size_t *bufsize, int fd)
ssize_t wget_getline (char **buf, size_t *bufsize, FILE *fp)
int wget_ready_2_transfer (int fd, int timeout, int mode)
int wget_ready_2_read (int fd, int timeout)
int wget_ready_2_write (int fd, int timeout)
char * wget_read_file (const char *fname, size_t *size)
int wget_update_file (const char *fname, wget_update_load_fn
*load_func, wget_update_save_fn *save_func, void *context)
int wget_truncate (const char *path, off_t length)

Detailed Description
Some general I/O helper functions that could be handy for developers.

Function Documentation
ssize_t wget_fdgetline (char ** buf, size_t * bufsize, int fd)
Parameters
buf Pointer to a pointer that will be set up by the function to
point to the read line
bufsize Pointer to a variable where the length of the read line
will be put
fd File descriptor for an open file

Returns
The length of the last line read or a WGET_E_* error code (< 0)

Behaves identically as wget_getline(), but uses a file descriptor
instead of a stream.

ssize_t wget_getline (char ** buf, size_t * bufsize, FILE * fp)
Parameters
buf Pointer to a pointer that will be set up by the function to
point to the read line
bufsize Pointer to a variable where the length of the read line
will be put
fp Pointer to an open file's stream handle (FILE *)

Returns
The length of the last line read or a WGET_E_* error code (< 0)

This function will read a line from the open file handle fp. This
function reads input characters until either a newline character
(\\n) is found or EOF is reached. A block of memory large enough to
hold the read line will be implicitly allocated by the function, and
its address placed at the pointer pointed to by buf. The length of
the aforementioned memory block will be stored in the variable
pointed at by bufsize.

The caller is not expected to allocate memory as that will be
automatically done by wget_getline(), but it is responsibility of the
caller free the memory allocated by a previous invocation of this
function. The caller is also responsible for opening and closing the
file to read from.

Subsequent calls to wget_getline() that use the same block of memory
allocated by previous calls (that is, the caller did not free the
buffer returned by a previous call to wget_getline()) will try to
reuse as much as possible from the available memory. The block of
memory allocated by wget_getline() may be larger than the length of
the line read, and might even contain additional lines in it. When
wget_getline() returns, the contents of the buffer (pointed at by
buf) are guaranteed to start with the first character of the last
line read, and such line is also guaranteed to end with a NULL
termination character (\0). The length of the last read line will be
returned by wget_getline(), whereas the actual length of the buffer
will be placed in the variable pointed at by bufsize. The newline
character (\\n) will not be included in the last read line.

int wget_ready_2_transfer (int fd, int timeout, int mode)
Parameters
fd File descriptor to wait for
timeout Max. duration in milliseconds to wait
mode Either WGET_IO_WRITABLE or WGET_IO_READABLE

Returns
-1 on error
0 on timeout - the file descriptor is not ready for reading or
writing
>0 The file descriptor is ready for reading or writing. Check
for the bitwise or of WGET_IO_WRITABLE and WGET_IO_READABLE.

Wait for a file descriptor to become ready to read or write.

A timeout value of 0 means the function returns immediately.
A timeout value of -1 means infinite timeout.

int wget_ready_2_read (int fd, int timeout)
Parameters
fd File descriptor to wait for
timeout Max. duration in milliseconds to wait

Returns
-1 on error
0 on timeout - the file descriptor is not ready for reading
1 on success - the file descriptor is ready for reading

Wait for a file descriptor to become ready to read.

A timeout value of 0 means the function returns immediately.
A timeout value of -1 means infinite timeout.

int wget_ready_2_write (int fd, int timeout)
Parameters
fd File descriptor to wait for
timeout Max. duration in milliseconds to wait

Returns
-1 on error
0 on timeout - the file descriptor is not ready for writing
1 on success - the file descriptor is ready for writing

Wait for a file descriptor to become ready to write.

A timeout value of 0 means the function returns immediately.
A timeout value of -1 means infinite timeout.

char * wget_read_file (const char * fname, size_t * size)
Parameters
fname The name of the file to read from, or a dash (-) to read
from STDIN
size Pointer to a variable where the length of the contents read
will be stored

Returns
Pointer to the read data, as a NULL-terminated C string

Reads the content of a file, or from STDIN. When reading from STDIN,
the behavior is the same as for regular files: input is read until an
EOF character is found.

Memory will be accordingly allocated by wget_read_file() and a
pointer to it returned when the read finishes, but the caller is
responsible for freeing that memory. The length of the allocated
block of memory, which is guaranteed to be the same as the length of
the data read, will be placed in the variable pointed at by size.

The read data is guaranteed to be appended a NUL termination
character (\0).

int wget_update_file (const char * fname, wget_update_load_fn *
load_func, wget_update_save_fn * save_func, void * context)
Parameters
fname File name to update
load_func Pointer to the loader function
save_func Pointer to the saver function
context Context data

Returns
0 on success, or WGET_E_* on error

This function updates the file named fname atomically. It lets two
caller-provided functions do the actual updating. A lock file is
created first under /tmp to ensure exclusive access to the file.
Other processes attempting to call wget_update_file() with the same
fname parameter will block until the current calling process has
finished (that is, until wget_update_file() has returned).
Then, the file is opened with read access first, and the load_func
function is called. When it returns, the file is closed and opened
again with write access, and the save_func function is called. Both
callback functions are passed the context data context, and a stream
descriptor for the file. If either function load_func or save_func
returns a non-zero value, wget_update_file() closes the file and
returns -1, performing no further actions.

int wget_truncate (const char * path, off_t length)
Parameters
path File path
length New file size

Returns
0 on success, or -1 on error

Set path to a size of exactly length bytes.

If the file was previously larger, the extra data is lost. If the
file was previously shorter, extra zero bytes are added.

On POSIX, this is a wrapper around ftruncate() (see 'man ftruncate'
for details).

Author
Generated automatically by Doxygen for wget2 from the source code.

wget2 Version 2.2.0 libwget-io(3)