5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcutil/File Util Interface
24 * The SILC File Util Interface is a small set of functions that provides a
25 * portable access method to the filesystem.
29 #ifndef SILCFILEUTIL_H
30 #define SILCFILEUTIL_H
32 /****d* silcutil/SilcFileMode
36 * typedef enum { ... } SilcFileMode;
40 * A file mode bits that specify the file's mode, type and protection
41 * in the SilcFileStat context.
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 */
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 */
68 /****s* silcutil/SilcFileStat
72 * typedef struct SilcFileStatObject { ... } *SilcFileStat,
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.
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;
99 /****f* silcutil/silc_file_open
103 * int silc_file_open(const char *filename, int flags);
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
113 int silc_file_open(const char *filename, int flags);
115 /****f* silcutil/silc_file_open_mode
119 * int silc_file_open_mode(const char *filename, int flags, int mode);
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.
129 int silc_file_open_mode(const char *filename, int flags, int mode);
131 /****f* silcutil/silc_file_read
135 * int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
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.
143 int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
145 /****f* silcutil/silc_file_write
149 * int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
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.
157 int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
159 /****f* silcutil/silc_file_close
163 * int silc_file_close(int fd);
167 * Closes file descriptor previously opened with silc_file_open().
168 * Returns 0 on success or -1 on error and sets silc_errno.
171 int silc_file_close(int fd);
173 /****f* silcutil/silc_file_set_nonblock
177 * int silc_file_set_nonblock(int fd);
181 * Sets the file descriptor to non-blocking mode.
184 int silc_file_set_nonblock(int fd);
186 /****f* silcutil/silc_file_readfile
190 * char *silc_file_readfile(const char *filename, SilcUInt32 *return_len,
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
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.
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.
208 char *silc_file_readfile(const char *filename, SilcUInt32 *return_len,
211 /****f* silcutil/silc_file_writefile
215 * int silc_file_writefile(const char *filename, const char *buffer,
220 * Writes a buffer to the file. If the file is created specific mode is
224 int silc_file_writefile(const char *filename, const char *buffer,
227 /****f* silcutil/silc_file_writefile_mode
231 * int silc_file_writefile_mode(const char *filename, const char *buffer,
232 * SilcUInt32 len, int mode);
236 * Writes a buffer to the file. If the file is created the specified `mode'
237 * is set to the file.
240 int silc_file_writefile_mode(const char *filename, const char *buffer,
241 SilcUInt32 len, int mode);
243 /****f* silcutil/silc_file_size
247 * SilcUInt64 silc_file_size(const char *filename);
251 * Returns the size of `filename'. Returns 0 on error and sets silc_errno.
252 * If silc_errno is not set the file size is 0 bytes if this returns 0.
255 SilcUInt64 silc_file_size(const char *filename);
257 /****f* silcutil/silc_file_fsize
261 * SilcUInt64 silc_file_fsize(int fd);
265 * Returns the size of the file indicated by open file descriptor `fd'.
266 * Returns 0 on error and sets silc_errno. If silc_errno is not set the
267 * file size is 0 bytes if this returns 0.
270 SilcUInt64 silc_file_fsize(int fd);
272 /****f* silcutil/silc_file_stat
276 * SilcBool silc_file_stat(const char *filename, SilcBool follow_symlinks,
277 * SilcFileStat return_stat);
281 * Returns status information of a file named `filename'. The status
282 * information is returned to `return_stat' structure. If the
283 * `follow_symlinks' is TRUE this will return the status of the file the
284 * symlink referts to. If it is FALSE, returns the status of the link
287 * Returns FALSE on error and sets the silc_errno. Returns TRUE otherwise.
290 SilcBool silc_file_stat(const char *filename, SilcBool follow_symlinks,
291 SilcFileStat return_stat);
293 /****f* silcutil/silc_file_fstat
297 * SilcBool silc_file_fstat(int fd, SilcFileStat return_stat);
301 * Returns status information of a opened file indicated by the file
302 * descriptor `fd'. The status information is returned to the
303 * `return_stat' structure.
305 * Returns FALSE on error and sets the silc_errno. Returns TRUE otherwise.
308 SilcBool silc_file_fstat(int fd, SilcFileStat return_stat);
310 #endif /* !SILCFILEUTIL_H */