home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / ktempfile.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  6.3 KB  |  214 lines
  1. /*
  2.    This file is part of the KDE libraries
  3.    Copyright (c) 1999 Waldo Bastian <bastian@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 _KTEMPFILE_H_
  21. #define _KTEMPFILE_H_
  22.  
  23. #include <qstring.h>
  24. #include <stdio.h>
  25. #include <errno.h>
  26. #include "kdelibs_export.h"
  27.  
  28. class QFile;
  29. class QTextStream;
  30. class QDataStream;
  31. class KSaveFile;
  32. class KTempFilePrivate;
  33.  
  34. /**
  35.  * The KTempFile class creates and opens a unique file for temporary use.
  36.  *
  37.  * This is especially useful if you need to create a file in a world
  38.  * writable directory like /tmp without being vulnerable to so called
  39.  * symlink attacks.
  40.  *
  41.  * KDE applications, however, shouldn't create files in /tmp in the first 
  42.  * place but use the "tmp" resource instead. The standard KTempFile 
  43.  * constructor will do that by default.
  44.  *
  45.  * To create a temporary file that starts with a certain name
  46.  * in the "tmp" resource, one should use:
  47.  * KTempFile(locateLocal("tmp", prefix), extension);
  48.  *
  49.  * KTempFile does not create any missing directories, but locateLocal() does.
  50.  *
  51.  * See also KStandardDirs
  52.  *
  53.  * @author Waldo Bastian <bastian@kde.org>
  54.  */
  55. class KDECORE_EXPORT KTempFile
  56. {
  57.    friend class KSaveFile;
  58. public:
  59.    /**
  60.     * Creates a temporary file with the name:
  61.     *  \<filePrefix>\<six letters>\<fileExtension>
  62.     *
  63.     * The default @p filePrefix is "$KDEHOME/tmp-$HOST/appname/"
  64.     * The default @p fileExtension is ".tmp"
  65.     * @param filePrefix the prefix of the file name, or QString::null
  66.     *        for the default value
  67.     * @param fileExtension the extension of the prefix, or QString::null for the
  68.     *        default value
  69.     * @param mode the file permissions
  70.     **/
  71.    KTempFile(QString filePrefix=QString::null,
  72.              QString fileExtension=QString::null,
  73.              int mode = 0600 );
  74.  
  75.  
  76.    /**
  77.     * The destructor closes the file.
  78.     * If autoDelete is enabled the file gets unlinked as well.
  79.     **/
  80.    ~KTempFile();
  81.  
  82.    /**
  83.     * Turn automatic deletion on or off.
  84.     * Automatic deletion is off by default.
  85.     * @param autoDelete true to turn automatic deletion on
  86.     **/
  87.    void setAutoDelete(bool autoDelete) { bAutoDelete = autoDelete; }
  88.  
  89.    /**
  90.     * Returns the status of the file based on errno. (see errno.h)
  91.     * 0 means OK.
  92.     *
  93.     * You should check the status after object creation to check
  94.     * whether a file could be created in the first place.
  95.     *
  96.     * You may check the status after closing the file to verify that
  97.     * the file has indeed been written correctly.
  98.     * @return the errno status, 0 means ok
  99.     **/
  100.    int status() const;
  101.  
  102.    /**
  103.     * Returns the full path and name of the file.
  104.     *
  105.     * Note that in most circumstances the file needs to be closed 
  106.     * before you use it by name. 
  107.     *
  108.     * In particular, if another process or software part needs to write data 
  109.     * to the file based on the filename, the file should be closed before doing 
  110.     * so. Otherwise the act of closing the file later on may cause the file to 
  111.     * get truncated to a zero-size, resulting in an unexpected loss of the data.
  112.     *
  113.     * In some cases there is only interest in the filename itself but where the
  114.     * actual presence of a file with such name is a problem. In that case the
  115.     * file should first be both closed and unlinked. Such usage is not recommended
  116.     * since it may lead to the kind of symlink vulnerabilities that the KTempFile 
  117.     * design attempts to prevent.
  118.     *
  119.     * @return The name of the file, or QString::null if opening the
  120.     *         file has failed or the file has been unlinked already.
  121.     **/
  122.    QString name() const;
  123.    
  124.    /**
  125.     * An integer file descriptor open for writing to the file 
  126.     * @return The file descriptor, or a negative number if opening
  127.     *         the file failed
  128.     **/
  129.    int handle() const;
  130.    
  131.    /**
  132.     * Returns the FILE* of the temporary file.
  133.     * @return FILE* stream open for writing to the file, or 0
  134.     *         if opening the file failed
  135.     **/
  136.    FILE *fstream();
  137.  
  138.    /**
  139.     * Returns the QTextStream for writing.
  140.     * @return QTextStream open for writing to the file, or 0
  141.     *         if opening the file failed
  142.     **/
  143.    QTextStream *textStream();
  144.  
  145.    /**
  146.     * Returns a QDataStream for writing.
  147.     * @return QDataStream open for writing to the file, or 0 
  148.     *         if opening the file failed
  149.     **/
  150.    QDataStream *dataStream();
  151.  
  152.    /**
  153.     * Returns a QFile.
  154.     * @return A QFile open for writing to the file, or 0 if 
  155.     *         opening the file failed.
  156.     **/
  157.    QFile *file();
  158.  
  159.    /**
  160.     * Unlinks the file from the directory. The file is
  161.     * deleted once the last reader/writer closes it.
  162.     **/
  163.    void unlink();   
  164.  
  165.    /**
  166.     * Flushes file to disk (fsync).
  167.     *
  168.     * If you want to be as sure as possible that the file data has
  169.     * actually been physically stored on disk you need to call sync().
  170.     * 
  171.     * See status() for details about errors.
  172.     * @return true if successful, or false if an error has occurred.
  173.     * @since 3.3
  174.     **/
  175.    bool sync();
  176.  
  177.    /**
  178.     * Closes the file.
  179.     * 
  180.     * See status() for details about errors.
  181.     * @return true if successful, or false if an error has occurred.
  182.     **/
  183.    bool close();
  184.  
  185. protected:
  186.    /**
  187.     * Constructor used by KSaveFile
  188.     **/
  189.    KTempFile(bool);
  190.  
  191.    /**
  192.     * @internal
  193.     * Create function used internally by KTempFile and KSaveFile
  194.     **/
  195.    bool create(const QString &filePrefix, 
  196.                const QString &fileExtension, int mode);
  197.  
  198.    void setError(int error) { mError = error; }
  199. private:
  200.    int mError;
  201.    QString mTmpName;
  202.    int mFd;
  203.    FILE *mStream;
  204.    QFile *mFile;
  205.    QTextStream *mTextStream;
  206.    QDataStream *mDataStream;
  207.    bool bOpen;
  208.    bool bAutoDelete;
  209.  
  210.    KTempFilePrivate *d;
  211. };
  212.  
  213. #endif
  214.