camel-file-utils
3
CAMEL Library

# camel-file-utils

## Synopsis

    #define             O_BINARY
    int                 camel_file_util_encode_fixed_int32  (FILE *out,
                                                             gint32 );
    int                 camel_file_util_decode_fixed_int32  (FILE *in,
                                                             gint32 *);
    int                 camel_file_util_encode_uint32       (FILE *out,
                                                             guint32 );
    int                 camel_file_util_decode_uint32       (FILE *in,
                                                             guint32 *);
    int                 camel_file_util_encode_time_t       (FILE *out,
                                                             time_t );
    int                 camel_file_util_decode_time_t       (FILE *in,
                                                             time_t *);
    int                 camel_file_util_encode_off_t        (FILE *out,
                                                             off_t );
    int                 camel_file_util_decode_off_t        (FILE *in,
                                                             off_t *);
    int                 camel_file_util_encode_size_t       (FILE *out,
                                                             size_t );
    int                 camel_file_util_decode_size_t       (FILE *in,
                                                             size_t *);
    int                 camel_file_util_encode_string       (FILE *out,
                                                             const char *);
    int                 camel_file_util_decode_string       (FILE *in,
                                                             char **);
    int                 camel_file_util_encode_fixed_string (FILE *out,
                                                             const char *str,
                                                             size_t len);
    int                 camel_file_util_decode_fixed_string (FILE *in,
                                                             char **str,
                                                             size_t len);
    char*               camel_file_util_safe_filename       (const char *name);
    ssize_t             camel_read                          (int fd,
                                                             char *buf,
                                                             size_t n);
    ssize_t             camel_write                         (int fd,
                                                             const char *buf,
                                                             size_t n);
    ssize_t             camel_read_socket                   (int fd,
                                                             char *buf,
                                                             size_t n);
    ssize_t             camel_write_socket                  (int fd,
                                                             const char *buf,
                                                             size_t n);
    char*               camel_file_util_savename            (const char *filename);

## Description

## Details

### O_BINARY

    #define O_BINARY 0

### camel_file_util_encode_fixed_int32 ()

    int                 camel_file_util_encode_fixed_int32  (FILE *out,
                                                             gint32 );

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

`out` :

  file to output to

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_decode_fixed_int32 ()

    int                 camel_file_util_decode_fixed_int32  (FILE *in,
                                                             gint32 *);

Retrieve a gint32.

`in` :

  file to read from

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_encode_uint32 ()

    int                 camel_file_util_encode_uint32       (FILE *out,
                                                             guint32 );

Utility function to save an uint32 to a file.

`out` :

  file to output to

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_decode_uint32 ()

    int                 camel_file_util_decode_uint32       (FILE *in,
                                                             guint32 *);

Retrieve an encoded uint32 from a file.

`in` :

  file to read from

`Param2` :

Returns :

  0 on success, -1 on error. @*dest will contain the decoded value.

### camel_file_util_encode_time_t ()

    int                 camel_file_util_encode_time_t       (FILE *out,
                                                             time_t );

Encode a time_t value to the file.

`out` :

  file to output to

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_decode_time_t ()

    int                 camel_file_util_decode_time_t       (FILE *in,
                                                             time_t *);

Decode a time_t value.

`in` :

  file to read from

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_encode_off_t ()

    int                 camel_file_util_encode_off_t        (FILE *out,
                                                             off_t );

Encode an off_t type.

`out` :

  file to output to

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_decode_off_t ()

    int                 camel_file_util_decode_off_t        (FILE *in,
                                                             off_t *);

Decode an off_t type.

`in` :

  file to read from

`Param2` :

Returns :

  0 on success, -1 on failure.

### camel_file_util_encode_size_t ()

    int                 camel_file_util_encode_size_t       (FILE *out,
                                                             size_t );

Encode an size_t type.

`out` :

  file to output to

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_decode_size_t ()

    int                 camel_file_util_decode_size_t       (FILE *in,
                                                             size_t *);

Decode an size_t type.

`in` :

  file to read from

`Param2` :

Returns :

  0 on success, -1 on failure.

### camel_file_util_encode_string ()

    int                 camel_file_util_encode_string       (FILE *out,
                                                             const char *);

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

`out` :

  file to output to

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_decode_string ()

    int                 camel_file_util_decode_string       (FILE *in,
                                                             char **);

Decode a normal string from the input file.

`in` :

  file to read from

`Param2` :

Returns :

  0 on success, -1 on error.

### camel_file_util_encode_fixed_string ()

    int                 camel_file_util_encode_fixed_string (FILE *out,
                                                             const char *str,
                                                             size_t 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 ()

    int                 camel_file_util_decode_fixed_string (FILE *in,
                                                             char **str,
                                                             size_t 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 ()

    char*               camel_file_util_safe_filename       (const char *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 ()

    ssize_t             camel_read                          (int fd,
                                                             char *buf,
                                                             size_t n);

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`

Returns :

  number of bytes read or -1 on fail. On failure, errno will be set appropriately.

### camel_write ()

    ssize_t             camel_write                         (int fd,
                                                             const char *buf,
                                                             size_t n);

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

Returns :

  number of bytes written or -1 on fail. On failure, errno will be set appropriately.

### camel_read_socket ()

    ssize_t             camel_read_socket                   (int fd,
                                                             char *buf,
                                                             size_t n);

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`

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 ()

    ssize_t             camel_write_socket                  (int fd,
                                                             const char *buf,
                                                             size_t n);

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

Returns :

  number of bytes written or -1 on fail. On failure, errno will be set appropriately.

### camel_file_util_savename ()

    char*               camel_file_util_savename            (const char *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()`.