1 | /* |
2 | This file is part of the KDE libraries |
3 | Copyright (c) 2003 Joseph Wenninger <jowenn@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License version 2 as published by the Free Software Foundation. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KTEMPDIR_H |
21 | #define KTEMPDIR_H |
22 | |
23 | #include <kdecore_export.h> |
24 | #include <QtCore/QString> |
25 | |
26 | /** |
27 | * \class KTempDir ktempdir.h <KTempDir> |
28 | * |
29 | * @brief Create a unique directory for temporary use. |
30 | * |
31 | * The KTempDir class creates a unique directory for temporary use. |
32 | * |
33 | * This is especially useful if you need to create a directory in a world |
34 | * writable directory like /tmp without being vulnerable to so called |
35 | * symlink attacks. |
36 | * |
37 | * KDE applications, however, shouldn't create files or directories in /tmp |
38 | * in the first place but use the "tmp" resource instead. The standard |
39 | * KTempDir constructor will do that by default. |
40 | * |
41 | * To create a temporary directory that starts with a certain name |
42 | * in the "tmp" resource, one should use: |
43 | * KTempDir(KStandardDirs::locateLocal("tmp", prefix)); |
44 | * |
45 | * KTempDir does not create any missing directories, but |
46 | * KStandardDirs::locateLocal() does. |
47 | * |
48 | * @see KStandardDirs |
49 | * @see KTemporaryFile |
50 | * @author Joseph Wenninger <jowenn@kde.org> |
51 | */ |
52 | class KDECORE_EXPORT KTempDir |
53 | { |
54 | public: |
55 | /** |
56 | * Creates a temporary directory with the name: |
57 | * \p \<directoryPrefix\>\<six letters\> |
58 | * |
59 | * The default \p directoryPrefix is "$KDEHOME/tmp-$HOST/appname", i.e. |
60 | * as returned by KStandardDirs::locateLocal("tmp", KGlobal::mainComponent().componentName()) |
61 | * |
62 | * @param directoryPrefix the prefix of the file name, or |
63 | * QString() for the default value |
64 | * @param mode the file permissions, |
65 | * almost always in octal. The first digit selects permissions for |
66 | * the user who owns the file: read (4), write (2), and execute |
67 | * (1); the second selects permissions for other users in the |
68 | * file's group, with the same values; and the third for other |
69 | * users not in the file's group, with the same values. |
70 | * |
71 | **/ |
72 | explicit KTempDir(const QString& directoryPrefix=QString(), |
73 | int mode = 0700 ); |
74 | |
75 | |
76 | /** |
77 | * The destructor deletes the directory and its contents if autoRemove |
78 | * is set to true. |
79 | * @see setAutoRemove. |
80 | **/ |
81 | ~KTempDir(); |
82 | |
83 | /** |
84 | * Turn automatic deletion of the directory on or off. |
85 | * Automatic deletion is on by default. |
86 | * @param autoRemove toggle automatic deletion on or off |
87 | **/ |
88 | void setAutoRemove(bool autoRemove); |
89 | |
90 | /** |
91 | * @return whether auto remove is active |
92 | * @see setAutoRemove |
93 | **/ |
94 | bool autoRemove() const; |
95 | |
96 | /** |
97 | * Returns the status of the directory creation based on errno. |
98 | * (see errno.h) |
99 | * |
100 | * @note You should check the status after object creation to check |
101 | * whether the directory could be created. |
102 | * |
103 | * @return the errno status, 0 means ok |
104 | **/ |
105 | int status() const; |
106 | |
107 | /** |
108 | * Returns the full path and name of the directory, including a |
109 | * trailing '/'. |
110 | * @return The name of the directory, or QString() if creating the |
111 | * directory has failed or the directory has been unlinked |
112 | **/ |
113 | QString name() const; |
114 | |
115 | /** |
116 | * Deletes the directory recursively |
117 | **/ |
118 | void unlink(); |
119 | |
120 | /** |
121 | * Returns true if a temporary directory has successfully been created |
122 | * and has not been unlinked yet. |
123 | */ |
124 | bool exists() const; |
125 | |
126 | /** |
127 | * @brief Remove a directory and all its contents |
128 | * |
129 | * Remove recursively a directory, even if it is not empty |
130 | * or contains other directories. |
131 | * |
132 | * However the function works too when the @p path given |
133 | * is a non-directory file. In that case it simply remove that file. |
134 | * |
135 | * The function stops on the first error. |
136 | * |
137 | * @note This function is more meant for removing a directory |
138 | * not created by the user. For user-created directories, |
139 | * using KIO::del() is recommended instead, |
140 | * especially as it has user feedback for long operations. |
141 | * |
142 | * @param path Path of the directory to delete |
143 | * @return true if successful, otherwise false |
144 | * (Use errno for more details about the error.) |
145 | * @todo decide how and where this function should be defined in KDE5 |
146 | */ |
147 | static bool removeDir( const QString& path ); |
148 | |
149 | protected: |
150 | |
151 | /** |
152 | * Creates a "random" directory with specified mode |
153 | * @param directoryPrefix to use when creating temp directory |
154 | * (the rest is generated randomly) |
155 | * @param mode directory permissions |
156 | * @return true upon success |
157 | */ |
158 | bool create(const QString &directoryPrefix, int mode); |
159 | |
160 | private: |
161 | Q_DISABLE_COPY(KTempDir) |
162 | class Private; |
163 | Private * const d; |
164 | }; |
165 | |
166 | #endif |
167 | |