cfengine  3.15.4
About: CFEngine is a configuration management system for configuring and maintaining Unix-like computers (using an own high level policy language). Community version.
  Fossies Dox: cfengine-3.15.4.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

file_lib.h
Go to the documentation of this file.
1 /*
2  Copyright 2020 Northern.tech AS
3 
4  This file is part of CFEngine 3 - written and maintained by Northern.tech AS.
5 
6  This program is free software; you can redistribute it and/or modify it
7  under the terms of the GNU General Public License as published by the
8  Free Software Foundation; version 3.
9 
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License
16  along with this program; if not, write to the Free Software
17  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
18 
19  To the extent this program is licensed as part of the Enterprise
20  versions of CFEngine, the applicable Commercial Open Source License
21  (COSL) may apply to this file if you as a licensee so wish it. See
22  included file COSL.txt.
23 */
24 
25 #ifndef CFENGINE_FILE_LIB_H
26 #define CFENGINE_FILE_LIB_H
27 
28 #include <stdbool.h> // bool
29 #include <sys/types.h> // uid_t
30 #include <writer.h>
31 #include <set.h>
32 #include <sequence.h>
33 
34 typedef enum
35 {
36  NewLineMode_Unix, // LF everywhere
37  NewLineMode_Native // CRLF on Windows, LF elsewhere
39 
40 #define FILE_ERROR_READ -1
41 
42 /**
43  * Reads up to size_max bytes from filename and returns a Writer.
44  */
45 Writer *FileRead(const char *filename, size_t size_max, bool *truncated);
46 
47 /**
48  * Reads up to max_bytes bytes from file and writes into buf.
49  * Returns negative numbers in case of errors, bytes read/written otherwise.
50  */
51 ssize_t ReadFileStreamToBuffer(FILE *file, size_t max_bytes, char *buf);
52 
53 /**
54  * Copies a files content, without preserving metadata, times or permissions
55  */
56 bool File_Copy(const char *src, const char *dst);
57 
58 /**
59  * Same as CopyFile, except destination is a directory,
60  * and filename will match source
61  */
62 bool File_CopyToDir(const char *src, const char *dst_dir);
63 
64 /**
65  * Reads up to size_max bytes from fd and returns a Writer.
66  */
67 Writer *FileReadFromFd(int fd, size_t size_max, bool *truncated);
68 
69 bool FileCanOpen(const char *path, const char *modes);
70 
71 /* Write LEN bytes at PTR to descriptor DESC, retrying if interrupted.
72  Return LEN upon success, write's (negative) error code otherwise. */
73 ssize_t FullWrite(int desc, const char *ptr, size_t len);
74 
75 /* Read up to LEN bytes (or EOF) to PTR from descriptor DESC, retrying if interrupted.
76  Return amount of bytes read upon success, -1 otherwise */
77 ssize_t FullRead(int desc, char *ptr, size_t len);
78 
79 bool IsDirReal(const char *path);
80 
81 /**
82  * Returns what type of line endings the file is using.
83  *
84  * @param file File to check.
85  * @return Always returns NewLineMode_Unix on Unix. On Windows it may return
86  * NewLineMode_Native if the file has CRLF line endings.
87  * If the file cannot be opened, or the line endings are mixed it will
88  * return NewLineMode_Native. Note that only the first CF_BUFSIZE bytes
89  * are checked.
90  */
91 NewLineMode FileNewLineMode(const char *file);
92 
93 /* File node separator (cygwin can use \ or / but prefer \ for communicating
94  * with native windows commands). */
95 
96 #ifdef _WIN32
97 # define IsFileSep(c) ((c) == '\\' || (c) == '/')
98 # define FILE_SEPARATOR '\\'
99 # define FILE_SEPARATOR_STR "\\"
100 #else
101 # define IsFileSep(c) ((c) == '/')
102 # define FILE_SEPARATOR '/'
103 # define FILE_SEPARATOR_STR "/"
104 #endif
105 
106 StringSet* GlobFileList(const char *pattern);
107 
108 bool IsAbsoluteFileName(const char *f);
109 char *MapName(char *s);
110 char *MapNameCopy(const char *s);
111 char *MapNameForward(char *s);
112 
113 Seq *ListDir(const char *dir, const char *extension);
114 
115 mode_t SetUmask(mode_t new_mask);
116 void RestoreUmask(mode_t old_mask);
117 
118 int safe_open(const char *const pathname, int flags);
120  const char *pathname, int flags, mode_t create_perms);
121 
122 FILE *safe_fopen(const char *path, const char *mode);
124  const char *path, const char *mode, mode_t create_perms);
125 
126 int safe_chdir(const char *path);
127 int safe_chown(const char *path, uid_t owner, gid_t group);
128 int safe_chmod(const char *path, mode_t mode);
129 #ifndef __MINGW32__
130 int safe_lchown(const char *path, uid_t owner, gid_t group);
131 #endif
132 int safe_creat(const char *pathname, mode_t mode);
133 
134 /**
135  * @brief Sets whether a file descriptor should be closed on
136  * exec()/CreateProcess().
137  * @param fd File descriptor.
138  * @param inherit Whether to enable close-on-exec or not.
139  * @return true on success, false otherwise.
140  */
141 bool SetCloseOnExec(int fd, bool enable);
142 
143 /**
144  * @brief Deletes directory path recursively. Symlinks are not followed.
145  * Note that this function only deletes the contents of the directory, not the directory itself.
146  * @param path
147  * @return true if directory was deleted successfully, false if one or more files were not deleted.
148  */
149 bool DeleteDirectoryTree(const char *path);
150 
151 bool FileSparseWrite(int fd, const void *buf, size_t count,
152  bool *wrote_hole);
153 bool FileSparseCopy(int sd, const char *src_name,
154  int dd, const char *dst_name,
155  size_t blk_size,
156  size_t *total_bytes_written,
157  bool *last_write_was_a_hole);
158 bool FileSparseClose(int fd, const char *filename,
159  bool do_sync,
160  size_t total_bytes_written,
161  bool last_write_was_hole);
162 
163 /**
164  * @brief Works exactly like posix 'getline', EXCEPT it does not include carriage return at the end.
165  * @return -1 on error OR EOF, so check. Or bytes in buff without excluding terminator.
166  */
167 ssize_t CfReadLine(char **buff, size_t *size, FILE *fp);
168 
169 /**
170  * @brief Read lines from a file and return them as a sequence.
171  *
172  * @param buff If not %NULL, a buffer used for the internal CfReadLine() calls
173  * @param size Size of the buffer %buff (or 0)
174  * @param fp File to read the data from
175  * @param lines Sequence to append the read lines to
176  *
177  * @return Number of items/lines appended to #lines or -1 in case of error
178  * @note #buff can be reallocated by an internal CfReadLine() call in which case,
179  * #size is also adapted accordingly (just like getline() does)
180  * @warning The information about lengths of individual lines is lost,
181  * use CfReadLine() for files with NUL bytes.
182  */
183 ssize_t CfReadLines(char **buff, size_t *size, FILE *fp, Seq *lines);
184 
185 /**
186  * @brief For testing things against /proc, uses env var CFENGINE_TEST_OVERRIDE_PROCDIR
187  * @return the extra directory to add BEFORE /proc in the path
188  */
189 const char* GetRelocatedProcdirRoot();
190 
191 /*********** File locking ***********/
192 
193 typedef struct _FileLock {
194  /* may be extended with some other fields in the future */
195 
196  /**
197  * File descriptor to the file associated with the lock (if any)
198  * @note %fd == -1 is used to indicate that the lock is not associated with
199  * any file
200  */
201  int fd;
203 
204 #define EMPTY_FILE_LOCK { .fd = -1 }
205 
206 /**
207  * Try to acquire an exclusive lock.
208  *
209  * @param lock The lock to try to acquire. lock.fd needs to be an open FD.
210  * @param wait Whether to wait for the lock (blocks) or give up immediately.
211  * @return 0 in case of success, -1 in case of failure.
212  */
213 int ExclusiveFileLock(FileLock *lock, bool wait);
214 
215 /**
216  * Try to acquire an exclusive lock on the file given by path.
217  *
218  * @param lock The lock to try to acquire. lock.fd has to be -1.
219  * @param fpath Path to the file to lock.
220  * @param wait Whether to wait for the lock (blocks) or give up immediately.
221  * @return 0 in case of success,
222  * -1 in case of failure to lock,
223  * -2 in case of failure to open
224  */
225 int ExclusiveFileLockPath(FileLock *lock, const char *fpath, bool wait);
226 
227 /**
228  * Yield the previously acquired lock.
229  *
230  * @param lock Lock to yield.
231  * @param close_fd Whether to close the FD when yielding the lock.
232  * @return 0 in case of success, -1 in case of failure.
233  */
234 int ExclusiveFileUnlock(FileLock *lock, bool close_fd);
235 
236 /**
237  * @see ExclusiveFileLock()
238  */
239 int SharedFileLock(FileLock *lock, bool wait);
240 
241 /**
242  * @see ExclusiveFileLockPath()
243  * @note The resulting lock.fd is opened RDONLY (shared lock is semantically
244  * a reader lock).
245  */
246 int SharedFileLockPath(FileLock *lock, const char *fpath, bool wait);
247 
248 /**
249  * @see ExclusiveFileUnock()
250  */
251 int SharedFileUnlock(FileLock *lock, bool close_fd);
252 
253 #ifdef __MINGW32__
255  __attribute__ ((error("ExclusiveLockFileCheck() is not supported on Windows")));
256 #else
257 
258 /**
259  * Check if an exclusive lock could be acquired.
260  *
261  * @param lock Lock to check.
262  * @return Whether it would be possible to acquire an exclusive lock or not.
263  * @warning There is of course a race condition when this is used to check if
264  * a blocking call to ExclusiveFileLock() would block!
265  * @note If the current process is already holding a lock on the file,
266  * this function returns %true because a call to ExclusiveFileLock()
267  * would just succeed (no-op or change the lock type).
268  */
269 bool ExclusiveFileLockCheck(FileLock *lock);
270 #endif /* __MINGW32__ */
271 
272 #endif
bool FileSparseClose(int fd, const char *filename, bool do_sync, size_t total_bytes_written, bool last_write_was_hole)
Definition: file_lib.c:1426
bool DeleteDirectoryTree(const char *path)
Deletes directory path recursively. Symlinks are not followed. Note that this function only deletes t...
Definition: file_lib.c:1304
int safe_chmod(const char *path, mode_t mode)
Definition: file_lib.c:1122
int safe_chdir(const char *path)
Definition: file_lib.c:903
int ExclusiveFileLockPath(FileLock *lock, const char *fpath, bool wait)
Definition: file_lib.c:1808
bool FileCanOpen(const char *path, const char *modes)
Definition: file_lib.c:46
mode_t SetUmask(mode_t new_mask)
Definition: file_lib.c:496
ssize_t ReadFileStreamToBuffer(FILE *file, size_t max_bytes, char *buf)
Definition: file_lib.c:76
ssize_t CfReadLines(char **buff, size_t *size, FILE *fp, Seq *lines)
Read lines from a file and return them as a sequence.
Definition: file_lib.c:1493
ssize_t FullWrite(int desc, const char *ptr, size_t len)
Definition: file_lib.c:253
bool FileSparseCopy(int sd, const char *src_name, int dd, const char *dst_name, size_t blk_size, size_t *total_bytes_written, bool *last_write_was_a_hole)
Definition: file_lib.c:1358
int safe_open_create_perms(const char *pathname, int flags, mode_t create_perms)
Definition: file_lib.c:541
bool File_CopyToDir(const char *src, const char *dst_dir)
Definition: file_lib.c:177
ssize_t FullRead(int desc, char *ptr, size_t len)
Definition: file_lib.c:279
char * MapNameForward(char *s)
Definition: file_lib.c:453
int ExclusiveFileLock(FileLock *lock, bool wait)
Definition: file_lib.c:1648
int safe_lchown(const char *path, uid_t owner, gid_t group)
Definition: file_lib.c:1110
FILE * safe_fopen(const char *path, const char *mode)
Definition: file_lib.c:812
int safe_open(const char *const pathname, int flags)
Definition: file_lib.c:516
struct _FileLock FileLock
Seq * ListDir(const char *dir, const char *extension)
Definition: file_lib.c:471
const char * GetRelocatedProcdirRoot()
For testing things against /proc, uses env var CFENGINE_TEST_OVERRIDE_PROCDIR.
Definition: file_lib.c:1576
Writer * FileReadFromFd(int fd, size_t size_max, bool *truncated)
Definition: file_lib.c:207
int ExclusiveFileUnlock(FileLock *lock, bool close_fd)
Definition: file_lib.c:1684
int SharedFileLock(FileLock *lock, bool wait)
Definition: file_lib.c:1656
ssize_t CfReadLine(char **buff, size_t *size, FILE *fp)
Works exactly like posix 'getline', EXCEPT it does not include carriage return at the end.
Definition: file_lib.c:1476
bool IsDirReal(const char *path)
Definition: file_lib.c:314
bool SetCloseOnExec(int fd, bool enable)
Sets whether a file descriptor should be closed on exec()/CreateProcess().
Definition: file_lib.c:1212
char * MapNameCopy(const char *s)
Definition: file_lib.c:446
Writer * FileRead(const char *filename, size_t size_max, bool *truncated)
Definition: file_lib.c:63
NewLineMode FileNewLineMode(const char *file)
Definition: file_lib.c:327
bool File_Copy(const char *src, const char *dst)
Definition: file_lib.c:100
void RestoreUmask(mode_t old_mask)
Definition: file_lib.c:502
bool IsAbsoluteFileName(const char *f)
Definition: file_lib.c:333
bool ExclusiveFileLockCheck(FileLock *lock)
Definition: file_lib.c:1664
bool FileSparseWrite(int fd, const void *buf, size_t count, bool *wrote_hole)
Definition: file_lib.c:1316
int SharedFileLockPath(FileLock *lock, const char *fpath, bool wait)
Definition: file_lib.c:1829
int SharedFileUnlock(FileLock *lock, bool close_fd)
Definition: file_lib.c:1710
StringSet * GlobFileList(const char *pattern)
Definition: file_lib.c:1533
int safe_chown(const char *path, uid_t owner, gid_t group)
Definition: file_lib.c:1093
NewLineMode
Definition: file_lib.h:35
@ NewLineMode_Native
Definition: file_lib.h:37
@ NewLineMode_Unix
Definition: file_lib.h:36
int safe_creat(const char *pathname, mode_t mode)
Definition: file_lib.c:1203
FILE * safe_fopen_create_perms(const char *path, const char *mode, mode_t create_perms)
Definition: file_lib.c:832
char * MapName(char *s)
Definition: file_lib.c:441
Sequence data-structure.
Definition: sequence.h:50
Definition: set.h:138
Definition: writer.c:45
int fd
Definition: file_lib.h:201