/src/wrappers/glib/library/utilities/glib_file_utilities.e
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