fs_entry.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2005, 2006, 2007, 2008 Ciaran McCreesh
00005  * Copyright (c) 2006 Mark Loeser
00006  *
00007  * This file is part of the Paludis package manager. Paludis is free software;
00008  * you can redistribute it and/or modify it under the terms of the GNU General
00009  * Public License version 2, as published by the Free Software Foundation.
00010  *
00011  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
00012  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00013  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00014  * details.
00015  *
00016  * You should have received a copy of the GNU General Public License along with
00017  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
00018  * Place, Suite 330, Boston, MA  02111-1307  USA
00019  */
00020 
00021 #ifndef PALUDIS_GUARD_PALUDIS_FS_ENTRY_HH
00022 #define PALUDIS_GUARD_PALUDIS_FS_ENTRY_HH 1
00023 
00024 #include <paludis/util/fs_entry-fwd.hh>
00025 #include <paludis/util/exception.hh>
00026 #include <paludis/util/operators.hh>
00027 #include <paludis/util/private_implementation_pattern.hh>
00028 #include <string>
00029 #include <tr1/memory>
00030 #include <iosfwd>
00031 #include <sys/types.h>
00032 #include <sys/stat.h>
00033 #include <ctime>
00034 
00035 /** \file
00036  * Declarations for FSEntry.
00037  *
00038  * \ingroup g_fs
00039  *
00040  * \section Examples
00041  *
00042  * - None at this time.
00043  */
00044 
00045 struct stat;
00046 struct utimbuf;
00047 
00048 namespace paludis
00049 {
00050     /**
00051      * Generic filesystem error class.
00052      *
00053      * \ingroup g_exceptions
00054      * \ingroup g_fs
00055      * \nosubgrouping
00056      */
00057     class PALUDIS_VISIBLE FSError :
00058         public Exception
00059     {
00060         public:
00061             ///\name Basic operations
00062             ///\{
00063 
00064             FSError(const std::string & message) throw ();
00065 
00066             ///\}
00067     };
00068 
00069     /**
00070      * Represents an entry (which may or may not exist) in the filesystem.
00071      *
00072      * \ingroup g_fs
00073      */
00074     class PALUDIS_VISIBLE FSEntry :
00075         public relational_operators::HasRelationalOperators,
00076         public arithmetic_operators::HasArithmeticOperators,
00077         private PrivateImplementationPattern<FSEntry>
00078     {
00079         friend std::ostream & operator<< (std::ostream & s, const FSEntry & f);
00080         friend class DirIterator;
00081 
00082         private:
00083             void _normalise();
00084 
00085             /**
00086              * Runs lstat() on the current path if we have not done so already.
00087              * Note: lstat() will give information on the symlink itself, and not what
00088              * the link points to, which is how stat() works.
00089              */
00090             void _stat() const;
00091 
00092             FSEntry(const std::string & path, unsigned char d_type);
00093 
00094         public:
00095             ///\name Basic operations
00096             ///\{
00097 
00098             FSEntry(const std::string & path);
00099 
00100             FSEntry(const FSEntry & other);
00101 
00102             ~FSEntry();
00103 
00104             const FSEntry & operator= (const FSEntry & other);
00105 
00106             ///\}
00107 
00108             ///\name Modification operations
00109             ///\{
00110 
00111             /**
00112              * Append another FSEntry.
00113              */
00114             const FSEntry & operator/= (const FSEntry & rhs);
00115 
00116             /**
00117              * Append another path.
00118              */
00119             const FSEntry & operator/= (const std::string & rhs)
00120             {
00121                 return operator/= (FSEntry(rhs));
00122             }
00123 
00124             /**
00125              * Join with another path.
00126              */
00127             FSEntry operator/ (const std::string & rhs) const
00128                 PALUDIS_ATTRIBUTE((warn_unused_result));
00129 
00130             ///\}
00131 
00132 
00133             ///\name Comparison operators
00134             ///\{
00135 
00136             bool operator< (const FSEntry &) const;
00137             bool operator== (const FSEntry &) const;
00138 
00139             ///\}
00140 
00141             /**
00142              * Return the last part of our path (eg '/foo/bar' => 'bar').
00143              */
00144             std::string basename() const
00145                 PALUDIS_ATTRIBUTE((warn_unused_result));
00146 
00147             /**
00148              * Return the path without a given prefix (eg '/foo/bar/baz'->strip_leading('/foo') => '/bar/baz').
00149              */
00150             FSEntry strip_leading(const FSEntry & prefix) const;
00151 
00152             /**
00153              * Return the first part of our path (eg '/foo/bar' => '/foo').
00154              */
00155             FSEntry dirname() const
00156                 PALUDIS_ATTRIBUTE((warn_unused_result));
00157 
00158 
00159             ///\}
00160 
00161             ///\name Filesystem queries
00162             ///\{
00163 
00164             /**
00165              * Does a filesystem entry exist at our location?
00166              */
00167             bool exists() const
00168                 PALUDIS_ATTRIBUTE((warn_unused_result));
00169 
00170             /**
00171              * Does a filesystem entry exist at our location, and if it does,
00172              * is it a directory?
00173              */
00174             bool is_directory() const
00175                 PALUDIS_ATTRIBUTE((warn_unused_result));
00176 
00177             /**
00178              * Does a filesystem entry exist at our location, and if it does,
00179              * is it a directory?
00180              */
00181             bool is_directory_or_symlink_to_directory() const
00182                 PALUDIS_ATTRIBUTE((warn_unused_result));
00183 
00184             /**
00185              * Does a filesystem entry exist at our location, and if it does,
00186              * is it a regular file?
00187              */
00188             bool is_regular_file() const
00189                 PALUDIS_ATTRIBUTE((warn_unused_result));
00190 
00191             /**
00192              * Does a filesystem entry exist at our location, and if it does,
00193              * is it a regular file?
00194              */
00195             bool is_regular_file_or_symlink_to_regular_file() const
00196                 PALUDIS_ATTRIBUTE((warn_unused_result));
00197 
00198             /**
00199              * Does a filesystem entry exist at our location, and if it does,
00200              * is it a symbolic link?
00201              */
00202             bool is_symbolic_link() const
00203                 PALUDIS_ATTRIBUTE((warn_unused_result));
00204 
00205             /**
00206              * Whether we exist and are a device file.
00207              */
00208             bool is_device() const
00209                 PALUDIS_ATTRIBUTE((warn_unused_result));
00210 
00211             /**
00212              * Whether we exist and are a fifo.
00213              */
00214             bool is_fifo() const
00215                 PALUDIS_ATTRIBUTE((warn_unused_result));
00216 
00217             /**
00218              * Check if filesystem entry has `perm` for `user_group`.
00219              *
00220              * \exception FSError if there was a problem accessing the filesystem entry
00221              */
00222             bool has_permission(const FSUserGroup & user_group, const FSPermission & fs_perm) const
00223                 PALUDIS_ATTRIBUTE((warn_unused_result));
00224 
00225             /**
00226              * Return the permissions for our item.
00227              *
00228              * \exception FSError if there was a problem accessing the filesystem entry
00229              */
00230             mode_t permissions() const
00231                 PALUDIS_ATTRIBUTE((warn_unused_result));
00232 
00233             /**
00234              * Return the canonicalised version of our path.
00235              */
00236             FSEntry realpath() const
00237                 PALUDIS_ATTRIBUTE((warn_unused_result));
00238 
00239             /**
00240              * Return the canonicalised version of our path, if it exists, or
00241              * ourself if it doesn't.
00242              */
00243             FSEntry realpath_if_exists() const
00244                 PALUDIS_ATTRIBUTE((warn_unused_result));
00245 
00246             /**
00247              * Return our destination, if we are a symlink.
00248              *
00249              * \exception FSError if we are not a symlink, or if the system call
00250              * fails.
00251              */
00252             std::string readlink() const
00253                 PALUDIS_ATTRIBUTE((warn_unused_result));
00254 
00255             /**
00256              * Return the time the inode for the filesystem entry was last modified
00257              * \exception FSError if there was a problem accessing the filesystem entry
00258              */
00259             time_t ctime() const
00260                 PALUDIS_ATTRIBUTE((warn_unused_result));
00261 
00262             /**
00263              * Return the time the filesystem entry was last modified
00264              * \exception FSError if there was a problem accessing the filesystem entry
00265              */
00266             time_t mtime() const
00267                 PALUDIS_ATTRIBUTE((warn_unused_result));
00268 
00269             /**
00270              * Return the size of our file, in bytes.
00271              *
00272              * \exception FSError if we don't have a size.
00273              */
00274             off_t file_size() const
00275                 PALUDIS_ATTRIBUTE((warn_unused_result));
00276 
00277             /**
00278              * Fetch our owner.
00279              *
00280              * \exception FSError If we don't exist or the stat call fails.
00281              */
00282             uid_t owner() const
00283                 PALUDIS_ATTRIBUTE((warn_unused_result));
00284 
00285             /**
00286              * Fetch our group.
00287              *
00288              * \exception FSError If we don't exist or the stat call fails.
00289              */
00290             gid_t group() const
00291                 PALUDIS_ATTRIBUTE((warn_unused_result));
00292 
00293             /**
00294              * Return the current working directory
00295              */
00296             static FSEntry cwd()
00297                 PALUDIS_ATTRIBUTE((warn_unused_result));
00298 
00299             /**
00300              * Return an unique low-level id for this entry
00301              */
00302             std::pair<dev_t, ino_t> lowlevel_id() const
00303                 PALUDIS_ATTRIBUTE((warn_unused_result));
00304 
00305             ///\}
00306 
00307             ///\name Filesystem operations
00308             ///\{
00309 
00310             /**
00311              * Try to make a directory.
00312              *
00313              * \return True, if we succeeded, and false if the directory
00314              *   already exists and is a directory.
00315              *
00316              * \exception FSError If an error other than the directory already
00317              *   existing occurs.
00318              */
00319             bool mkdir(const mode_t mode = 0755);
00320 
00321             /**
00322              * Try to make a symlink.
00323              *
00324              * \return True, if we succeeded, and false if the target already
00325              *   exists and is a symlink to the same target.
00326              *
00327              * \exception FSError If an error other than the symlink already
00328              *   existing occurs, or if the symlink exists and points elsewhere.
00329              */
00330             bool symlink(const std::string & target);
00331 
00332             /**
00333              * Try to unlink.
00334              *
00335              * \return True, if we succeeded, and false if we don't exist
00336              *   already.
00337              *
00338              * \exception FSError If an error other than us already not
00339              *   existing occurs.
00340              */
00341             bool unlink();
00342 
00343             /**
00344              * Try to rmdir.
00345              *
00346              * \return True, if we succeeded, and false if we don't exist
00347              *   already.
00348              *
00349              * \exception FSError If an error other than us already not
00350              *   existing occurs.
00351              */
00352             bool rmdir();
00353 
00354             /**
00355              * Try to set atime and mtime
00356              *
00357              * \return True, if we succeeded, and false if we don't exist
00358              *   already.
00359              *
00360              * \exception FSError If an error other than us already not
00361              *   existing ocurrs.
00362              */
00363             bool utime(const struct ::utimbuf * buf = 0);
00364 
00365             /**
00366              * Change our ownership, following symlinks.
00367              *
00368              * \exception FSError If the chown failed.
00369              */
00370             void chown(const uid_t owner, const gid_t group = static_cast<gid_t>(-1));
00371 
00372             /**
00373              * Change our ownership, not following symlinks.
00374              *
00375              * \exception FSError If the lchown failed.
00376              */
00377             void lchown(const uid_t owner, const gid_t group = static_cast<gid_t>(-1));
00378 
00379             /**
00380              * Change our permissions.
00381              *
00382              * \exception FSError If the chmod failed.
00383              */
00384             void chmod(const mode_t mode);
00385 
00386             /**
00387              * Rename ourself (will not work across mount points).
00388              *
00389              * \exception FSError If the rename failed.
00390              */
00391             void rename(const FSEntry & new_name);
00392 
00393             ///\}
00394     };
00395 }
00396 
00397 #endif

Generated on Mon Sep 21 10:36:08 2009 for paludis by  doxygen 1.5.4