1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
/*
This file is part of the KDE libraries
Copyright (c) 1999 Waldo Bastian <bastian@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License version 2 as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#ifndef _KSAVEFILE_H_
#define _KSAVEFILE_H_
#include <qstring.h>
#include <stdio.h>
#include <errno.h>
#include <ktempfile.h>
class KSaveFilePrivate;
/**
* The KSaveFile class has been made to write out changes to an existing
* file atomically.
* This means that EITHER:
* a)
* All changes have been written successfully to the file.
*
* b)
* Some error occurred, no changes have been written whatsoever and the
* old file is still in place.
*/
class KDECORE_EXPORT KSaveFile
{
public:
/**
* Creates a new KSaveFile with the given file name.
* @param filename the path of the file
* @param mode the mode of the file (see chmod(1))
*/
KSaveFile(const QString &filename, int mode = 0666 );
/**
* The destructor closes the file.
* You might want to call close() explicitely though, to test whether it worked.
**/
~KSaveFile();
/**
* Returns the status of the file based on errno. (see errno.h)
* 0 means OK.
*
* You should check the status after object creation to check
* whether a file could be created in the first place.
*
* You may check the status after closing the file to verify that
* the file has indeed been written correctly.
* @return the errno status, 0 means ok
**/
int status() const
{ return mTempFile.status(); }
/**
* The name of the file as passed to the constructor.
* @return The name of the file, or QString::null if opening the
* file has failed
**/
QString name() const;
/**
* An integer file descriptor open for writing to the file.
* @return The file descriptor, or a negative number if opening
* the temporary file failed
**/
int handle() const
{ return mTempFile.handle(); }
/**
* A FILE* stream open for writing to the file.
* @return FILE* stream open for writing to the file, or 0
* if opening the temporary file failed
**/
FILE *fstream()
{ return mTempFile.fstream(); }
/**
* A QFile* open for writing to the file.
* @return A QFile open for writing to the file, or 0 if
* opening the temporary file failed.
**/
QFile *file()
{ return mTempFile.file(); }
/**
* A QTextStream* open for writing to the file.
* @return A QTextStream that is open for writing to the file, or 0
* if opening the temporary file failed
**/
QTextStream *textStream()
{ return mTempFile.textStream(); }
/**
* A QDataStream* open for writing to the file.
* @return A QDataStream that is open for writing to the file, or 0
* if opening the file failed
**/
QDataStream *dataStream()
{ return mTempFile.dataStream(); }
/**
* Aborts the write operation and removes any intermediate files
* This implies a close.
**/
void abort();
/**
* Closes the file and makes the changes definitive.
* Returns 'true' is successful, or 'false' if an error has occurred.
* See status() for details about errors.
* @return true if successful, or false if an error has occurred.
**/
bool close();
/**
* Static method to create a backup file before saving.
* You can use this method even if you don't use KSaveFile.
* @param filename the file to backup
* @param backupDir optional directory where to save the backup file in.
* If empty (the default), the backup will be in the same directory as @p filename.
* @param backupExtension the extension to append to @p filename, "~" by default.
* @since 3.2
*/
static bool backupFile( const QString& filename,
const QString& backupDir = QString::null,
const QString& backupExtension = QString::fromLatin1( "~" ) );
private:
QString mFileName;
KTempFile mTempFile;
KSaveFilePrivate *d;
};
#endif
|
