lib/silcutil/silcfileutil.h

   1 /*
   2
   3   silcfileutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2007 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC File Util Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  *    The SILC File Util Interface is a small set of functions that provides a
  25  *    portable access method to the filesystem.
  26  *
  27  ***/
  28
  29 #ifndef SILCFILEUTIL_H
  30 #define SILCFILEUTIL_H
  31
  32 /* Prototypes */
  33
  34 /****f* silcutil/SilcFileUtilAPI/silc_file_open
  35  *
  36  * SYNOPSIS
  37  *
  38  *    int silc_file_open(const char *filename, int flags);
  39  *
  40  * DESCRIPTION
  41  *
  42  *    Opens a file indicated by the filename `filename' with flags indicated
  43  *    by `flags'.  The opening permission defaults to 0600.  The `flags'
  44  *    are defined in open(2).  Returns the opened file descriptor or -1 on
  45  *    error.
  46  *
  47  ***/
  48 int silc_file_open(const char *filename, int flags);
  49
  50 /****f* silcutil/SilcFileUtilAPI/silc_file_open_mode
  51  *
  52  * SYNOPSIS
  53  *
  54  *    int silc_file_open_mode(const char *filename, int flags, int mode);
  55  *
  56  * DESCRIPTION
  57  *
  58  *    Opens a file indicated by the filename `filename' with flags indicated
  59  *    by `flags'.  The argument `mode' specifies the permissions to use in
  60  *    case a new file is created.  The `flags' are defined in open(2).
  61  *    Returns the opened file descriptor or -1 on error and sets silc_errno.
  62  *
  63  ***/
  64 int silc_file_open_mode(const char *filename, int flags, int mode);
  65
  66 /****f* silcutil/SilcFileUtilAPI/silc_file_read
  67  *
  68  * SYNOPSIS
  69  *
  70  *    int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
  71  *
  72  * DESCRIPTION
  73  *
  74  *    Reads data from file descriptor `fd' to `buf'.  Returns the amount of
  75  *    bytes read, 0 on EOF or -1 on error and sets silc_errno.
  76  *
  77  ***/
  78 int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
  79
  80 /****f* silcutil/SilcFileUtilAPI/silc_file_write
  81  *
  82  * SYNOPSIS
  83  *
  84  *    int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
  85  *
  86  * DESCRIPTION
  87  *
  88  *    Writes `buffer' of length of `len' to file descriptor `fd'.  Returns
  89  *    the amount of bytes written, 0 on EOF or -1 on error and sets silc_errno.
  90  *
  91  ***/
  92 int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
  93
  94 /****f* silcutil/SilcFileUtilAPI/silc_file_close
  95  *
  96  * SYNOPSIS
  97  *
  98  *    int silc_file_close(int fd);
  99  *
 100  * DESCRIPTION
 101  *
 102  *    Closes file descriptor previously opened with silc_file_open().
 103  *    Returns 0 on success or -1 on error and sets silc_errno.
 104  *
 105  ***/
 106 int silc_file_close(int fd);
 107
 108 /****f* silcutil/SilcFileUtilAPI/silc_file_set_nonblock
 109  *
 110  * SYNOPSIS
 111  *
 112  *    int silc_file_set_nonblock(int fd);
 113  *
 114  * DESCRIPTION
 115  *
 116  *    Sets the file descriptor to non-blocking mode.
 117  *
 118  ***/
 119 int silc_file_set_nonblock(int fd);
 120
 121 /****f* silcutil/SilcFileUtilAPI/silc_file_readfile
 122  *
 123  * SYNOPSIS
 124  *
 125  *    char *silc_file_readfile(const char *filename, SilcUInt32 *return_len,
 126  *                             SilcStack stack);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Reads the content of `filename' to a buffer.  The allocated buffer is
 131  *    returned.  This does not NULL terminate the buffer but EOF terminate
 132  *    it.  The caller must replace the EOF with NULL if the buffer must be
 133  *    NULL terminated.
 134  *
 135  *    If the `return_len' pointer is not NULL, it's filled with the length of
 136  *    the file.
 137  *
 138  *    If `stack' is non-NULL the returned buffer is allocated from `stack'.
 139  *    The allocation consumes `stack' so caller should push the stack before
 140  *    calling this function and pop it later.
 141  *
 142  ***/
 143 char *silc_file_readfile(const char *filename, SilcUInt32 *return_len,
 144                          SilcStack stack);
 145
 146 /****f* silcutil/SilcFileUtilAPI/silc_file_writefile
 147  *
 148  * SYNOPSIS
 149  *
 150  *    int silc_file_writefile(const char *filename, const char *buffer,
 151  *                            SilcUInt32 len);
 152  *
 153  * DESCRIPTION
 154  *
 155  *    Writes a buffer to the file.  If the file is created specific mode is
 156  *    set to the file.
 157  *
 158  ***/
 159 int silc_file_writefile(const char *filename, const char *buffer,
 160                         SilcUInt32 len);
 161
 162 /****f* silcutil/SilcFileUtilAPI/silc_file_writefile_mode
 163  *
 164  * SYNOPSIS
 165  *
 166  *    int silc_file_writefile_mode(const char *filename, const char *buffer,
 167  *                                 SilcUInt32 len, int mode);
 168  *
 169  * DESCRIPTION
 170  *
 171  *    Writes a buffer to the file.  If the file is created the specified `mode'
 172  *    is set to the file.
 173  *
 174  ***/
 175 int silc_file_writefile_mode(const char *filename, const char *buffer,
 176                              SilcUInt32 len, int mode);
 177
 178 /****f* silcutil/SilcFileUtilAPI/silc_file_size
 179  *
 180  * SYNOPSIS
 181  *
 182  *    SilcUInt64 silc_file_size(const char *filename);
 183  *
 184  * DESCRIPTION
 185  *
 186  *    Returns the size of `filename'. Returns 0 on error.
 187  *
 188  ***/
 189 SilcUInt64 silc_file_size(const char *filename);
 190
 191 #endif  /* !SILCFILEUTIL_H */