2
\alias{GFileProgressCallback}
3
\alias{GFileReadMoreCallback}
4
\alias{GFileQueryInfoFlags}
5
\alias{GFileCreateFlags}
7
\alias{GFileMonitorFlags}
10
\description{File and Directory Handling}
11
\section{Methods and Functions}{
12
\code{\link{gFileNewForPath}(path)}\cr
13
\code{\link{gFileNewForUri}(uri)}\cr
14
\code{\link{gFileNewForCommandlineArg}(arg)}\cr
15
\code{\link{gFileParseName}(parse.name)}\cr
16
\code{\link{gFileDup}(object)}\cr
17
\code{\link{gFileHash}(file)}\cr
18
\code{\link{gFileEqual}(object, file2)}\cr
19
\code{\link{gFileGetBasename}(object)}\cr
20
\code{\link{gFileGetPath}(object)}\cr
21
\code{\link{gFileGetUri}(object)}\cr
22
\code{\link{gFileGetParseName}(object)}\cr
23
\code{\link{gFileGetParent}(object)}\cr
24
\code{\link{gFileGetChild}(object, name)}\cr
25
\code{\link{gFileGetChildForDisplayName}(object, display.name, .errwarn = TRUE)}\cr
26
\code{\link{gFileHasPrefix}(object, descendant)}\cr
27
\code{\link{gFileGetRelativePath}(object, descendant)}\cr
28
\code{\link{gFileResolveRelativePath}(object, relative.path)}\cr
29
\code{\link{gFileIsNative}(object)}\cr
30
\code{\link{gFileHasUriScheme}(object, uri.scheme)}\cr
31
\code{\link{gFileGetUriScheme}(object)}\cr
32
\code{\link{gFileRead}(object, cancellable = NULL, .errwarn = TRUE)}\cr
33
\code{\link{gFileReadAsync}(object, io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
34
\code{\link{gFileReadFinish}(object, res, .errwarn = TRUE)}\cr
35
\code{\link{gFileAppendTo}(object, flags = "G_FILE_CREATE_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
36
\code{\link{gFileCreate}(object, flags = "G_FILE_CREATE_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
37
\code{\link{gFileReplace}(object, etag, make.backup, flags = "G_FILE_CREATE_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
38
\code{\link{gFileAppendToAsync}(object, flags = "G_FILE_CREATE_NONE", io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
39
\code{\link{gFileAppendToFinish}(object, res, .errwarn = TRUE)}\cr
40
\code{\link{gFileCreateAsync}(object, flags = "G_FILE_CREATE_NONE", io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
41
\code{\link{gFileCreateFinish}(object, res, .errwarn = TRUE)}\cr
42
\code{\link{gFileReplaceAsync}(object, etag, make.backup, flags = "G_FILE_CREATE_NONE", io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
43
\code{\link{gFileReplaceFinish}(object, res, .errwarn = TRUE)}\cr
44
\code{\link{gFileQueryInfo}(object, attributes, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
45
\code{\link{gFileQueryInfoAsync}(object, attributes, flags = "G_FILE_QUERY_INFO_NONE", io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
46
\code{\link{gFileQueryInfoFinish}(object, res, .errwarn = TRUE)}\cr
47
\code{\link{gFileQueryExists}(object, cancellable = NULL)}\cr
48
\code{\link{gFileQueryFileType}(object, flags, cancellable = NULL)}\cr
49
\code{\link{gFileQueryFilesystemInfo}(object, attributes, cancellable = NULL, .errwarn = TRUE)}\cr
50
\code{\link{gFileQueryFilesystemInfoAsync}(object, attributes, io.priority, cancellable, callback, user.data = NULL)}\cr
51
\code{\link{gFileQueryFilesystemInfoFinish}(object, res, .errwarn = TRUE)}\cr
52
\code{\link{gFileQueryDefaultHandler}(object, cancellable = NULL, .errwarn = TRUE)}\cr
53
\code{\link{gFileFindEnclosingMount}(object, cancellable = NULL, .errwarn = TRUE)}\cr
54
\code{\link{gFileFindEnclosingMountAsync}(object, io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
55
\code{\link{gFileFindEnclosingMountFinish}(object, res, .errwarn = TRUE)}\cr
56
\code{\link{gFileEnumerateChildren}(object, attributes, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
57
\code{\link{gFileEnumerateChildrenAsync}(object, attributes, flags = "G_FILE_QUERY_INFO_NONE", io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
58
\code{\link{gFileEnumerateChildrenFinish}(object, res, .errwarn = TRUE)}\cr
59
\code{\link{gFileSetDisplayName}(object, display.name, cancellable = NULL, .errwarn = TRUE)}\cr
60
\code{\link{gFileSetDisplayNameAsync}(object, display.name, io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
61
\code{\link{gFileSetDisplayNameFinish}(object, res, .errwarn = TRUE)}\cr
62
\code{\link{gFileDelete}(object, cancellable = NULL, .errwarn = TRUE)}\cr
63
\code{\link{gFileTrash}(object, cancellable = NULL, .errwarn = TRUE)}\cr
64
\code{\link{gFileCopy}(object, destination, flags = "G_FILE_COPY_NONE", cancellable = NULL, progress.callback, progress.callback.data, .errwarn = TRUE)}\cr
65
\code{\link{gFileCopyAsync}(object, destination, flags = "G_FILE_COPY_NONE", io.priority = 0, cancellable = NULL, progress.callback, progress.callback.data, callback, user.data = NULL)}\cr
66
\code{\link{gFileCopyFinish}(object, res, .errwarn = TRUE)}\cr
67
\code{\link{gFileMove}(object, destination, flags = "G_FILE_COPY_NONE", cancellable = NULL, progress.callback, progress.callback.data, .errwarn = TRUE)}\cr
68
\code{\link{gFileMakeDirectory}(object, cancellable = NULL, .errwarn = TRUE)}\cr
69
\code{\link{gFileMakeDirectoryWithParents}(object, cancellable = NULL, .errwarn = TRUE)}\cr
70
\code{\link{gFileMakeSymbolicLink}(object, symlink.value, cancellable = NULL, .errwarn = TRUE)}\cr
71
\code{\link{gFileQuerySettableAttributes}(object, cancellable = NULL, .errwarn = TRUE)}\cr
72
\code{\link{gFileQueryWritableNamespaces}(object, cancellable = NULL, .errwarn = TRUE)}\cr
73
\code{\link{gFileSetAttribute}(object, attribute, type, value.p, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
74
\code{\link{gFileSetAttributesFromInfo}(object, info, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
75
\code{\link{gFileSetAttributesAsync}(object, info, flags = "G_FILE_QUERY_INFO_NONE", io.priority = 0, cancellable = NULL, callback, user.data = NULL)}\cr
76
\code{\link{gFileSetAttributesFinish}(object, result, .errwarn = TRUE)}\cr
77
\code{\link{gFileSetAttributeString}(object, attribute, value, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
78
\code{\link{gFileSetAttributeByteString}(object, attribute, value, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
79
\code{\link{gFileSetAttributeUint32}(object, attribute, value, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
80
\code{\link{gFileSetAttributeInt32}(object, attribute, value, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
81
\code{\link{gFileSetAttributeUint64}(object, attribute, value, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
82
\code{\link{gFileSetAttributeInt64}(object, attribute, value, flags = "G_FILE_QUERY_INFO_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
83
\code{\link{gFileMountMountable}(object, flags, mount.operation, cancellable = NULL, callback, user.data = NULL)}\cr
84
\code{\link{gFileMountMountableFinish}(object, result, .errwarn = TRUE)}\cr
85
\code{\link{gFileUnmountMountable}(object, flags = "G_MOUNT_UNMOUNT_NONE", cancellable = NULL, callback, user.data = NULL)}\cr
86
\code{\link{gFileUnmountMountableFinish}(object, result, .errwarn = TRUE)}\cr
87
\code{\link{gFileUnmountMountableWithOperation}(object, flags, mount.operation, cancellable = NULL, callback, user.data = NULL)}\cr
88
\code{\link{gFileUnmountMountableWithOperationFinish}(object, result, .errwarn = TRUE)}\cr
89
\code{\link{gFileEjectMountable}(object, flags = "G_MOUNT_UNMOUNT_NONE", cancellable = NULL, callback, user.data = NULL)}\cr
90
\code{\link{gFileEjectMountableFinish}(object, result, .errwarn = TRUE)}\cr
91
\code{\link{gFileEjectMountableWithOperation}(object, flags, mount.operation, cancellable = NULL, callback, user.data = NULL)}\cr
92
\code{\link{gFileEjectMountableWithOperationFinish}(object, result, .errwarn = TRUE)}\cr
93
\code{\link{gFileStartMountable}(object, flags, start.operation, cancellable = NULL, callback, user.data = NULL)}\cr
94
\code{\link{gFileStartMountableFinish}(object, result, .errwarn = TRUE)}\cr
95
\code{\link{gFileStopMountable}(object, flags, mount.operation, cancellable = NULL, callback, user.data = NULL)}\cr
96
\code{\link{gFileStopMountableFinish}(object, result, .errwarn = TRUE)}\cr
97
\code{\link{gFilePollMountable}(object, cancellable = NULL, callback, user.data = NULL)}\cr
98
\code{\link{gFilePollMountableFinish}(object, result, .errwarn = TRUE)}\cr
99
\code{\link{gFileMountEnclosingVolume}(object, flags, mount.operation, cancellable = NULL, callback, user.data = NULL)}\cr
100
\code{\link{gFileMountEnclosingVolumeFinish}(object, result, .errwarn = TRUE)}\cr
101
\code{\link{gFileMonitorDirectory}(object, flags = "G_FILE_MONITOR_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
102
\code{\link{gFileMonitorFile}(object, flags = "G_FILE_MONITOR_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
103
\code{\link{gFileMonitor}(object, flags = "G_FILE_MONITOR_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
104
\code{\link{gFileLoadContents}(object, cancellable = NULL, .errwarn = TRUE)}\cr
105
\code{\link{gFileLoadContentsAsync}(object, cancellable = NULL, callback, user.data = NULL)}\cr
106
\code{\link{gFileLoadContentsFinish}(object, res, .errwarn = TRUE)}\cr
107
\code{\link{gFileLoadPartialContentsFinish}(object, res, .errwarn = TRUE)}\cr
108
\code{\link{gFileReplaceContents}(object, contents, length, etag, make.backup, flags = "G_FILE_CREATE_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
109
\code{\link{gFileReplaceContentsAsync}(object, contents, length, etag, make.backup, flags = "G_FILE_CREATE_NONE", cancellable = NULL, callback, user.data = NULL)}\cr
110
\code{\link{gFileReplaceContentsFinish}(object, res, .errwarn = TRUE)}\cr
111
\code{\link{gFileCopyAttributes}(object, destination, flags = "G_FILE_COPY_NONE", cancellable = NULL, .errwarn = TRUE)}\cr
112
\code{\link{gFileCreateReadwrite}(object, flags, cancellable = NULL, .errwarn = TRUE)}\cr
113
\code{\link{gFileCreateReadwriteAsync}(object, flags, io.priority, cancellable = NULL, callback, user.data = NULL)}\cr
114
\code{\link{gFileCreateReadwriteFinish}(object, res, .errwarn = TRUE)}\cr
115
\code{\link{gFileOpenReadwrite}(object, cancellable = NULL, .errwarn = TRUE)}\cr
116
\code{\link{gFileOpenReadwriteAsync}(object, io.priority, cancellable = NULL, callback, user.data = NULL)}\cr
117
\code{\link{gFileOpenReadwriteFinish}(object, res, .errwarn = TRUE)}\cr
118
\code{\link{gFileReplaceReadwrite}(object, etag, make.backup, flags, cancellable = NULL, .errwarn = TRUE)}\cr
119
\code{\link{gFileReplaceReadwriteAsync}(object, etag, make.backup, flags, io.priority, cancellable = NULL, callback, user.data = NULL)}\cr
120
\code{\link{gFileReplaceReadwriteFinish}(object, res, .errwarn = TRUE)}\cr
121
\code{\link{gFileSupportsThreadContexts}(object)}\cr
123
\section{Hierarchy}{\preformatted{GInterface
125
\section{Detailed Description}{\code{\link{GFile}} is a high level abstraction for manipulating files on a
126
virtual file system. \code{\link{GFile}}s are lightweight, immutable
127
objects that do no I/O upon creation. It is necessary to understand that
128
\code{\link{GFile}} objects do not represent files, merely an identifier for a file. All
129
file content I/O is implemented as streaming operations (see \code{\link{GInputStream}} and
130
\code{\link{GOutputStream}}).
132
To construct a \code{\link{GFile}}, you can use:
133
\code{\link{gFileNewForPath}} if you have a path.
134
\code{\link{gFileNewForUri}} if you have a URI.
135
\code{\link{gFileNewForCommandlineArg}} for a command line argument.
136
\code{\link{gFileParseName}} from a utf8 string gotten from \code{\link{gFileGetParseName}}.
138
One way to think of a \code{\link{GFile}} is as an abstraction of a pathname. For normal
139
files the system pathname is what is stored internally, but as \code{\link{GFile}}s
140
are extensible it could also be something else that corresponds to a pathname
141
in a userspace implementation of a filesystem.
142
\code{\link{GFile}}s make up hierarchies of directories and files that correspond to the
143
files on a filesystem. You can move through the file system with \code{\link{GFile}} using
144
\code{\link{gFileGetParent}} to get an identifier for the parent directory, \code{\link{gFileGetChild}}
145
to get a child within a directory, \code{\link{gFileResolveRelativePath}} to resolve a relative
146
path between two \code{\link{GFile}}s. There can be multiple hierarchies, so you may not
147
end up at the same root if you repeatedly call \code{\link{gFileGetParent}} on two different
150
All \code{\link{GFile}}s have a basename (get with \code{\link{gFileGetBasename}}). These names
151
are byte strings that are used to identify the file on the filesystem (relative to
152
its parent directory) and there is no guarantees that they have any particular charset
153
encoding or even make any sense at all. If you want to use filenames in a user
154
interface you should use the display name that you can get by requesting the
155
\code{G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME} attribute with \code{\link{gFileQueryInfo}}.
156
This is guaranteed to be in utf8 and can be used in a user interface. But always
157
store the real basename or the \code{\link{GFile}} to use to actually access the file, because
158
there is no way to go from a display name to the actual name.
160
Using \code{\link{GFile}} as an identifier has the same weaknesses as using a path in that
161
there may be multiple aliases for the same file. For instance, hard or
162
soft links may cause two different \code{\link{GFile}}s to refer to the same file.
163
Other possible causes for aliases are: case insensitive filesystems, short
164
and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if
165
two \code{\link{GFile}}s point to the same file you can query for the
166
\code{G_FILE_ATTRIBUTE_ID_FILE} attribute. Note that \code{\link{GFile}} does some trivial
167
canonicalization of pathnames passed in, so that trivial differences in the
168
path string used at creation (duplicated slashes, slash at end of path, "."
169
or ".." path segments, etc) does not create different \code{\link{GFile}}s.
171
Many \code{\link{GFile}} operations have both synchronous and asynchronous versions
172
to suit your application. Asynchronous versions of synchronous functions
173
simply have \code{async()} appended to their function names. The asynchronous
174
I/O functions call a \code{\link{GAsyncReadyCallback}} which is then used to finalize
175
the operation, producing a GAsyncResult which is then passed to the
176
function's matching \code{finish()} operation.
178
Some \code{\link{GFile}} operations do not have synchronous analogs, as they may
179
take a very long time to finish, and blocking may leave an application
180
unusable. Notable cases include:
181
\code{\link{gFileMountMountable}} to mount a mountable file.
182
\code{\link{gFileUnmountMountableWithOperation}} to unmount a mountable file.
183
\code{\link{gFileEjectMountableWithOperation}} to eject a mountable file.
185
One notable feature of \code{\link{GFile}}s are entity tags, or "etags" for
186
short. Entity tags are somewhat like a more abstract version of the
187
traditional mtime, and can be used to quickly determine if the file has
188
been modified from the version on the file system. See the HTTP 1.1
189
specification (\url{http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html})
190
for HTTP Etag headers, which are a very similar concept.}
191
\section{Structures}{\describe{\item{\verb{GFile}}{
192
A handle to an object implementing the \verb{GFileIface} interface.
193
Generally stores a location within the file system. Handles do not
194
necessarily represent files or directories that currently exist.
197
\section{Enums and Flags}{\describe{
198
\item{\verb{GFileQueryInfoFlags}}{
199
Flags used when querying a \code{\link{GFileInfo}}.
202
\item{\verb{ne}}{No flags set.}
203
\item{\verb{follow-symlinks}}{Don't follow symlinks.}
207
\item{\verb{GFileCreateFlags}}{
208
Flags used when an operation may create a file.
211
\item{\verb{none}}{No flags set.}
212
\item{\verb{private}}{Create a file that can only be
213
accessed by the current user.}
217
\item{\verb{GFileCopyFlags}}{
218
Flags used when copying or moving files.
221
\item{\verb{none}}{No flags set.}
222
\item{\verb{overwrite}}{Overwrite any existing files}
223
\item{\verb{backup}}{Make a backup of any existing files.}
224
\item{\verb{nofollow-symlinks}}{Don't follow symlinks.}
225
\item{\verb{all-metadata}}{Copy all file metadata instead of just default set used for copy (see \code{\link{GFileInfo}}).}
226
\item{\verb{no-fallback-for-move}}{Don't use copy and delete fallback if native move not supported.}
230
\item{\verb{GFileMonitorFlags}}{
231
Flags used to set what a \code{\link{GFileMonitor}} will watch for.
234
\item{\verb{none}}{No flags set.}
235
\item{\verb{watch-mounts}}{Watch for mount events.}
240
\section{User Functions}{\describe{
241
\item{\code{GFileProgressCallback(current.num.bytes, total.num.bytes, user.data)}}{
242
When doing file operations that may take a while, such as moving
243
a file or copying a file, a progress callback is used to pass how
244
far along that operation is to the application.
247
\item{\code{current.num.bytes}}{the current number of bytes in the operation.}
248
\item{\code{total.num.bytes}}{the total number of bytes in the operation.}
249
\item{\code{user.data}}{user data passed to the callback.}
254
\item{\code{GFileReadMoreCallback(file.contents, file.size, callback.data)}}{
255
When loading the partial contents of a file with \code{gFileLoadPartialContentsAsync()},
256
it may become necessary to determine if any more data from the file should be loaded.
257
A \code{\link{GFileReadMoreCallback}} function facilitates this by returning \code{TRUE} if more data
258
should be read, or \code{FALSE} otherwise.
261
\item{\code{file.contents}}{the data as currently read.}
262
\item{\code{file.size}}{the size of the data currently read.}
263
\item{\code{callback.data}}{data passed to the callback.}
266
\emph{Returns:} [logical] \code{TRUE} if more data should be read back. \code{FALSE} otherwise.
270
\references{\url{http://library.gnome.org/devel//gio/GFile.html}}
271
\author{Derived by RGtkGen from GTK+ documentation}