lib/silcutil/silcdir.h

   1 /*
   2
   3   silcdir.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 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/SILC Directory Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * The SILC Directory API provides portable way to open and read directories
  25  * and their content.
  26  *
  27  * EXAMPLE
  28  *
  29  * SilcDir dir;
  30  * SilcDirEntry entry;
  31  *
  32  * dir = silc_dir_open("foodir");
  33  *
  34  * while ((entry = silc_dir_read(dir, NULL)))
  35  *   printf("File name: %s", silc_dir_entry_name(entry));
  36  *
  37  * silc_dir_close(dir);
  38  *
  39  ***/
  40
  41 #ifndef SILCDIR_H
  42 #define SILCDIR_H
  43
  44 /****s* silcutil/SilcDirAPI/SilcDir
  45  *
  46  * NAME
  47  *
  48  *    typedef struct SilcDirStruct *SilcDir;
  49  *
  50  * DESCRIPTION
  51  *
  52  *    The directory context.  This is allocated by silc_dir_open and
  53  *    freed by calling silc_dir_close.
  54  *
  55  ***/
  56 typedef struct SilcDirStruct *SilcDir;
  57
  58 /****s* silcutil/SilcDirAPI/SilcDirEntry
  59  *
  60  * NAME
  61  *
  62  *    typedef struct SilcDirEntryStruct *SilcDirEntry;
  63  *
  64  * DESCRIPTION
  65  *
  66  *    The directory entry context.  The entry is usually a file in the
  67  *    directory.
  68  *
  69  ***/
  70 typedef struct SilcDirEntryStruct *SilcDirEntry;
  71
  72 /****d* silcutil/SilcDirAPI/SilcDirEntryMode
  73  *
  74  * NAME
  75  *
  76  *    typedef enum { ... } SilcDirEntryMode;
  77  *
  78  * DESCRIPTION
  79  *
  80  *    The directory entry mode bits.  These bits specify the entry mode,
  81  *    type and protection.
  82  *
  83  ***/
  84 typedef enum {
  85   /* Type */
  86   SILC_DIR_ENTRY_IFDIR     = 0x00000001,  /* Entry is directory */
  87   SILC_DIR_ENTRY_IFCHR     = 0x00000002,  /* Entry is character device */
  88   SILC_DIR_ENTRY_IFBLK     = 0x00000004,  /* Entry is block device */
  89   SILC_DIR_ENTRY_IFREG     = 0x00000008,  /* Entry is regular file */
  90   SILC_DIR_ENTRY_IFIFO     = 0x00000010,  /* Entry is FIFO */
  91   SILC_DIR_ENTRY_IFLNK     = 0x00000020,  /* Entry is symbolic link */
  92   SILC_DIR_ENTRY_IFSOCK    = 0x00000040,  /* Entry is socket */
  93
  94   /* Protection */
  95   SILC_DIR_ENTRY_IRUSR     = 0x00000080,  /* Owner has read permission */
  96   SILC_DIR_ENTRY_IWUSR     = 0x00000100,  /* Owner has write permission */
  97   SILC_DIR_ENTRY_IXUSR     = 0x00000200,  /* Owner has execute permission */
  98   SILC_DIR_ENTRY_IRGRP     = 0x00000400,  /* Group has read permission */
  99   SILC_DIR_ENTRY_IWGRP     = 0x00000800,  /* Group has write permission */
 100   SILC_DIR_ENTRY_IXGRP     = 0x00001000,  /* Group has execute permission */
 101   SILC_DIR_ENTRY_IROTH     = 0x00002000,  /* Others have read permission */
 102   SILC_DIR_ENTRY_IWOTH     = 0x00004000,  /* Others have write permission */
 103   SILC_DIR_ENTRY_IXOTH     = 0x00008000,  /* Others have execute permission */
 104 } SilcDirEntryMode;
 105
 106 /****s* silcutil/SilcDirAPI/SilcDirEntryStat
 107  *
 108  * NAME
 109  *
 110  *    typedef struct SilcDirEntryObject { ... } *SilcDirEntryStat,
 111  *                                               SilcDirEntryStatStruct;
 112  *
 113  * DESCRIPTION
 114  *
 115  *    The directory entry status information structure.  The structure
 116  *    contains various information about the entry in the directory.
 117  *    This context is returned by silc_dir_read or silc_dir_entry_stat.
 118  *
 119  ***/
 120 typedef struct SilcDirEntryStatObject {
 121   SilcTimeStruct last_access;           /* Time of last access */
 122   SilcTimeStruct last_mod;              /* Time of last modification */
 123   SilcTimeStruct last_change;           /* Time of last status change */
 124   SilcUInt64 size;                      /* Entry size in bytes */
 125   SilcUInt32 uid;                       /* Owner ID of the entry */
 126   SilcUInt32 gid;                       /* Group owner ID of the entry */
 127   SilcUInt32 dev;                       /* Entry device number */
 128   SilcUInt32 nlink;                     /* Number of hard links */
 129   SilcDirEntryMode mode;                /* Entry mode */
 130 } *SilcDirEntryStat, SilcDirEntryStatStruct;
 131
 132 /****f* silcutil/SilcDirAPI/silc_dir_open
 133  *
 134  * SYNOPSIS
 135  *
 136  *    SilcDir silc_dir_open(const char *name);
 137  *
 138  * DESCRIPTION
 139  *
 140  *    Opens the directory named `name' and returns its context.  Returns NULL
 141  *    on error and sets the silc_errno.  This function must be called before
 142  *    being able to read the directory and its contents.
 143  *
 144  ***/
 145 SilcDir silc_dir_open(const char *name);
 146
 147 /****f* silcutil/SilcDirAPI/silc_dir_close
 148  *
 149  * SYNOPSIS
 150  *
 151  *    void silc_dir_close(SilcDir dir);
 152  *
 153  * DESCRIPTION
 154  *
 155  *    Closes the directory `dir'.
 156  *
 157  ***/
 158 void silc_dir_close(SilcDir dir);
 159
 160 /****f* silcutil/SilcDirAPI/silc_dir_read
 161  *
 162  * SYNOPSIS
 163  *
 164  *    SilcDirEntry silc_dir_read(SilcDir dir, SilcDirEntryStat *status);
 165  *
 166  * DESCRIPTION
 167  *
 168  *    Reads next entry (file) from the directory `dir'.  The silc_dir_open
 169  *    must be called first before reading from the directory.  Returns the
 170  *    next entry context or NULL if there are no more entries or error occurs.
 171  *    In case of error the silc_errno is also set.
 172  *
 173  *    If the `status' is non-NULL this will also call silc_dir_entry_stat
 174  *    and returns the status into the `status' pointer.
 175  *
 176  *    The returned context remains valid until the silc_dir_read is called
 177  *    again.
 178  *
 179  ***/
 180 SilcDirEntry silc_dir_read(SilcDir dir, SilcDirEntryStat *status);
 181
 182 /****f* silcutil/SilcDirAPI/silc_dir_rewind
 183  *
 184  * SYNOPSIS
 185  *
 186  *    void silc_dir_rewind(SilcDir dir);
 187  *
 188  * DESCRIPTION
 189  *
 190  *    Rewinds the directory `dir' to the beginning of the directory.  Calling
 191  *    silc_dir_read after this will return the first entry in the directory.
 192  *
 193  ***/
 194 void silc_dir_rewind(SilcDir dir);
 195
 196 /****f* silcutil/SilcDirAPI/silc_dir_name
 197  *
 198  * SYNOPSIS
 199  *
 200  *    const char *silc_dir_name(SilcDir dir);
 201  *
 202  * DESCRIPTION
 203  *
 204  *    Returns the name of the directory from `dir' context.
 205  *
 206  ***/
 207 const char *silc_dir_name(SilcDir dir);
 208
 209 /****f* silcutil/SilcDirAPI/silc_dir_entry_name
 210  *
 211  * SYNOPSIS
 212  *
 213  *    const char *silc_dir_entry_name(SilcDirEntry entry);
 214  *
 215  * DESCRIPTION
 216  *
 217  *    Returns the name of the entry (file) `entry'.  The returned pointer
 218  *    remains valid until the silc_dir_read is called again.
 219  *
 220  ***/
 221 const char *silc_dir_entry_name(SilcDirEntry entry);
 222
 223 /****f* silcutil/SilcDirAPI/silc_dir_entry_stat
 224  *
 225  * SYNOPSIS
 226  *
 227  *    SilcDirEntryStat silc_dir_entry_stat(SilcDir dir, SilcDirEntry entry);
 228  *
 229  * DESCRIPTION
 230  *
 231  *    Returns the status of the entry.  The status context contains details
 232  *    of the entry (file) in the directory.  Returns NULL on error and sets
 233  *    the silc_errno.
 234  *
 235  *    The returned contest is valid until the silc_dir_read is called again.
 236  *
 237  ***/
 238 SilcDirEntryStat silc_dir_entry_stat(SilcDir dir, SilcDirEntry entry);
 239
 240 #endif /* SILCDIR_H */