## camel-file-utils

camel-file-utils

## Synopsis

    #define             O_BINARY
    gint                camel_file_util_encode_fixed_int32  (FILE *out,
                                                             gint32 value);
    gint                camel_file_util_decode_fixed_int32  (FILE *in,
                                                             gint32 *dest);
    gint                camel_file_util_encode_uint32       (FILE *out,
                                                             guint32 value);
    gint                camel_file_util_decode_uint32       (FILE *in,
                                                             guint32 *dest);
    gint                camel_file_util_encode_time_t       (FILE *out,
                                                             time_t value);
    gint                camel_file_util_decode_time_t       (FILE *in,
                                                             time_t *dest);
    gint                camel_file_util_encode_off_t        (FILE *out,
                                                             off_t value);
    gint                camel_file_util_decode_off_t        (FILE *in,
                                                             off_t *dest);
    gint                camel_file_util_encode_gsize        (FILE *out,
                                                             gsize value);
    gint                camel_file_util_decode_gsize        (FILE *in,
                                                             gsize *dest);
    gint                camel_file_util_encode_string       (FILE *out,
                                                             const gchar *str);
    gint                camel_file_util_decode_string       (FILE *in,
                                                             gchar **str);
    gint                camel_file_util_encode_fixed_string (FILE *out,
                                                             const gchar *str,
                                                             gsize len);
    gint                camel_file_util_decode_fixed_string (FILE *in,
                                                             gchar **str,
                                                             gsize len);
    gchar *             camel_file_util_safe_filename       (const gchar *name);
    gssize              camel_read                          (gint fd,
                                                             gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              camel_write                         (gint fd,
                                                             const gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              camel_read_socket                   (gint fd,
                                                             gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              camel_write_socket                  (gint fd,
                                                             const gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gchar *		           camel_file_util_savename            (const gchar *filename);

## Description

## Details

### O_BINARY

    #define O_BINARY 0

### camel_file_util_encode_fixed_int32 ()

    gint                camel_file_util_encode_fixed_int32  (FILE *out,
                                                             gint32 value);

Encode a gint32, performing no compression, but converting to network order.

`out` : | file to output to
`value` : | value to output
Returns : | `0` on success, `-1` on error.

### camel_file_util_decode_fixed_int32 ()

    gint                camel_file_util_decode_fixed_int32  (FILE *in,
                                                             gint32 *dest);

Retrieve a gint32.

`in` : | file to read from
`dest` : | pointer to a variable to store the value in
Returns : | `0` on success, `-1` on error.

### camel_file_util_encode_uint32 ()

    gint                camel_file_util_encode_uint32       (FILE *out,
                                                             guint32 value);

Utility function to save an uint32 to a file.

`out` : | file to output to
`value` : | value to output
Returns : | `0` on success, `-1` on error.

### camel_file_util_decode_uint32 ()

    gint                camel_file_util_decode_uint32       (FILE *in,
                                                             guint32 *dest);

Retrieve an encoded uint32 from a file.

`in` : | file to read from
`dest` : | pointer to a variable to store the value in
Returns : | `0` on success, `-1` on error. @*dest will contain the decoded value.

### camel_file_util_encode_time_t ()

    gint                camel_file_util_encode_time_t       (FILE *out,
                                                             time_t value);

Encode a time_t value to the file.

`out` : | file to output to
`value` : | value to output
Returns : | `0` on success, `-1` on error.

### camel_file_util_decode_time_t ()

    gint                camel_file_util_decode_time_t       (FILE *in,
                                                             time_t *dest);

Decode a time_t value.

`in` : | file to read from
`dest` : | pointer to a variable to store the value in
Returns : | `0` on success, `-1` on error.

### camel_file_util_encode_off_t ()

    gint                camel_file_util_encode_off_t        (FILE *out,
                                                             off_t value);

Encode an off_t type.

`out` : | file to output to
`value` : | value to output
Returns : | `0` on success, `-1` on error.

### camel_file_util_decode_off_t ()

    gint                camel_file_util_decode_off_t        (FILE *in,
                                                             off_t *dest);

Decode an off_t type.

`in` : | file to read from
`dest` : | pointer to a variable to put the value in
Returns : | `0` on success, `-1` on failure.

### camel_file_util_encode_gsize ()

    gint                camel_file_util_encode_gsize        (FILE *out,
                                                             gsize value);

Encode an gsize type.

`out` : | file to output to
`value` : | value to output
Returns : | `0` on success, `-1` on error.

### camel_file_util_decode_gsize ()

    gint                camel_file_util_decode_gsize        (FILE *in,
                                                             gsize *dest);

Decode an gsize type.

`in` : | file to read from
`dest` : | pointer to a variable to put the value in
Returns : | `0` on success, `-1` on failure.

### camel_file_util_encode_string ()

    gint                camel_file_util_encode_string       (FILE *out,
                                                             const gchar *str);

Encode a normal string and save it in the output file.

`out` : | file to output to
`str` : | value to output
Returns : | `0` on success, `-1` on error.

### camel_file_util_decode_string ()

    gint                camel_file_util_decode_string       (FILE *in,
                                                             gchar **str);

Decode a normal string from the input file.

`in` : | file to read from
`str` : | pointer to a variable to store the value in
Returns : | `0` on success, `-1` on error.

### camel_file_util_encode_fixed_string ()

    gint                camel_file_util_encode_fixed_string (FILE *out,
                                                             const gchar *str,
                                                             gsize len);

Encode a normal string and save it in the output file. Unlike `camel_file_util_encode_string`, it pads the `str` with "NULL" bytes, if `len` is > strlen(str)

`out` : | file to output to
`str` : | value to output
`len` : | total-len of str to store
Returns : | `0` on success, `-1` on error.

### camel_file_util_decode_fixed_string ()

    gint                camel_file_util_decode_fixed_string (FILE *in,
                                                             gchar **str,
                                                             gsize len);

Decode a normal string from the input file.

`in` : | file to read from
`str` : | pointer to a variable to store the value in
`len` : | total-len to decode.
Returns : | `0` on success, `-1` on error.

### camel_file_util_safe_filename ()

    gchar *             camel_file_util_safe_filename       (const gchar *name);

'Flattens' `name` into a safe filename string by hex encoding any chars that may cause problems on the filesystem.

`name` : | string to 'flattened' into a safe filename
Returns : | a safe filename string.

### camel_read ()

    gssize              camel_read                          (gint fd,
                                                             gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);

Cancellable libc `read()` replacement.

Code that intends to be portable to Win32 should call this function only on file descriptors returned from `open()`, not on sockets.

`fd` : | file descriptor
`buf` : | buffer to fill
`n` : | number of bytes to read into `buf`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | number of bytes read or -1 on fail. On failure, errno will be set appropriately.

### camel_write ()

    gssize              camel_write                         (gint fd,
                                                             const gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);

Cancellable libc `write()` replacement.

Code that intends to be portable to Win32 should call this function only on file descriptors returned from `open()`, not on sockets.

`fd` : | file descriptor
`buf` : | buffer to write
`n` : | number of bytes of `buf` to write
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | number of bytes written or -1 on fail. On failure, errno will be set appropriately.

### camel_read_socket ()

    gssize              camel_read_socket                   (gint fd,
                                                             gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);

Cancellable `read()` replacement for sockets. Code that intends to be portable to Win32 should call this function only on sockets returned from `socket()`, or `accept()`.

`fd` : | a socket
`buf` : | buffer to fill
`n` : | number of bytes to read into `buf`
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | number of bytes read or -1 on fail. On failure, errno will be set appropriately. If the socket is nonblocking `camel_read_socket()` will retry the read until it gets something.

### camel_write_socket ()

    gssize              camel_write_socket                  (gint fd,
                                                             const gchar *buf,
                                                             gsize n,
                                                             GCancellable *cancellable,
                                                             GError **error);

Cancellable `write()` replacement for sockets. Code that intends to be portable to Win32 should call this function only on sockets returned from `socket()` or `accept()`.

`fd` : | file descriptor
`buf` : | buffer to write
`n` : | number of bytes of `buf` to write
`error` : | return location for a GError, or `NULL`
Returns : | number of bytes written or -1 on fail. On failure, errno will be set appropriately.

### camel_file_util_savename ()

    gchar *		           camel_file_util_savename            (const gchar *filename);

Builds a pathname where the basename is of the form ".#" + the basename of `filename`, for instance used in a two-stage commit file write.

`filename` : | a pathname
Returns : | The new pathname. It must be free'd with `g_free()`.