1/**
2 * @file op_file.h
3 * Useful file management helpers
4 *
5 * @remark Copyright 2002 OProfile authors
6 * @remark Read the file COPYING
7 *
8 * @author John Levon
9 * @author Philippe Elie
10 */
11
12#ifndef OP_FILE_H
13#define OP_FILE_H
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19#include <sys/types.h>
20
21/**
22 * op_file_readable - is a file readable
23 * @param file file name
24 *
25 * Return true if the given file is readable and regular.
26 *
27 * Beware of race conditions !
28 */
29int op_file_readable(char const * file);
30
31/**
32 * op_get_mtime - get mtime of file
33 * @param file  file name
34 *
35 * Returns the mtime of the given file or 0 on failure
36 */
37time_t op_get_mtime(char const * file);
38
39/**
40 * create_dir - create a directory
41 * @param dir  the directory name to create
42 *
43 * Returns 0 on success.
44 */
45int create_dir(char const * dir);
46
47
48/**
49 * create_path - create a path
50 * @param path  the path to create
51 *
52 * create directory for each dir components in path
53 * the last path component is not considered as a directory
54 * but as a filename
55 *
56 * Returns 0 on success.
57 */
58int create_path(char const * path);
59
60/**
61 * Clients of get_matching_pathnames must provide their own implementation
62 * of get_pathname_callback.
63 */
64typedef void (*get_pathname_callback)(char const * pathname, void * name_list);
65
66/* This enum is intended solely for the use of get_matching_pathnames(),
67 * bit 0 is reserved for internal use..*/
68enum recursion_type {
69	NO_RECURSION = 2,
70	MATCH_ANY_ENTRY_RECURSION = 4,
71	MATCH_DIR_ONLY_RECURSION = 8,
72};
73/**
74 * @param name_list where to store result
75 * @param get_pathname_callback client-provided callback function
76 * @param base_dir directory from where lookup starts
77 * @param filter a pathname filter
78 * @param recursion recursion_type -- see above enum and following description:
79 *	NO_RECURSION:  Find matching files from passed base_dir and call
80 *          get_pathname_callback to add entry to name_list to be returned.
81 *	MATCH_ANY_ENTRY_RECURSION: Starting at base_dir, for each entry in the
82 *	   dir that matches the filter: if entry is of type 'dir', recurse;
83 *         else call get_pathname_callback to add entry to name_list to be
84 *         returned.
85 *	MATCH_DIR_ONLY_RECURSION: Starting at base_dir, if an entry in the
86 *         dir is of type 'dir' and its complete pathname contains a match to
87 *         the filter, call get_pathname_callback to add entry to name_list to
88 *         be returned; else recurse.
89 *
90 * Returns 0 on success.
91 *
92 * Return a list of pathnames under base_dir, filtered by filter and optionally
93 * looking in sub-directory. See description above of the recursion_type
94 * parameter for more details.
95 *    NOTE: For C clients: Your implementation of the get_pathname_callback
96 *          function will probably dynamically allocate storage for elements
97 *          added to name_list.  If so, remember to free that memory when it's
98 *          no longer needed.
99 */
100int get_matching_pathnames(void * name_list, get_pathname_callback,
101			   char const * base_dir, char const * filter,
102			   enum recursion_type recursion);
103
104
105#ifdef __cplusplus
106}
107#endif
108
109#endif /* OP_FILE_H */
110