PageRenderTime 26ms CodeModel.GetById 13ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/utilities/glib_file_utilities.e

http://github.com/tybor/Liberty
Specman e | 895 lines | 2 code | 246 blank | 647 comment | 0 complexity | d4a8fcfb8c03b58fd3c3d4a507b39b3a MD5 | raw file
  1deferred class GLIB_FILE_UTILITIES
  2
  3--    File Utilities
  4
  5--    File Utilities -- various file-related functions.
  6
  7-- Synopsis
  8
  9
 10--  #include <glib.h>
 11--  #include <glib/gstdio.h>
 12
 13
 14--  enum        GFileError;
 15--  #define     G_FILE_ERROR
 16--  enum        GFileTest;
 17--  GFileError  g_file_error_from_errno         (gint err_no);
 18--  gboolean    g_file_get_contents             (const gchar *filename,
 19--                                               gchar **contents,
 20--                                               gsize *length,
 21--                                               GError **error);
 22--  gboolean    g_file_set_contents             (const gchar *filename,
 23--                                               const gchar *contents,
 24--                                               gssize length,
 25--                                               GError **error);
 26--  gboolean    g_file_test                     (const gchar *filename,
 27--                                               GFileTest test);
 28--  gint        g_mkstemp                       (gchar *tmpl);
 29--  gint        g_file_open_tmp                 (const gchar *tmpl,
 30--                                               gchar **name_used,
 31--                                               GError **error);
 32--  gchar*      g_file_read_link                (const gchar *filename,
 33--                                               GError **error);
 34--  int         g_mkdir_with_parents            (const gchar *pathname,
 35--                                               int mode);
 36
 37--              GDir;
 38--  GDir*       g_dir_open                      (const gchar *path,
 39--                                               guint flags,
 40--                                               GError **error);
 41--  const gchar* g_dir_read_name                (GDir *dir);
 42--  void        g_dir_rewind                    (GDir *dir);
 43--  void        g_dir_close                     (GDir *dir);
 44
 45--              GMappedFile;
 46--  GMappedFile* g_mapped_file_new              (const gchar *filename,
 47--                                               gboolean writable,
 48--                                               GError **error);
 49--  void        g_mapped_file_free              (GMappedFile *file);
 50--  gsize       g_mapped_file_get_length        (GMappedFile *file);
 51--  gchar*      g_mapped_file_get_contents      (GMappedFile *file);
 52
 53--  int         g_open                          (const gchar *filename,
 54--                                               int flags,
 55--                                               int mode);
 56--  int         g_rename                        (const gchar *oldfilename,
 57--                                               const gchar *newfilename);
 58--  int         g_mkdir                         (const gchar *filename,
 59--                                               int mode);
 60--  int         g_stat                          (const gchar *filename,
 61--                                               struct stat *buf);
 62--  int         g_lstat                         (const gchar *filename,
 63--                                               struct stat *buf);
 64--  int         g_unlink                        (const gchar *filename);
 65--  int         g_remove                        (const gchar *filename);
 66--  int         g_rmdir                         (const gchar *filename);
 67--  FILE*       g_fopen                         (const gchar *filename,
 68--                                               const gchar *mode);
 69--  FILE*       g_freopen                       (const gchar *filename,
 70--                                               const gchar *mode,
 71--                                               FILE *stream);
 72--  int         g_chmod                         (const gchar *filename,
 73--                                               int mode);
 74--  int         g_access                        (const gchar *filename,
 75--                                               int mode);
 76--  int         g_creat                         (const gchar *filename,
 77--                                               int mode);
 78--  int         g_chdir                         (const gchar *path);
 79
 80
 81-- Description
 82
 83--    There is a group of functions which wrap the common POSIX functions dealing with
 84--    filenames (g_open(), g_rename(), g_mkdir(), g_stat(), g_unlink(), g_remove(),
 85--    g_fopen(), g_freopen()). The point of these wrappers is to make it possible to
 86--    handle file names with any Unicode characters in them on Windows without having
 87--    to use ifdefs and the wide character API in the application code.
 88
 89--    The pathname argument should be in the GLib file name encoding. On POSIX this is
 90--    the actual on-disk encoding which might correspond to the locale settings of the
 91--    process (or the G_FILENAME_ENCODING environment variable), or not.
 92
 93--    On Windows the GLib file name encoding is UTF-8. Note that the Microsoft C
 94--    library does not use UTF-8, but has separate APIs for current system code page
 95--    and wide characters (UTF-16). The GLib wrappers call the wide character API if
 96--    present (on modern Windows systems), otherwise convert to/from the system code
 97--    page.
 98
 99--    Another group of functions allows to open and read directories in the GLib file
