qfileinfo(3qt)

1QFileInfo(3qt)                                                  QFileInfo(3qt)
2
3
4

NAME

6       QFileInfo - System-independent file information
7

SYNOPSIS

9       All the functions in this class are reentrant when Qt is built with
10       thread support.</p>
11
12       #include <qfileinfo.h>
13
14   Public Members
15       enum PermissionSpec { ReadOwner = 04000, WriteOwner = 02000, ExeOwner =
16           01000, ReadUser = 00400, WriteUser = 00200, ExeUser = 00100,
17           ReadGroup = 00040, WriteGroup = 00020, ExeGroup = 00010, ReadOther
18           = 00004, WriteOther = 00002, ExeOther = 00001 }
19       QFileInfo ()
20       QFileInfo ( const QString & file )
21       QFileInfo ( const QFile & file )
22       QFileInfo ( const QDir & d, const QString & fileName )
23       QFileInfo ( const QFileInfo & fi )
24       ~QFileInfo ()
25       QFileInfo & operator= ( const QFileInfo & fi )
26       void setFile ( const QString & file )
27       void setFile ( const QFile & file )
28       void setFile ( const QDir & d, const QString & fileName )
29       bool exists () const
30       void refresh () const
31       bool caching () const
32       void setCaching ( bool enable )
33       QString filePath () const
34       QString fileName () const
35       QString absFilePath () const
36       QString baseName ( bool complete = FALSE ) const
37       QString extension ( bool complete = TRUE ) const
38       QString dirPath ( bool absPath = FALSE ) const
39       QDir dir ( bool absPath = FALSE ) const
40       bool isReadable () const
41       bool isWritable () const
42       bool isExecutable () const
43       bool isHidden () const
44       bool isRelative () const
45       bool convertToAbs ()
46       bool isFile () const
47       bool isDir () const
48       bool isSymLink () const
49       QString readLink () const
50       QString owner () const
51       uint ownerId () const
52       QString group () const
53       uint groupId () const
54       bool permission ( int permissionSpec ) const
55       uint size () const
56       QDateTime created () const
57       QDateTime lastModified () const
58       QDateTime lastRead () const
59

DESCRIPTION

61       The QFileInfo class provides system-independent file information.
62
63       QFileInfo provides information about a file's name and position (path)
64       in the file system, its access rights and whether it is a directory or
65       symbolic link, etc. The file's size and last modified/read times are
66       also available.
67
68       A QFileInfo can point to a file with either a relative or an absolute
69       file path. Absolute file paths begin with the directory separator "/"
70       (or with a drive specification on Windows). Relative file names begin
71       with a directory name or a file name and specify a path relative to the
72       current working directory. An example of an absolute path is the string
73       "/tmp/quartz". A relative path might look like "src/fatlib". You can
74       use the function isRelative() to check whether a QFileInfo is using a
75       relative or an absolute file path. You can call the function
76       convertToAbs() to convert a relative QFileInfo's path to an absolute
77       path.
78
79       The file that the QFileInfo works on is set in the constructor or later
80       with setFile(). Use exists() to see if the file exists and size() to
81       get its size.
82
83       To speed up performance, QFileInfo caches information about the file.
84       Because files can be changed by other users or programs, or even by
85       other parts of the same program, there is a function that refreshes the
86       file information: refresh(). If you want to switch off a QFileInfo's
87       caching and force it to access the file system every time you request
88       information from it call setCaching(FALSE).
89
90       The file's type is obtained with isFile(), isDir() and isSymLink(). The
91       readLink() function provides the name of the file the symlink points
92       to.
93
94       Elements of the file's name can be extracted with dirPath() and
95       fileName(). The fileName()'s parts can be extracted with baseName() and
96       extension().
97
98       The file's dates are returned by created(), lastModified() and
99       lastRead(). Information about the file's access permissions is obtained
100       with isReadable(), isWritable() and isExecutable(). The file's
101       ownership is available from owner(), ownerId(), group() and groupId().
102       You can examine a file's permissions and ownership in a single
103       statement using the permission() function.
104
105       If you need to read and traverse directories, see the QDir class.
106
107       See also Input/Output and Networking.
108
109   Member Type Documentation

QFileInfo::PermissionSpec

