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 */
52class KDECORE_EXPORT KTempDir
53{
54public:
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
149protected:
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
160private:
161 Q_DISABLE_COPY(KTempDir)
162 class Private;
163 Private * const d;
164};
165
166#endif
167