lib/silcutil/silcfileutil.h

   1 /*
   2
   3   silcfileutil.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2008 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/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 /****d* silcutil/SilcFileMode
  33  *
  34  * NAME
  35  *
  36  *    typedef enum { ... } SilcFileMode;
  37  *
  38  * DESCRIPTION
  39  *
  40  *    A file mode bits that specify the file's mode, type and protection
  41  *    in the SilcFileStat context.
  42  *
  43  * SOURCE
  44  */
  45 typedef enum {
  46   /* Type */
  47   SILC_FILE_IFDIR     = 0x00000001,  /* Entry is directory */
  48   SILC_FILE_IFCHR     = 0x00000002,  /* Entry is character device */
  49   SILC_FILE_IFBLK     = 0x00000004,  /* Entry is block device */
  50   SILC_FILE_IFREG     = 0x00000008,  /* Entry is regular file */
  51   SILC_FILE_IFIFO     = 0x00000010,  /* Entry is FIFO */
  52   SILC_FILE_IFLNK     = 0x00000020,  /* Entry is symbolic link */
  53   SILC_FILE_IFSOCK    = 0x00000040,  /* Entry is socket */
  54
  55   /* Protection */
  56   SILC_FILE_IRUSR     = 0x00000080,  /* Owner has read permission */
  57   SILC_FILE_IWUSR     = 0x00000100,  /* Owner has write permission */
  58   SILC_FILE_IXUSR     = 0x00000200,  /* Owner has execute permission */
  59   SILC_FILE_IRGRP     = 0x00000400,  /* Group has read permission */
  60   SILC_FILE_IWGRP     = 0x00000800,  /* Group has write permission */
  61   SILC_FILE_IXGRP     = 0x00001000,  /* Group has execute permission */
  62   SILC_FILE_IROTH     = 0x00002000,  /* Others have read permission */
  63   SILC_FILE_IWOTH     = 0x00004000,  /* Others have write permission */
  64   SILC_FILE_IXOTH     = 0x00008000,  /* Others have execute permission */
  65 } SilcFileMode;
  66 /***/
  67
  68 /****s* silcutil/SilcFileStat
  69  *
  70  * NAME
  71  *
  72  *    typedef struct SilcFileStatObject { ... } *SilcFileStat,
  73  *                                               SilcFileStatStruct;
  74  *
  75  * DESCRIPTION
  76  *
  77  *    The file entry status information structure.  The structure contains
  78  *    various information about a file.  The structure is filled by calling
  79  *    the silc_file_stat or silc_file_fstat functions.
  80  *
  81  * SOURCE
  82  */
  83 typedef struct SilcFileStatObject {
  84   SilcTimeStruct last_access;           /* Time of last access */
  85   SilcTimeStruct last_mod;              /* Time of last modification */
  86   SilcTimeStruct last_change;           /* Time of last status change */
  87   SilcUInt64 size;                      /* Entry size in bytes */
  88   SilcUInt32 uid;                       /* Owner ID of the entry */
  89   SilcUInt32 gid;                       /* Group owner ID of the entry */
  90   SilcUInt32 dev;                       /* Entry device number */
  91   SilcUInt32 rdev;                      /* Device number if special file */
  92   SilcUInt32 nlink;                     /* Number of hard links */
  93   SilcFileMode mode;                    /* Entry mode */
  94 } *SilcFileStat, SilcFileStatStruct;
  95 /***/
  96
  97 /* Prototypes */
  98
  99 /****f* silcutil/silc_file_open
 100  *
 101  * SYNOPSIS
 102  *
 103  *    int silc_file_open(const char *filename, int flags);
 104  *
 105  * DESCRIPTION
 106  *
 107  *    Opens a file indicated by the filename `filename' with flags indicated
 108  *    by `flags'.  The opening permission defaults to 0600.  The `flags'
 109  *    are defined in open(2).  Returns the opened file descriptor or -1 on
 110  *    error.
 111  *
 112  ***/
 113 int silc_file_open(const char *filename, int flags);
 114
 115 /****f* silcutil/silc_file_open_mode
 116  *
 117  * SYNOPSIS
 118  *
 119  *    int silc_file_open_mode(const char *filename, int flags, int mode);
 120  *
 121  * DESCRIPTION
 122  *
 123  *    Opens a file indicated by the filename `filename' with flags indicated
 124  *    by `flags'.  The argument `mode' specifies the permissions to use in
 125  *    case a new file is created.  The `flags' are defined in open(2).
 126  *    Returns the opened file descriptor or -1 on error and sets silc_errno.
 127  *
 128  ***/
 129 int silc_file_open_mode(const char *filename, int flags, int mode);
 130
 131 /****f* silcutil/silc_file_read
 132  *
 133  * SYNOPSIS
 134  *
 135  *    int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
 136  *
 137  * DESCRIPTION
 138  *
 139  *    Reads data from file descriptor `fd' to `buf'.  Returns the amount of
 140  *    bytes read, 0 on EOF or -1 on error and sets silc_errno.
 141  *
 142  ***/
 143 int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
 144
 145 /****f* silcutil/silc_file_write
 146  *
 147  * SYNOPSIS
 148  *
 149  *    int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
 150  *
 151  * DESCRIPTION
 152  *
 153  *    Writes `buffer' of length of `len' to file descriptor `fd'.  Returns
 154  *    the amount of bytes written, 0 on EOF or -1 on error and sets silc_errno.
 155  *
 156  ***/
 157 int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
 158
 159 /****f* silcutil/silc_file_close
 160  *
 161  * SYNOPSIS
 162  *
 163  *    int silc_file_close(int fd);
 164  *
 165  * DESCRIPTION
 166  *
 167  *    Closes file descriptor previously opened with silc_file_open().
 168  *    Returns 0 on success or -1 on error and sets silc_errno.
 169  *
 170  ***/
 171 int silc_file_close(int fd);
 172
 173 /****f* silcutil/silc_file_set_nonblock
 174  *
 175  * SYNOPSIS
 176  *
 177  *    int silc_file_set_nonblock(int fd);
 178  *
 179  * DESCRIPTION
 180  *
 181  *    Sets the file descriptor to non-blocking mode.
 182  *
 183  ***/
 184 int silc_file_set_nonblock(int fd);
 185
 186 /****f* silcutil/silc_file_readfile
 187  *
 188  * SYNOPSIS
 189  *
 190  *    char *silc_file_readfile(const char *filename, SilcUInt32 *return_len,
 191  *                             SilcStack stack);
 192  *
 193  * DESCRIPTION
 194  *
 195  *    Reads the content of `filename' to a buffer.  The allocated buffer is
 196  *    returned.  This does not NULL terminate the buffer but EOF terminate
 197  *    it.  The caller must replace the EOF with NULL if the buffer must be
 198  *    NULL terminated.
 199  *
 200  *    If the `return_len' pointer is not NULL, it's filled with the length of
 201  *    the file.  The returned length does not include the terminator.
 202  *
 203  *    If `stack' is non-NULL the returned buffer is allocated from `stack'.
 204  *    The allocation consumes `stack' so caller should push the stack before
 205  *    calling this function and pop it later.
 206  *
 207  ***/
 208 char *silc_file_readfile(const char *filename, SilcUInt32 *return_len,
 209                          SilcStack stack);
 210
 211 /****f* silcutil/silc_file_writefile
 212  *
 213  * SYNOPSIS
 214  *
 215  *    int silc_file_writefile(const char *filename, const char *buffer,
 216  *                            SilcUInt32 len);
 217  *
 218  * DESCRIPTION
 219  *
 220  *    Writes a buffer to the file.  Returns 0 on success and -1 on error.
 221  *
 222  ***/
 223 int silc_file_writefile(const char *filename, const char *buffer,
 224                         SilcUInt32 len);
 225
 226 /****f* silcutil/silc_file_writefile_mode
 227  *
 228  * SYNOPSIS
 229  *
 230  *    int silc_file_writefile_mode(const char *filename, const char *buffer,
 231  *                                 SilcUInt32 len, int mode);
 232  *
 233  * DESCRIPTION
 234  *
 235  *    Writes a buffer to the file.  If the file is created the specified `mode'
 236  *    is set to the file.  Returns 0 on success and -1 on error.
 237  *
 238  ***/
 239 int silc_file_writefile_mode(const char *filename, const char *buffer,
 240                              SilcUInt32 len, int mode);
 241
 242 /****f* silcutil/silc_file_size
 243  *
 244  * SYNOPSIS
 245  *
 246  *    SilcUInt64 silc_file_size(const char *filename);
 247  *
 248  * DESCRIPTION
 249  *
 250  *    Returns the size of `filename'.  Returns 0 on error and sets silc_errno.
 251  *    If silc_errno is not set the file size is 0 bytes if this returns 0.
 252  *
 253  ***/
 254 SilcUInt64 silc_file_size(const char *filename);
 255
 256 /****f* silcutil/silc_file_fsize
 257  *
 258  * SYNOPSIS
 259  *
 260  *    SilcUInt64 silc_file_fsize(int fd);
 261  *
 262  * DESCRIPTION
 263  *
 264  *    Returns the size of the file indicated by open file descriptor `fd'.
 265  *    Returns 0 on error and sets silc_errno.  If silc_errno is not set the
 266  *    file size is 0 bytes if this returns 0.
 267  *
 268  ***/
 269 SilcUInt64 silc_file_fsize(int fd);
 270
 271 /****f* silcutil/silc_file_stat
 272  *
 273  * SYNOPSIS
 274  *
 275  *    SilcBool silc_file_stat(const char *filename, SilcBool follow_symlinks,
 276  *                            SilcFileStat return_stat);
 277  *
 278  * DESCRIPTION
 279  *
 280  *    Returns status information of a file named `filename'.  The status
 281  *    information is returned to `return_stat' structure.  If the
 282  *    `follow_symlinks' is TRUE this will return the status of the file the
 283  *    symlink referts to.  If it is FALSE, returns the status of the link
 284  *    itself.
 285  *
 286  *    Returns FALSE on error and sets the silc_errno.  Returns TRUE otherwise.
 287  *
 288  ***/
 289 SilcBool silc_file_stat(const char *filename, SilcBool follow_symlinks,
 290                         SilcFileStat return_stat);
 291
 292 /****f* silcutil/silc_file_fstat
 293  *
 294  * SYNOPSIS
 295  *
 296  *    SilcBool silc_file_fstat(int fd, SilcFileStat return_stat);
 297  *
 298  * DESCRIPTION
 299  *
 300  *    Returns status information of a opened file indicated by the file
 301  *    descriptor `fd'.  The status information is returned to the
 302  *    `return_stat' structure.
 303  *
 304  *    Returns FALSE on error and sets the silc_errno.  Returns TRUE otherwise.
 305  *
 306  ***/
 307 SilcBool silc_file_fstat(int fd, SilcFileStat return_stat);
 308
 309 #endif  /* !SILCFILEUTIL_H */