111       This enum is used by the permission() function to report the
112       permissions and ownership of a file. The values may be OR-ed together
113       to test multiple permissions and ownership values.
114
115       QFileInfo::ReadOwner - The file is readable by the owner of the file.
116
117       QFileInfo::WriteOwner - The file is writable by the owner of the file.
118
119       QFileInfo::ExeOwner - The file is executable by the owner of the file.
120
121       QFileInfo::ReadUser - The file is readable by the user.
122
123       QFileInfo::WriteUser - The file is writable by the user.
124
125       QFileInfo::ExeUser - The file is executable by the user.
126
127       QFileInfo::ReadGroup - The file is readable by the group.
128
129       QFileInfo::WriteGroup - The file is writable by the group.
130
131       QFileInfo::ExeGroup - The file is executable by the group.
132
133       QFileInfo::ReadOther - The file is readable by anyone.
134
135       QFileInfo::WriteOther - The file is writable by anyone.
136
137       QFileInfo::ExeOther - The file is executable by anyone.
138
139       Warning: The semantics of ReadUser, WriteUser and ExeUser are
140       unfortunately not platform independent: on Unix, the rights of the
141       owner of the file are returned and on Windows the rights of the current
142       user are returned. This behavior might change in a future Qt version.
143       If you want to find the rights of the owner of the file, you should use
144       the flags ReadOwner, WriteOwner and ExeOwner. If you want to find out
145       the rights of the current user, you should use isReadable(),
146       isWritable() and isExecutable().
147

MEMBER FUNCTION DOCUMENTATION

QFileInfo::QFileInfo ()

150       Constructs a new empty QFileInfo.
151

QFileInfo::QFileInfo ( const QString & file )

153       Constructs a new QFileInfo that gives information about the given file.
154       The file can also include an absolute or relative path.
155
156       Warning: Some functions might behave in a counter-intuitive way if file
157       has a trailing directory separator.
158
159       See also setFile(), isRelative(), QDir::setCurrent(), and
160       QDir::isRelativePath().
161

QFileInfo::QFileInfo ( const QFile & file )

163       Constructs a new QFileInfo that gives information about file file.
164
165       If the file has a relative path, the QFileInfo will also have a
166       relative path.
167
168       See also isRelative().
169

QFileInfo::QFileInfo ( const QDir & d, const QString & fileName )

171       Constructs a new QFileInfo that gives information about the file called
172       fileName in the directory d.
173
174       If d has a relative path, the QFileInfo will also have a relative path.
175
176       See also isRelative().
177

QFileInfo::QFileInfo ( const QFileInfo & fi )

179       Constructs a new QFileInfo that is a copy of fi.
180

QFileInfo::~QFileInfo ()

182       Destroys the QFileInfo and frees its resources.
183

QString QFileInfo::absFilePath () const

185       Returns the absolute path including the file name.
186
187       The absolute path name consists of the full path and the file name. On
188       Unix this will always begin with the root, '/', directory. On Windows
189       this will always begin 'D:/' where D is a drive letter, except for
190       network shares that are not mapped to a drive letter, in which case the
191       path will begin '//sharename/'.
192
193       This function returns the same as filePath(), unless isRelative() is
194       TRUE.
195
196       If the QFileInfo is empty it returns QDir::currentDirPath().
197
198       This function can be time consuming under Unix (in the order of
199       milliseconds).
200
201       See also isRelative() and filePath().
202
203       Examples:
204

QString QFileInfo::baseName ( bool complete = FALSE ) const

206       Returns the base name of the file.
207
208       If complete is FALSE (the default) the base name consists of all
209       characters in the file name up to (but not including) the first '.'
210       character.
211
212       If complete is TRUE the base name consists of all characters in the
213       file up to (but not including) the last '.' character.
214
215       The path is not included in either case.
216
217       Example:
218
219               QFileInfo fi( "/tmp/archive.tar.gz" );
220               QString base = fi.baseName();  // base = "archive"
221               base = fi.baseName( TRUE );    // base = "archive.tar"
222
223       See also fileName() and extension().
224

bool QFileInfo::caching () const

226       Returns TRUE if caching is enabled; otherwise returns FALSE.
227
228       See also setCaching() and refresh().
229

bool QFileInfo::convertToAbs ()

231       Converts the file's path to an absolute path.
232
233       If it is already absolute, nothing is done.
234
235       See also filePath() and isRelative().
236

QDateTime QFileInfo::created () const

238       Returns the date and time when the file was created.
239
240       On platforms where this information is not available, returns the same
241       as lastModified().
242
243       See also lastModified() and lastRead().
244

QDir QFileInfo::dir ( bool absPath = FALSE ) const

246       Returns the file's path as a QDir object.
247
248       If the QFileInfo is relative and absPath is FALSE, the QDir will be
249       relative; otherwise it will be absolute.
250
251       See also dirPath(), filePath(), fileName(), and isRelative().
252
253       Example: fileiconview/qfileiconview.cpp.
254

QString QFileInfo::dirPath ( bool absPath = FALSE ) const

