NAME

       libwget-io

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_t load_func, wget_update_load_t
           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

       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

       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 NULL termination character (\0).

   int wget_update_file (const char * fname, wget_update_load_t load_func, wget_update_load_t
       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 -1 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.