100--    name encoding. These are g_dir_open(), g_dir_read_name(), g_dir_rewind(),
101--    g_dir_close().
102
103-- Details
104
105--   enum GFileError
106
107--  typedef enum
108--  {
109--    G_FILE_ERROR_EXIST,
110--    G_FILE_ERROR_ISDIR,
111--    G_FILE_ERROR_ACCES,
112--    G_FILE_ERROR_NAMETOOLONG,
113--    G_FILE_ERROR_NOENT,
114--    G_FILE_ERROR_NOTDIR,
115--    G_FILE_ERROR_NXIO,
116--    G_FILE_ERROR_NODEV,
117--    G_FILE_ERROR_ROFS,
118--    G_FILE_ERROR_TXTBSY,
119--    G_FILE_ERROR_FAULT,
120--    G_FILE_ERROR_LOOP,
121--    G_FILE_ERROR_NOSPC,
122--    G_FILE_ERROR_NOMEM,
123--    G_FILE_ERROR_MFILE,
124--    G_FILE_ERROR_NFILE,
125--    G_FILE_ERROR_BADF,
126--    G_FILE_ERROR_INVAL,
127--    G_FILE_ERROR_PIPE,
128--    G_FILE_ERROR_AGAIN,
129--    G_FILE_ERROR_INTR,
130--    G_FILE_ERROR_IO,
131--    G_FILE_ERROR_PERM,
132--    G_FILE_ERROR_NOSYS,
133--    G_FILE_ERROR_FAILED
134--  } GFileError;
135
136--    Values corresponding to errno codes returned from file operations on UNIX. Unlike
137--    errno codes, GFileError values are available on all systems, even Windows. The
138--    exact meaning of each code depends on what sort of file operation you were
139--    performing; the UNIX documentation gives more details. The following error code
140--    descriptions come from the GNU C Library manual, and are under the copyright of
141--    that manual.
142
143--    It's not very portable to make detailed assumptions about exactly which errors
144--    will be returned from a given operation. Some errors don't occur on some systems,
145--    etc., sometimes there are subtle differences in when a system will report a given
146--    error, etc.
147
148--    G_FILE_ERROR_EXIST       Operation not permitted; only the owner of the file (or
149--                             other resource) or processes with special privileges can
150--                             perform the operation.
151--    G_FILE_ERROR_ISDIR       File is a directory; you cannot open a directory for
152--                             writing, or create or remove hard links to it.
153--    G_FILE_ERROR_ACCES       Permission denied; the file permissions do not allow the
154--                             attempted operation.
155--    G_FILE_ERROR_NAMETOOLONG Filename too long.
156--    G_FILE_ERROR_NOENT       No such file or directory. This is a "file doesn't
157--                             exist" error for ordinary files that are referenced in
158--                             contexts where they are expected to already exist.
159--    G_FILE_ERROR_NOTDIR      A file that isn't a directory was specified when a
160--                             directory is required.
161--    G_FILE_ERROR_NXIO        No such device or address. The system tried to use the
162--                             device represented by a file you specified, and it
163--                             couldn't find the device. This can mean that the device
164--                             file was installed incorrectly, or that the physical
165--                             device is missing or not correctly attached to the
166--                             computer.
167--    G_FILE_ERROR_NODEV       This file is of a type that doesn't support mapping.
168--    G_FILE_ERROR_ROFS        The directory containing the new link can't be modified
169--                             because it's on a read-only file system.
170--    G_FILE_ERROR_TXTBSY      Text file busy.
171--    G_FILE_ERROR_FAULT       You passed in a pointer to bad memory. (GLib won't
172--                             reliably return this, don't pass in pointers to bad
173--                             memory.)
174--    G_FILE_ERROR_LOOP        Too many levels of symbolic links were encountered in
175--                             looking up a file name. This often indicates a cycle of
176--                             symbolic links.
177--    G_FILE_ERROR_NOSPC       No space left on device; write operation on a file
178--                             failed because the disk is full.
179--    G_FILE_ERROR_NOMEM       No memory available. The system cannot allocate more
180--                             virtual memory because its capacity is full.
181--    G_FILE_ERROR_MFILE       The current process has too many files open and can't
182--                             open any more. Duplicate descriptors do count toward
183--                             this limit.
184--    G_FILE_ERROR_NFILE       There are too many distinct file openings in the entire
185--                             system.
186--    G_FILE_ERROR_BADF        Bad file descriptor; for example, I/O on a descriptor
187--                             that has been closed or reading from a descriptor open
188--                             only for writing (or vice versa).
189--    G_FILE_ERROR_INVAL       Invalid argument. This is used to indicate various kinds
190--                             of problems with passing the wrong argument to a library
191--                             function.
192--    G_FILE_ERROR_PIPE        Broken pipe; there is no process reading from the other
193--                             end of a pipe. Every library function that returns this
194--                             error code also generates a `SIGPIPE' signal; this
195--                             signal terminates the program if not handled or blocked.
196--                             Thus, your program will never actually see this code
197--                             unless it has handled or blocked `SIGPIPE'.
198--    G_FILE_ERROR_AGAIN       Resource temporarily unavailable; the call might work if
199--                             you try again later.
200--    G_FILE_ERROR_INTR        Interrupted function call; an asynchronous signal
201--                             occurred and prevented completion of the call. When this
202--                             happens, you should try the call again.
203--    G_FILE_ERROR_IO          Input/output error; usually used for physical read or
204--                             write errors. i.e. the disk or other physical device
205--                             hardware is returning errors.
206--    G_FILE_ERROR_PERM        Operation not permitted; only the owner of the file (or
207--                             other resource) or processes with special privileges can
208--                             perform the operation.
209--    G_FILE_ERROR_NOSYS       Function not implemented; this indicates that the system
210--                             is missing some functionality.
211--    G_FILE_ERROR_FAILED      Does not correspond to a UNIX error code; this is the
212--                             standard "failed for unspecified reason" error code
213--                             present in all GError error code enumerations. Returned
214--                             if no specific code applies.
215
216--    ---------------------------------------------------------------------------------
217
218--   G_FILE_ERROR
219
220--  #define G_FILE_ERROR g_file_error_quark ()
221
222--    Error domain for file operations. Errors in this domain will be from the
223--    GFileError enumeration. See GError for information on error domains.
224
225--    ---------------------------------------------------------------------------------
226
227--   enum GFileTest
228
229--  typedef enum
230--  {
231--    G_FILE_TEST_IS_REGULAR    = 1 < < 0,
232--    G_FILE_TEST_IS_SYMLINK    = 1 < < 1,
233--    G_FILE_TEST_IS_DIR        = 1 < < 2,
234--    G_FILE_TEST_IS_EXECUTABLE = 1 < < 3,
235--    G_FILE_TEST_EXISTS        = 1 < < 4
236--  } GFileTest;
237
238--    A test to perform on a file using g_file_test().
239
240--    G_FILE_TEST_IS_REGULAR    TRUE if the file is a regular file (not a symlink or
241--                              directory)
242--    G_FILE_TEST_IS_SYMLINK    TRUE if the file is a symlink.
243--    G_FILE_TEST_IS_DIR        TRUE if the file is a directory.
244--    G_FILE_TEST_IS_EXECUTABLE TRUE if the file is executable.
245--    G_FILE_TEST_EXISTS        TRUE if the file exists. It may or may not be a regular
246--                              file.
247
248--    ---------------------------------------------------------------------------------
249
250--   g_file_error_from_errno ()
251
252--  GFileError  g_file_error_from_errno         (gint err_no);
253
254--    Gets a GFileError constant based on the passed-in errno. For example, if you pass
255--    in EEXIST this function returns G_FILE_ERROR_EXIST. Unlike errno values, you can
256--    portably assume that all GFileError values will exist.
257
258--    Normally a GFileError value goes into a GError returned from a function that
259--    manipulates files. So you would use g_file_error_from_errno() when constructing a
260--    GError.
261
262--    err_no :  an "errno" value
263--    Returns : GFileError corresponding to the given errno
264
265--    ---------------------------------------------------------------------------------
266
267--   g_file_get_contents ()
268
269--  gboolean    g_file_get_contents             (const gchar *filename,
270--                                               gchar **contents,
271--                                               gsize *length,
272--                                               GError **error);
273
274--    Reads an entire file into allocated memory, with good error checking.
275
276--    If the call was successful, it returns TRUE and sets contents to the file
277--    contents and length to the length of the file contents in bytes. The string
278--    stored in contents will be nul-terminated, so for text files you can pass NULL
279--    for the length argument. If the call was not successful, it returns FALSE and
280--    sets error. The error domain is G_FILE_ERROR. Possible error codes are those in
281--    the GFileError enumeration. In the error case, contents is set to NULL and length
282--    is set to zero.
283
284--    filename : name of a file to read contents from, in the GLib file name encoding
285--    contents : location to store an allocated string
286--    length :   location to store length in bytes of the contents, or NULL
287--    error :    return location for a GError, or NULL
288--    Returns :  TRUE on success, FALSE if an error occurred
289
290--    ---------------------------------------------------------------------------------
291
292--   g_file_set_contents ()
293
294--  gboolean    g_file_set_contents             (const gchar *filename,
295--                                               const gchar *contents,
296--                                               gssize length,
297--                                               GError **error);
298
299--    Writes all of contents to a file named filename, with good error checking. If a
300--    file called filename already exists it will be overwritten.
301
302--    This write is atomic in the sense that it is first written to a temporary file
303--    which is then renamed to the final name. Notes:
304
305--      o On Unix, if filename already exists hard links to filename will break. Also
306--        since the file is recreated, existing permissions, access control lists,
307--        metadata etc. may be lost. If filename is a symbolic link, the link itself
308--        will be replaced, not the linked file.
309--      o On Windows renaming a file will not remove an existing file with the new
310--        name, so on Windows there is a race condition between the existing file being
311--        removed and the temporary file being renamed.
312--      o On Windows there is no way to remove a file that is open to some process, or
313--        mapped into memory. Thus, this function will fail if filename already exists
314--        and is open.
315
316--    If the call was sucessful, it returns TRUE. If the call was not successful, it
317--    returns FALSE and sets error. The error domain is G_FILE_ERROR. Possible error
318--    codes are those in the GFileError enumeration.
319
320--    filename : name of a file to write contents to, in the GLib file name encoding
321--    contents : string to write to the file
322--    length :   length of contents, or -1 if contents is a nul-terminated string
323--    error :    return location for a GError, or NULL
324--    Returns :  TRUE on success, FALSE if an error occurred
325
326--    Since 2.8
327
328--    ---------------------------------------------------------------------------------
329
330--   g_file_test ()
331
332--  gboolean    g_file_test                     (const gchar *filename,
333--                                               GFileTest test);
334
335--    Returns TRUE if any of the tests in the bitfield test are TRUE. For example,
336--    (G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR) will return TRUE if the file exists;
337--    the check whether it's a directory doesn't matter since the existence test is
338--    TRUE. With the current set of available tests, there's no point passing in more
339--    than one test at a time.
340
341--    Apart from G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, so for a
342--    symbolic link to a regular file g_file_test() will return TRUE for both
343--    G_FILE_TEST_IS_SYMLINK and G_FILE_TEST_IS_REGULAR.
344
345--    Note, that for a dangling symbolic link g_file_test() will return TRUE for
346--    G_FILE_TEST_IS_SYMLINK and FALSE for all other flags.
347
348--    You should never use g_file_test() to test whether it is safe to perform an
349--    operation, because there is always the possibility of the condition changing
350--    before you actually perform the operation. For example, you might think you could
351--    use G_FILE_TEST_IS_SYMLINK to know whether it is is safe to write to a file
352--    without being tricked into writing into a different location. It doesn't work!
353
354--  /* DON'T DO THIS */
355--   if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) {
356--     fd = g_open (filename, O_WRONLY);
357--     /* write to fd */
358--   }
359
360--    Another thing to note is that G_FILE_TEST_EXISTS and G_FILE_TEST_IS_EXECUTABLE
361--    are implemented using the access() system call. This usually doesn't matter, but
362--    if your program is setuid or setgid it means that these tests will give you the
363--    answer for the real user ID and group ID, rather than the effective user ID and
364--    group ID.
365
366--    On Windows, there are no symlinks, so testing for G_FILE_TEST_IS_SYMLINK will
367--    always return FALSE. Testing for G_FILE_TEST_IS_EXECUTABLE will just check that
368--    the file exists and its name indicates that it is executable, checking for
369--    well-known extensions and those listed in the PATHEXT environment variable.
370
371--    filename : a filename to test in the GLib file name encoding
372--    test :     bitfield of GFileTest flags
373--    Returns :  whether a test was TRUE
374
375--    ---------------------------------------------------------------------------------
376
377--   g_mkstemp ()
378
379--  gint        g_mkstemp                       (gchar *tmpl);
380
381--    Opens a temporary file. See the mkstemp() documentation on most UNIX-like
382--    systems.
383
384--    The parameter is a string that should follow the rules for mkstemp() templates,
385--    i.e. contain the string "XXXXXX". g_mkstemp() is slightly more flexible than
386--    mkstemp() in that the sequence does not have to occur at the very end of the
387--    template. The X string will be modified to form the name of a file that didn't
388--    exist. The string should be in the GLib file name encoding. Most importantly, on
389--    Windows it should be in UTF-8.
390
391--    tmpl :    template filename
392--    Returns : A file handle (as from open()) to the file opened for reading and
393--              writing. The file is opened in binary mode on platforms where there is
394--              a difference. The file handle should be closed with close(). In case of
395--              errors, -1 is returned.
396
397--    ---------------------------------------------------------------------------------
398
399--   g_file_open_tmp ()
400
401--  gint        g_file_open_tmp                 (const gchar *tmpl,
402--                                               gchar **name_used,
403--                                               GError **error);
404
405--    Opens a file for writing in the preferred directory for temporary files (as
406--    returned by g_get_tmp_dir()).
407
408--    tmpl should be a string in the GLib file name encoding containing a sequence of
409--    six 'X' characters, as the parameter to g_mkstemp(). However, unlike these
410--    functions, the template should only be a basename, no directory components are
411--    allowed. If template is NULL, a default template is used.
412
413--    Note that in contrast to g_mkstemp() (and mkstemp()) tmpl is not modified, and
414--    might thus be a read-only literal string.
415
416--    The actual name used is returned in name_used if non-NULL. This string should be
417--    freed with g_free() when not needed any longer. The returned name is in the GLib
418--    file name encoding.
419
420--    tmpl :      Template for file name, as in g_mkstemp(), basename only, or NULL, to
421--                a default template
422--    name_used : location to store actual name used
423--    error :     return location for a GError
424--    Returns :   A file handle (as from open()) to the file opened for reading and
425--                writing. The file is opened in binary mode on platforms where there
426--                is a difference. The file handle should be closed with close(). In
427--                case of errors, -1 is returned and error will be set.
428
429--    ---------------------------------------------------------------------------------
430
431--   g_file_read_link ()
432
433--  gchar*      g_file_read_link                (const gchar *filename,
434--                                               GError **error);
435
436--    Reads the contents of the symbolic link filename like the POSIX readlink()
437--    function. The returned string is in the encoding used for filenames. Use
438--    g_filename_to_utf8() to convert it to UTF-8.
439
440--    filename : the symbolic link
441--    error :    return location for a GError
442--    Returns :  A newly allocated string with the contents of the symbolic link, or
443--               NULL if an error occurred.
444
445--    Since 2.4
446
447--    ---------------------------------------------------------------------------------
448
449--   g_mkdir_with_parents ()
450
451--  int         g_mkdir_with_parents            (const gchar *pathname,
452--                                               int mode);
453
454--    Create a directory if it doesn't already exist. Create intermediate parent
455--    directories as needed, too.
456
457--    pathname : a pathname in the GLib file name encoding
458--    mode :     permissions to use for newly created directories
459--    Returns :  0 if the directory already exists, or was successfully created.
460--               Returns -1 if an error occurred, with errno set.
461
462--    Since 2.8
463
464--    ---------------------------------------------------------------------------------
465
466--   GDir
467
468--  typedef struct _GDir GDir;
469
470--    An opaque structure representing an opened directory.
471
472--    ---------------------------------------------------------------------------------
473
474--   g_dir_open ()
475
476--  GDir*       g_dir_open                      (const gchar *path,
477--                                               guint flags,
478--                                               GError **error);
479
480--    Opens a directory for reading. The names of the files in the directory can then
481--    be retrieved using g_dir_read_name().
482
483--    path :    the path to the directory you are interested in. On Unix in the on-disk
484--              encoding. On Windows in UTF-8
485--    flags :   Currently must be set to 0. Reserved for future use.
486--    error :   return location for a GError, or NULL. If non-NULL, an error will be
487--              set if and only if g_dir_open() fails.
488--    Returns : a newly allocated GDir on success, NULL on failure. If non-NULL, you
489--              must free the result with g_dir_close() when you are finished with it.
490
491--    ---------------------------------------------------------------------------------
492
493--   g_dir_read_name ()
494
495--  const gchar* g_dir_read_name                (GDir *dir);
496
497--    Retrieves the name of the next entry in the directory. The '.' and '..' entries
498--    are omitted. On Windows, the returned name is in UTF-8. On Unix, it is in the
499--    on-disk encoding.
500
501--    dir :     a GDir* created by g_dir_open()
502--    Returns : The entry's name or NULL if there are no more entries. The return value
503--              is owned by GLib and must not be modified or freed.
504
505--    ---------------------------------------------------------------------------------
506
507--   g_dir_rewind ()
508
509--  void        g_dir_rewind                    (GDir *dir);
510
511--    Resets the given directory. The next call to g_dir_read_name() will return the
512--    first entry again.
513
514--    dir : a GDir* created by g_dir_open()
515
516--    ---------------------------------------------------------------------------------
517
518--   g_dir_close ()
519
520--  void        g_dir_close                     (GDir *dir);
521
522--    Closes the directory and deallocates all related resources.
523
524--    dir : a GDir* created by g_dir_open()
525
526--    ---------------------------------------------------------------------------------
527
528--   GMappedFile
529
530--  typedef struct _GMappedFile GMappedFile;
531
532--    The GMappedFile represents a file mapping created with g_mapped_file_new(). It
533--    has only private members and should not be accessed directly.
534
535--    ---------------------------------------------------------------------------------
536
537--   g_mapped_file_new ()
538
539--  GMappedFile* g_mapped_file_new              (const gchar *filename,
540--                                               gboolean writable,
541--                                               GError **error);
542
543--    Maps a file into memory. On UNIX, this is using the mmap() function.
544
545--    If writable is TRUE, the mapped buffer may be modified, otherwise it is an error
546--    to modify the mapped buffer. Modifications to the buffer are not visible to other
547--    processes mapping the same file, and are not written back to the file.
548
549--    Note that modifications of the underlying file might affect the contents of the
550--    GMappedFile. Therefore, mapping should only be used if the file will not be
551--    modified, or if all modifications of the file are done atomically (e.g. using
552--    g_file_set_contents()).
553
554--    filename : The path of the file to load, in the GLib filename encoding
555--    writable : wether the mapping should be writable
556--    error :    return location for a GError, or NULL
557--    Returns :  a newly allocated GMappedFile which must be freed with
558--               g_mapped_file_free(), or NULL if the mapping failed.
559
560--    Since 2.8
561
562--    ---------------------------------------------------------------------------------
563
564--   g_mapped_file_free ()
565
566--  void        g_mapped_file_free              (GMappedFile *file);
567
568--    Unmaps the buffer of file and frees it.
569
570--    file : a GMappedFile
571
572--    Since 2.8
573
574--    ---------------------------------------------------------------------------------
575
576--   g_mapped_file_get_length ()
577
578--  gsize       g_mapped_file_get_length        (GMappedFile *file);
579
580--    Returns the length of the contents of a GMappedFile.
581
582--    file :    a GMappedFile
583--    Returns : the length of the contents of file.
584
585--    Since 2.8
586
587--    ---------------------------------------------------------------------------------
588
589--   g_mapped_file_get_contents ()
590
591--  gchar*      g_mapped_file_get_contents      (GMappedFile *file);
592
593--    Returns the contents of a GMappedFile.
594
595--    Note that the contents may not be zero-terminated, even if the GMappedFile is
596--    backed by a text file.
597
598--    file :    a GMappedFile
599--    Returns : the contents of file.
600
601--    Since 2.8
602
603--    ---------------------------------------------------------------------------------
604
605--   g_open ()
606
607--  int         g_open                          (const gchar *filename,
608--                                               int flags,
609--                                               int mode);
610
611--    A wrapper for the POSIX open() function. The open() function is used to convert a
612--    pathname into a file descriptor. Note that on POSIX systems file descriptors are
613--    implemented by the operating system. On Windows, it's the C library that
614--    implements open() and file descriptors. The actual Windows API for opening files
615--    is something different.
616
617--    See the C library manual for more details about open().
618
619--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
620--    flags :    as in open()
621--    mode :     as in open()
622--    Returns :  a new file descriptor, or -1 if an error occurred. The return value
623--               can be used exactly like the return value from open().
624
625--    Since 2.6
626
627--    ---------------------------------------------------------------------------------
628
629--   g_rename ()
630
631--  int         g_rename                        (const gchar *oldfilename,
632--                                               const gchar *newfilename);
633
634--    A wrapper for the POSIX rename() function. The rename() function renames a file,
635--    moving it between directories if required.
636
637--    See your C library manual for more details about how rename() works on your
638--    system. Note in particular that on Win9x it is not possible to rename a file if a
639--    file with the new name already exists. Also it is not possible in general on
640--    Windows to rename an open file.
641
642--    oldfilename : a pathname in the GLib file name encoding (UTF-8 on Windows)
643--    newfilename : a pathname in the GLib file name encoding
644--    Returns :     0 if the renaming succeeded, -1 if an error occurred
645
646--    Since 2.6
647
648--    ---------------------------------------------------------------------------------
649
650--   g_mkdir ()
651
652--  int         g_mkdir                         (const gchar *filename,
653--                                               int mode);
654
655--    A wrapper for the POSIX mkdir() function. The mkdir() function attempts to create
656--    a directory with the given name and permissions.
657
658--    See the C library manual for more details about mkdir().
659
660--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
661--    mode :     permissions to use for the newly created directory
662--    Returns :  0 if the directory was successfully created, -1 if an error occurred
663
664--    Since 2.6
665
666--    ---------------------------------------------------------------------------------
667
668--   g_stat ()
669
670--  int         g_stat                          (const gchar *filename,
671--                                               struct stat *buf);
672
673--    A wrapper for the POSIX stat() function. The stat() function returns information
674--    about a file.
675
676--    See the C library manual for more details about stat().
677
678--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
679--    buf :      a pointer to a stat struct, which will be filled with the file
680--               information
681--    Returns :  0 if the information was successfully retrieved, -1 if an error
682--               occurred
683
684--    Since 2.6
685
686--    ---------------------------------------------------------------------------------
687
688--   g_lstat ()
689
690--  int         g_lstat                         (const gchar *filename,
691--                                               struct stat *buf);
692
693--    A wrapper for the POSIX lstat() function. The lstat() function is like stat()
694--    except that in the case of symbolic links, it returns information about the
695--    symbolic link itself and not the file that it refers to. If the system does not
696--    support symbolic links g_lstat() is identical to g_stat().
697
698--    See the C library manual for more details about lstat().
699
700--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
701--    buf :      a pointer to a stat struct, which will be filled with the file
702--               information
703--    Returns :  0 if the information was successfully retrieved, -1 if an error
704--               occurred
705
706--    Since 2.6
707
708--    ---------------------------------------------------------------------------------
709
710--   g_unlink ()
711
712--  int         g_unlink                        (const gchar *filename);
713
714--    A wrapper for the POSIX unlink() function. The unlink() function deletes a name
715--    from the filesystem. If this was the last link to the file and no processes have
716--    it opened, the diskspace occupied by the file is freed.
717
718--    See your C library manual for more details about unlink(). Note that on Windows,
719--    it is in general not possible to delete files that are open to some process, or
720--    mapped into memory.
721
722--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
723--    Returns :  0 if the name was successfully deleted, -1 if an error occurred
724
725--    Since 2.6
726
727--    ---------------------------------------------------------------------------------
728
729--   g_remove ()
730
731--  int         g_remove                        (const gchar *filename);
732
733--    A wrapper for the POSIX remove() function. The remove() function deletes a name
734--    from the filesystem.
735
736--    See your C library manual for more details about how remove() works on your
737--    system. On Unix, remove() removes also directories, as it calls unlink() for
738--    files and rmdir() for directories. On Windows, although remove() in the C library
739--    only works for files, this function tries first remove() and then if that fails
740--    rmdir(), and thus works for both files and directories. Note however, that on
741--    Windows, it is in general not possible to remove a file that is open to some
742--    process, or mapped into memory.
743
744--    If this function fails on Windows you can't infer too much from the errno value.
745--    rmdir() is tried regardless of what caused remove() to fail. Any errno value set
746--    by remove() will be overwritten by that set by rmdir().
747
748--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
749--    Returns :  0 if the file was successfully removed, -1 if an error occurred
750
751--    Since 2.6
752
753--    ---------------------------------------------------------------------------------
754
755--   g_rmdir ()
756
757--  int         g_rmdir                         (const gchar *filename);
758
759--    A wrapper for the POSIX rmdir() function. The rmdir() function deletes a
760--    directory from the filesystem.
761
762--    See your C library manual for more details about how rmdir() works on your
763--    system.
764
765--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
766--    Returns :  0 if the directory was successfully removed, -1 if an error occurred
767
768--    Since 2.6
769
770--    ---------------------------------------------------------------------------------
771
772--   g_fopen ()
773
774--  FILE*       g_fopen                         (const gchar *filename,
775--                                               const gchar *mode);
776
777--    A wrapper for the POSIX fopen() function. The fopen() function opens a file and
778--    associates a new stream with it.
779
780--    See the C library manual for more details about fopen().
781
782--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
783--    mode :     a string describing the mode in which the file should be opened
784--    Returns :  A FILE pointer if the file was successfully opened, or NULL if an
785--               error occurred
786
787--    Since 2.6
788
789--    ---------------------------------------------------------------------------------
790
791--   g_freopen ()
792
793--  FILE*       g_freopen                       (const gchar *filename,
794--                                               const gchar *mode,
795--                                               FILE *stream);
796
797--    A wrapper for the POSIX freopen() function. The freopen() function opens a file
798--    and associates it with an existing stream.
799
800--    See the C library manual for more details about freopen().
801
802--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
803--    mode :     a string describing the mode in which the file should be opened
804--    stream :   an existing stream which will be reused, or NULL
805--    Returns :  A FILE pointer if the file was successfully opened, or NULL if an
806--               error occurred.
807
808--    Since 2.6
809
810--    ---------------------------------------------------------------------------------
811
812--   g_chmod ()
813
814--  int         g_chmod                         (const gchar *filename,
815--                                               int mode);
816
817--    A wrapper for the POSIX chmod() function. The chmod() function is used to set the
818--    permissions of a file system object. Note that on Windows the file protection
819--    mechanism is not at all POSIX-like, and the underlying chmod() function in the C
820--    library just sets or clears the READONLY attribute. It does not touch any ACL.
821--    Software that needs to manage file permissions on Windows exactly should use the
822--    Win32 API.
823
824--    See the C library manual for more details about chmod().
825
826--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
827--    mode :     as in chmod()
828--    Returns :  zero if the operation succeeded, -1 on error.
829
830--    Since 2.8
831
832--    ---------------------------------------------------------------------------------
833
834--   g_access ()
835
836--  int         g_access                        (const gchar *filename,
837--                                               int mode);
838
839--    A wrapper for the POSIX access() function. This function is used to test a
840--    pathname for one or several of read, write or execute permissions, or just
841--    existence. On Windows, the underlying access() function in the C library only
842--    checks the READONLY attribute, and does not look at the ACL at all. Software that
843--    needs to handle file permissions on Windows more exactly should use the Win32
844--    API.
845
846--    See the C library manual for more details about access().
847
848--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
849--    mode :     as in access()
850--    Returns :  zero if the pathname refers to an existing file system object that has
851--               all the tested permissions, or -1 otherwise or on error.
852
853--    Since 2.8
854
855--    ---------------------------------------------------------------------------------
856
857--   g_creat ()
858
859--  int         g_creat                         (const gchar *filename,
860--                                               int mode);
861
862--    A wrapper for the POSIX creat() function. The creat() function is used to convert
863--    a pathname into a file descriptor, creating a file if necessar. Note that on
864--    POSIX systems file descriptors are implemented by the operating system. On
865--    Windows, it's the C library that implements creat() and file descriptors. The
866--    actual Windows API for opening files is something different.
867
868--    See the C library manual for more details about creat().
869
870--    filename : a pathname in the GLib file name encoding (UTF-8 on Windows)
871--    mode :     as in creat()
872--    Returns :  a new file descriptor, or -1 if an error occurred. The return value
873--               can be used exactly like the return value from creat().
874
875--    Since 2.8
876
877--    ---------------------------------------------------------------------------------
878
879--   g_chdir ()
880
881--  int         g_chdir                         (const gchar *path);
882
883--    A wrapper for the POSIX chdir() function. The function changes the current
884--    directory of the process to path.
885
886--    See your C library manual for more details about chdir().
887
888--    path :    a pathname in the GLib file name encoding (UTF-8 on Windows)
889--    Returns : 0 on success, -1 if an error occurred.
890
891--    Since 2.8
892end -- class GLIB_FILE_UTILITIES
893
894
895