256       Returns the file's path.
257
258       If absPath is TRUE an absolute path is returned.
259
260       See also dir(), filePath(), fileName(), and isRelative().
261
262       Example: fileiconview/qfileiconview.cpp.
263

bool QFileInfo::exists () const

265       Returns TRUE if the file exists; otherwise returns FALSE.
266
267       Examples:
268

QString QFileInfo::extension ( bool complete = TRUE ) const

270       Returns the file's extension name.
271
272       If complete is TRUE (the default), extension() returns the string of
273       all characters in the file name after (but not including) the first '.'
274       character.
275
276       If complete is FALSE, extension() returns the string of all characters
277       in the file name after (but not including) the last '.' character.
278
279       Example:
280
281               QFileInfo fi( "/tmp/archive.tar.gz" );
282               QString ext = fi.extension();  // ext = "tar.gz"
283               ext = fi.extension( FALSE );   // ext = "gz"
284
285       See also fileName() and baseName().
286
287       Example: qdir/qdir.cpp.
288

QString QFileInfo::fileName () const

290       Returns the name of the file, excluding the path.
291
292       Example:
293
294               QFileInfo fi( "/tmp/archive.tar.gz" );
295               QString name = fi.fileName();           // name = "archive.tar.gz"
296
297       See also isRelative(), filePath(), baseName(), and extension().
298
299       Examples:
300

QString QFileInfo::filePath () const

302       Returns the file name, including the path (which may be absolute or
303       relative).
304
305       See also isRelative() and absFilePath().
306
307       Examples:
308

QString QFileInfo::group () const

310       Returns the group of the file. On Windows, on systems where files do
311       not have groups, or if an error occurs, QString::null is returned.
312
313       This function can be time consuming under Unix (in the order of
314       milliseconds).
315
316       See also groupId(), owner(), and ownerId().
317

uint QFileInfo::groupId () const

319       Returns the id of the group the file belongs to.
320
321       On Windows and on systems where files do not have groups this function
322       always returns (uint) -2.
323
324       See also group(), owner(), and ownerId().
325

bool QFileInfo::isDir () const

327       Returns TRUE if this object points to a directory or to a symbolic link
328       to a directory; otherwise returns FALSE.
329
330       See also isFile() and isSymLink().
331
332       Examples:
333

bool QFileInfo::isExecutable () const

335       Returns TRUE if the file is executable; otherwise returns FALSE.
336
337       See also isReadable(), isWritable(), and permission().
338

bool QFileInfo::isFile () const

340       Returns TRUE if this object points to a file. Returns FALSE if the
341       object points to something which isn't a file, e.g. a directory or a
342       symlink.
343
344       See also isDir() and isSymLink().
345
346       Examples:
347

bool QFileInfo::isHidden () const

349       Returns TRUE if the file is hidden; otherwise returns FALSE.
350
351       On Unix-like operating systems, including Mac OS X, a file is hidden if
352       its name begins with ".". On Windows a file is hidden if its hidden
353       attribute is set.
354

bool QFileInfo::isReadable () const

356       Returns TRUE if the file is readable; otherwise returns FALSE.
357
358       See also isWritable(), isExecutable(), and permission().
359
360       Example: distributor/distributor.ui.h.
361

bool QFileInfo::isRelative () const

363       Returns TRUE if the file path name is relative. Returns FALSE if the
364       path is absolute (e.g. under Unix a path is absolute if it begins with
365       a "/").
366

bool QFileInfo::isSymLink () const

368       Returns TRUE if this object points to a symbolic link (or to a shortcut
369       on Windows, or an alias on Mac OS X); otherwise returns FALSE.
370
371       See also isFile(), isDir(), and readLink().
372
373       Examples:
374

bool QFileInfo::isWritable () const

376       Returns TRUE if the file is writable; otherwise returns FALSE.
377
378       See also isReadable(), isExecutable(), and permission().
379
380       Example: distributor/distributor.ui.h.
381

QDateTime QFileInfo::lastModified () const

383       Returns the date and time when the file was last modified.
384
385       See also created() and lastRead().
386
387       Example: biff/biff.cpp.
388

QDateTime QFileInfo::lastRead () const

390       Returns the date and time when the file was last read (accessed).
391
392       On platforms where this information is not available, returns the same
393       as lastModified().
394
395       See also created() and lastModified().
396
397       Example: biff/biff.cpp.
398

QFileInfo & QFileInfo::operator= ( const QFileInfo & fi )

400       Makes a copy of fi and assigns it to this QFileInfo.
401

QString QFileInfo::owner () const

403       Returns the owner of the file. On systems where files do not have
404       owners, or if an error occurs, QString::null is returned.
405
406       This function can be time consuming under Unix (in the order of
407       milliseconds).
408
409       See also ownerId(), group(), and groupId().
410

uint QFileInfo::ownerId () const

412       Returns the id of the owner of the file.
413
414       On Windows and on systems where files do not have owners this function
415       returns ((uint) -2).
416
417       See also owner(), group(), and groupId().
418

bool QFileInfo::permission ( int permissionSpec ) const

420       Tests for file permissions. The permissionSpec argument can be several
421       flags of type PermissionSpec OR-ed together to check for permission
422       combinations.
423
424       On systems where files do not have permissions this function always
425       returns TRUE.
426
427       Example:
428
429               QFileInfo fi( "/tmp/archive.tar.gz" );
430               if ( fi.permission( QFileInfo::WriteUser | QFileInfo::ReadGroup ) )
431                   qWarning( "I can change the file; my group can read the file" );
432               if ( fi.permission( QFileInfo::WriteGroup | QFileInfo::WriteOther ) )
433                   qWarning( "The group or others can change the file" );
434
435       See also isReadable(), isWritable(), and isExecutable().
436

QString QFileInfo::readLink () const

438       Returns the name a symlink (or shortcut on Windows) points to, or a
439       QString::null if the object isn't a symbolic link.
440
441       This name may not represent an existing file; it is only a string.
442       QFileInfo::exists() returns TRUE if the symlink points to an existing
443       file.
444
445       See also exists(), isSymLink(), isDir(), and isFile().
446

void QFileInfo::refresh () const

448       Refreshes the information about the file, i.e. reads in information
449       from the file system the next time a cached property is fetched.
450
451       See also setCaching().
452

void QFileInfo::setCaching ( bool enable )

454       If enable is TRUE, enables caching of file information. If enable is
455       FALSE caching is disabled.
456
457       When caching is enabled, QFileInfo reads the file information from the
458       file system the first time it's needed, but generally not later.
459
460       Caching is enabled by default.
461
462       See also refresh() and caching().
463

void QFileInfo::setFile ( const QString & file )

465       Sets the file that the QFileInfo provides information about to file.
466
467       The file can also include an absolute or relative file path. Absolute
468       paths begin with the directory separator (e.g. "/" under Unix) or a
469       drive specification (under Windows). Relative file names begin with a
470       directory name or a file name and specify a path relative to the
471       current directory.
472
473       Example:
474
475           QString absolute = "/local/bin";
476           QString relative = "local/bin";
477           QFileInfo absFile( absolute );
478           QFileInfo relFile( relative );
479           QDir::setCurrent( QDir::rootDirPath() );
480           // absFile and relFile now point to the same file
481           QDir::setCurrent( "/tmp" );
482           // absFile now points to "/local/bin",
483           // while relFile points to "/tmp/local/bin"
484
485       See also isRelative(), QDir::setCurrent(), and QDir::isRelativePath().
486
487       Example: biff/biff.cpp.
488

void QFileInfo::setFile ( const QFile & file )

490       This is an overloaded member function, provided for convenience. It
491       behaves essentially like the above function.
492
493       Sets the file that the QFileInfo provides information about to file.
494
495       If file includes a relative path, the QFileInfo will also have a
496       relative path.
497
498       See also isRelative().
499

void QFileInfo::setFile ( const QDir & d, const QString & fileName )

501       This is an overloaded member function, provided for convenience. It
502       behaves essentially like the above function.
503
504       Sets the file that the QFileInfo provides information about to fileName
505       in directory d.
506
507       If fileName includes a relative path, the QFileInfo will also have a
508       relative path.
509
510       See also isRelative().
511

uint QFileInfo::size () const

513       Returns the file size in bytes, or 0 if the file does not exist or if
514       the size is 0 or if the size cannot be fetched.
515
516       Example: qdir/qdir.cpp.
517
518

COPYRIGHT

524       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
525       license file included in the distribution for a complete license
526       statement.
527

AUTHOR

529       Generated automatically from the source code.
530

BUGS

532       If you find a bug in Qt, please report it as described in
533       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
534       help you. Thank you.
535
536       The definitive Qt documentation is provided in HTML format; it is
537       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
538       web browser. This man page is provided as a convenience for those users
539       who prefer man pages, although this format is not officially supported
540       by Trolltech.
541
542       If you find errors in this manual page, please report them to qt-
543       bugs@trolltech.com.  Please include the name of the manual page
544       (qfileinfo.3qt) and the Qt version (3.3.8).
545
546
547
548Trolltech AS                    2 February 2007                 QFileInfo(3qt)