glib/gfileutils.c

   1 /* gfileutils.c - File utility functions
   2  *
   3  *  Copyright 2000 Red Hat, Inc.
   4  *
   5  * GLib is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU Lesser General Public License as
   7  * published by the Free Software Foundation; either version 2 of the
   8  * License, or (at your option) any later version.
   9  *
  10  * GLib is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with GLib; see the file COPYING.LIB.  If not,
  17  * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  *   Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "config.h"
  22
  23 #include "glib.h"
  24
  25 #include <sys/stat.h>
  26 #ifdef HAVE_UNISTD_H
  27 #include <unistd.h>
  28 #endif
  29 #include <stdio.h>
  30 #include <stdlib.h>
  31 #include <stdarg.h>
  32 #include <string.h>
  33 #include <errno.h>
  34 #include <sys/types.h>
  35 #include <sys/stat.h>
  36 #include <fcntl.h>
  37 #include <stdlib.h>
  38
  39 #ifdef G_OS_WIN32
  40 #include <io.h>
  41 #ifndef F_OK
  42 #define F_OK 0
  43 #define X_OK 1
  44 #define W_OK 2
  45 #define R_OK 4
  46 #endif /* !F_OK */
  47
  48 #ifndef S_ISREG
  49 #define S_ISREG(mode) ((mode)&_S_IFREG)
  50 #endif
  51
  52 #ifndef S_ISDIR
  53 #define S_ISDIR(mode) ((mode)&_S_IFDIR)
  54 #endif
  55
  56 #endif /* G_OS_WIN32 */
  57
  58 #ifndef S_ISLNK
  59 #define S_ISLNK(x) 0
  60 #endif
  61
  62 #ifndef O_BINARY
  63 #define O_BINARY 0
  64 #endif
  65
  66 #include "glibintl.h"
  67
  68 /**
  69  * g_file_test:
  70  * @filename: a filename to test
  71  * @test: bitfield of #GFileTest flags
  72  *
  73  * Returns %TRUE if any of the tests in the bitfield @test are
  74  * %TRUE. For example, <literal>(G_FILE_TEST_EXISTS |
  75  * G_FILE_TEST_IS_DIR)</literal> will return %TRUE if the file exists;
  76  * the check whether it's a directory doesn't matter since the existence
  77  * test is %TRUE. With the current set of available tests, there's no point
  78  * passing in more than one test at a time.
  79  *
  80  * Return value: whether a test was %TRUE
  81  **/
  82 gboolean
  83 g_file_test (const gchar *filename,
  84              GFileTest    test)
  85 {
  86   if (test & G_FILE_TEST_EXISTS)
  87     return (access (filename, F_OK) == 0);
  88   else if (test & G_FILE_TEST_IS_EXECUTABLE)
  89     return (access (filename, X_OK) == 0);
  90   else
  91     {
  92       struct stat s;
  93
  94       if (stat (filename, &s) < 0)
  95         return FALSE;
  96
  97       if ((test & G_FILE_TEST_IS_REGULAR) &&
  98           S_ISREG (s.st_mode))
  99         return TRUE;
 100       else if ((test & G_FILE_TEST_IS_DIR) &&
 101                S_ISDIR (s.st_mode))
 102         return TRUE;
 103       else if ((test & G_FILE_TEST_IS_SYMLINK) &&
 104                S_ISLNK (s.st_mode))
 105         return TRUE;
 106       else
 107         return FALSE;
 108     }
 109 }
 110
 111 GQuark
 112 g_file_error_quark (void)
 113 {
 114   static GQuark q = 0;
 115   if (q == 0)
 116     q = g_quark_from_static_string ("g-file-error-quark");
 117
 118   return q;
 119 }
 120
 121 /**
 122  * g_file_error_from_errno:
 123  * @err_no: an "errno" value
 124  *
 125  * Gets a #GFileError constant based on the passed-in @errno.
 126  * For example, if you pass in %EEXIST this function returns
 127  * #G_FILE_ERROR_EXIST. Unlike @errno values, you can portably
 128  * assume that all #GFileError values will exist.
 129  *
 130  * Normally a #GFileError value goes into a #GError returned
 131  * from a function that manipulates files. So you would use
 132  * g_file_error_from_errno() when constructing a #GError.
 133  *
 134  * Return value: #GFileError corresponding to the given @errno
 135  **/
 136 GFileError
 137 g_file_error_from_errno (gint err_no)
 138 {
 139   switch (err_no)
 140     {
 141 #ifdef EEXIST
 142     case EEXIST:
 143       return G_FILE_ERROR_EXIST;
 144       break;
 145 #endif
 146
 147 #ifdef EISDIR
 148     case EISDIR:
 149       return G_FILE_ERROR_ISDIR;
 150       break;
 151 #endif
 152
 153 #ifdef EACCES
 154     case EACCES:
 155       return G_FILE_ERROR_ACCES;
 156       break;
 157 #endif
 158
 159 #ifdef ENAMETOOLONG
 160     case ENAMETOOLONG:
 161       return G_FILE_ERROR_NAMETOOLONG;
 162       break;
 163 #endif
 164
 165 #ifdef ENOENT
 166     case ENOENT:
 167       return G_FILE_ERROR_NOENT;
 168       break;
 169 #endif
 170
 171 #ifdef ENOTDIR
 172     case ENOTDIR:
 173       return G_FILE_ERROR_NOTDIR;
 174       break;
 175 #endif
 176
 177 #ifdef ENXIO
 178     case ENXIO:
 179       return G_FILE_ERROR_NXIO;
 180       break;
 181 #endif
 182
 183 #ifdef ENODEV
 184     case ENODEV:
 185       return G_FILE_ERROR_NODEV;
 186       break;
 187 #endif
 188
 189 #ifdef EROFS
 190     case EROFS:
 191       return G_FILE_ERROR_ROFS;
 192       break;
 193 #endif
 194
 195 #ifdef ETXTBSY
 196     case ETXTBSY:
 197       return G_FILE_ERROR_TXTBSY;
 198       break;
 199 #endif
 200
 201 #ifdef EFAULT
 202     case EFAULT:
 203       return G_FILE_ERROR_FAULT;
 204       break;
 205 #endif
 206
 207 #ifdef ELOOP
 208     case ELOOP:
 209       return G_FILE_ERROR_LOOP;
 210       break;
 211 #endif
 212
 213 #ifdef ENOSPC
 214     case ENOSPC:
 215       return G_FILE_ERROR_NOSPC;
 216       break;
 217 #endif
 218
 219 #ifdef ENOMEM
 220     case ENOMEM:
 221       return G_FILE_ERROR_NOMEM;
 222       break;
 223 #endif
 224
 225 #ifdef EMFILE
 226     case EMFILE:
 227       return G_FILE_ERROR_MFILE;
 228       break;
 229 #endif
 230
 231 #ifdef ENFILE
 232     case ENFILE:
 233       return G_FILE_ERROR_NFILE;
 234       break;
 235 #endif
 236
 237 #ifdef EBADF
 238     case EBADF:
 239       return G_FILE_ERROR_BADF;
 240       break;
 241 #endif
 242
 243 #ifdef EINVAL
 244     case EINVAL:
 245       return G_FILE_ERROR_INVAL;
 246       break;
 247 #endif
 248
 249 #ifdef EPIPE
 250     case EPIPE:
 251       return G_FILE_ERROR_PIPE;
 252       break;
 253 #endif
 254
 255 #ifdef EAGAIN
 256     case EAGAIN:
 257       return G_FILE_ERROR_AGAIN;
 258       break;
 259 #endif
 260
 261 #ifdef EINTR
 262     case EINTR:
 263       return G_FILE_ERROR_INTR;
 264       break;
 265 #endif
 266
 267 #ifdef EIO
 268     case EIO:
 269       return G_FILE_ERROR_IO;
 270       break;
 271 #endif
 272
 273 #ifdef EPERM
 274     case EPERM:
 275       return G_FILE_ERROR_PERM;
 276       break;
 277 #endif
 278
 279     default:
 280       return G_FILE_ERROR_FAILED;
 281       break;
 282     }
 283 }
 284
 285 static gboolean
 286 get_contents_stdio (const gchar *filename,
 287                     FILE        *f,
 288                     gchar      **contents,
 289                     gsize       *length,
 290                     GError     **error)
 291 {
 292   gchar buf[2048];
 293   size_t bytes;
 294   char *str;
 295   size_t total_bytes;
 296   size_t total_allocated;
 297
 298   g_assert (f != NULL);
 299
 300 #define STARTING_ALLOC 64
 301
 302   total_bytes = 0;
 303   total_allocated = STARTING_ALLOC;
 304   str = g_malloc (STARTING_ALLOC);
 305
 306   while (!feof (f))
 307     {
 308       bytes = fread (buf, 1, 2048, f);
 309
 310       while ((total_bytes + bytes + 1) > total_allocated)
 311         {
 312           total_allocated *= 2;
 313           str = g_try_realloc (str, total_allocated);
 314
 315           if (str == NULL)
 316             {
 317               g_set_error (error,
 318                            G_FILE_ERROR,
 319                            G_FILE_ERROR_NOMEM,
 320                            _("Could not allocate %lu bytes to read file \"%s\""),
 321                            (gulong) total_allocated, filename);
 322               goto error;
 323             }
 324         }
 325
 326       if (ferror (f))
 327         {
 328           g_set_error (error,
 329                        G_FILE_ERROR,
 330                        g_file_error_from_errno (errno),
 331                        _("Error reading file '%s': %s"),
 332                        filename, strerror (errno));
 333
 334           goto error;
 335         }
 336
 337       memcpy (str + total_bytes, buf, bytes);
 338       total_bytes += bytes;
 339     }
 340
 341   fclose (f);
 342
 343   str[total_bytes] = '\0';
 344
 345   if (length)
 346     *length = total_bytes;
 347
 348   *contents = str;
 349
 350   return TRUE;
 351
 352  error:
 353
 354   g_free (str);
 355   fclose (f);
 356
 357   return FALSE;
 358 }
 359
 360 #ifndef G_OS_WIN32
 361
 362 static gboolean
 363 get_contents_regfile (const gchar *filename,
 364                       struct stat *stat_buf,
 365                       gint         fd,
 366                       gchar      **contents,
 367                       gsize       *length,
 368                       GError     **error)
 369 {
 370   gchar *buf;
 371   size_t bytes_read;
 372   size_t size;
 373   size_t alloc_size;
 374
 375   size = stat_buf->st_size;
 376
 377   alloc_size = size + 1;
 378   buf = g_try_malloc (alloc_size);
 379
 380   if (buf == NULL)
 381     {
 382       g_set_error (error,
 383                    G_FILE_ERROR,
 384                    G_FILE_ERROR_NOMEM,
 385                    _("Could not allocate %lu bytes to read file \"%s\""),
 386                    (gulong) alloc_size, filename);
 387
 388       return FALSE;
 389     }
 390
 391   bytes_read = 0;
 392   while (bytes_read < size)
 393     {
 394       gssize rc;
 395
 396       rc = read (fd, buf + bytes_read, size - bytes_read);
 397
 398       if (rc < 0)
 399         {
 400           if (errno != EINTR)
 401             {
 402               close (fd);
 403
 404               g_free (buf);
 405
 406               g_set_error (error,
 407                            G_FILE_ERROR,
 408                            g_file_error_from_errno (errno),
 409                            _("Failed to read from file '%s': %s"),
 410                            filename, strerror (errno));
 411
 412               return FALSE;
 413             }
 414         }
 415       else if (rc == 0)
 416         break;
 417       else
 418         bytes_read += rc;
 419     }
 420
 421   buf[bytes_read] = '\0';
 422
 423   if (length)
 424     *length = bytes_read;
 425
 426   *contents = buf;
 427
 428   return TRUE;
 429 }
 430
 431 static gboolean
 432 get_contents_posix (const gchar *filename,
 433                     gchar      **contents,
 434                     gsize       *length,
 435                     GError     **error)
 436 {
 437   struct stat stat_buf;
 438   gint fd;
 439
 440   /* O_BINARY useful on Cygwin */
 441   fd = open (filename, O_RDONLY|O_BINARY);
 442
 443   if (fd < 0)
 444     {
 445       g_set_error (error,
 446                    G_FILE_ERROR,
 447                    g_file_error_from_errno (errno),
 448                    _("Failed to open file '%s': %s"),
 449                    filename, strerror (errno));
 450
 451       return FALSE;
 452     }
 453
 454   /* I don't think this will ever fail, aside from ENOMEM, but. */
 455   if (fstat (fd, &stat_buf) < 0)
 456     {
 457       close (fd);
 458
 459       g_set_error (error,
 460                    G_FILE_ERROR,
 461                    g_file_error_from_errno (errno),
 462                    _("Failed to get attributes of file '%s': fstat() failed: %s"),
 463                    filename, strerror (errno));
 464
 465       return FALSE;
 466     }
 467
 468   if (stat_buf.st_size > 0 && S_ISREG (stat_buf.st_mode))
 469     {
 470       return get_contents_regfile (filename,
 471                                    &stat_buf,
 472                                    fd,
 473                                    contents,
 474                                    length,
 475                                    error);
 476     }
 477   else
 478     {
 479       FILE *f;
 480
 481       f = fdopen (fd, "r");
 482
 483       if (f == NULL)
 484         {
 485           g_set_error (error,
 486                        G_FILE_ERROR,
 487                        g_file_error_from_errno (errno),
 488                        _("Failed to open file '%s': fdopen() failed: %s"),
 489                        filename, strerror (errno));
 490
 491           return FALSE;
 492         }
 493
 494       return get_contents_stdio (filename, f, contents, length, error);
 495     }
 496 }
 497
 498 #else  /* G_OS_WIN32 */
 499
 500 static gboolean
 501 get_contents_win32 (const gchar *filename,
 502                     gchar      **contents,
 503                     gsize       *length,
 504                     GError     **error)
 505 {
 506   FILE *f;
 507
 508   /* I guess you want binary mode; maybe you want text sometimes? */
 509   f = fopen (filename, "rb");
 510
 511   if (f == NULL)
 512     {
 513       g_set_error (error,
 514                    G_FILE_ERROR,
 515                    g_file_error_from_errno (errno),
 516                    _("Failed to open file '%s': %s"),
 517                    filename, strerror (errno));
 518
 519       return FALSE;
 520     }
 521
 522   return get_contents_stdio (filename, f, contents, length, error);
 523 }
 524
 525 #endif
 526
 527 /**
 528  * g_file_get_contents:
 529  * @filename: a file to read contents from
 530  * @contents: location to store an allocated string
 531  * @length: location to store length in bytes of the contents
 532  * @error: return location for a #GError
 533  *
 534  * Reads an entire file into allocated memory, with good error
 535  * checking. If @error is set, %FALSE is returned, and @contents is set
 536  * to %NULL. If %TRUE is returned, @error will not be set, and @contents
 537  * will be set to the file contents.  The string stored in @contents
 538  * will be nul-terminated, so for text files you can pass %NULL for the
 539  * @length argument.  The error domain is #G_FILE_ERROR. Possible
 540  * error codes are those in the #GFileError enumeration.
 541  *
 542  * FIXME currently crashes if the file is too big to fit in memory;
 543  * should probably use g_try_malloc() when we have that function.
 544  *
 545  * Return value: %TRUE on success, %FALSE if error is set
 546  **/
 547 gboolean
 548 g_file_get_contents (const gchar *filename,
 549                      gchar      **contents,
 550                      gsize       *length,
 551                      GError     **error)
 552 {
 553   g_return_val_if_fail (filename != NULL, FALSE);
 554   g_return_val_if_fail (contents != NULL, FALSE);
 555
 556   *contents = NULL;
 557   if (length)
 558     *length = 0;
 559
 560 #ifdef G_OS_WIN32
 561   return get_contents_win32 (filename, contents, length, error);
 562 #else
 563   return get_contents_posix (filename, contents, length, error);
 564 #endif
 565 }
 566
 567 /*
 568  * mkstemp() implementation is from the GNU C library.
 569  * Copyright (C) 1991,92,93,94,95,96,97,98,99 Free Software Foundation, Inc.
 570  */
 571 /**
 572  * g_mkstemp:
 573  * @tmpl: template filename
 574  *
 575  * Opens a temporary file. See the <function>mkstemp()</function> documentation
 576  * on most UNIX-like systems. This is a portability wrapper, which simply calls
 577  * <function>mkstemp()</function> on systems that have it, and implements
 578  * it in GLib otherwise.
 579  *
 580  * The parameter is a string that should match the rules for
 581  * <function>mkstemp()</function>, i.e. end in "XXXXXX". The X string will
 582  * be modified to form the name of a file that didn't exist.
 583  *
 584  * Return value: A file handle (as from <function>open()</function>) to the file
 585  * opened for reading and writing. The file is opened in binary mode
 586  * on platforms where there is a difference. The file handle should be
 587  * closed with <function>close()</function>. In case of errors, -1 is returned.
 588  */
 589 int
 590 g_mkstemp (char *tmpl)
 591 {
 592 #ifdef HAVE_MKSTEMP
 593   return mkstemp (tmpl);
 594 #else
 595   int len;
 596   char *XXXXXX;
 597   int count, fd;
 598   static const char letters[] =
 599     "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
 600   static const int NLETTERS = sizeof (letters) - 1;
 601   glong value;
 602   GTimeVal tv;
 603   static int counter = 0;
 604
 605   len = strlen (tmpl);
 606   if (len < 6 || strcmp (&tmpl[len - 6], "XXXXXX"))
 607     return -1;
 608
 609   /* This is where the Xs start.  */
 610   XXXXXX = &tmpl[len - 6];
 611
 612   /* Get some more or less random data.  */
 613   g_get_current_time (&tv);
 614   value = (tv.tv_usec ^ tv.tv_sec) + counter++;
 615
 616   for (count = 0; count < 100; value += 7777, ++count)
 617     {
 618       glong v = value;
 619
 620       /* Fill in the random bits.  */
 621       XXXXXX[0] = letters[v % NLETTERS];
 622       v /= NLETTERS;
 623       XXXXXX[1] = letters[v % NLETTERS];
 624       v /= NLETTERS;
 625       XXXXXX[2] = letters[v % NLETTERS];
 626       v /= NLETTERS;
 627       XXXXXX[3] = letters[v % NLETTERS];
 628       v /= NLETTERS;
 629       XXXXXX[4] = letters[v % NLETTERS];
 630       v /= NLETTERS;
 631       XXXXXX[5] = letters[v % NLETTERS];
 632
 633       fd = open (tmpl, O_RDWR | O_CREAT | O_EXCL | O_BINARY, 0600);
 634
 635       if (fd >= 0)
 636         return fd;
 637       else if (errno != EEXIST)
 638         /* Any other error will apply also to other names we might
 639          *  try, and there are 2^32 or so of them, so give up now.
 640          */
 641         return -1;
 642     }
 643
 644   /* We got out of the loop because we ran out of combinations to try.  */
 645   return -1;
 646 #endif
 647 }
 648
 649 /**
 650  * g_file_open_tmp:
 651  * @tmpl: Template for file name, as in g_mkstemp(), basename only
 652  * @name_used: location to store actual name used
 653  * @error: return location for a #GError
 654  *
 655  * Opens a file for writing in the preferred directory for temporary
 656  * files (as returned by g_get_tmp_dir()).
 657  *
 658  * @tmpl should be a string ending with six 'X' characters, as the
 659  * parameter to g_mkstemp() (or <function>mkstemp()</function>).
 660  * However, unlike these functions, the template should only be a
 661  * basename, no directory components are allowed. If template is %NULL,
 662  * a default template is used.
 663  *
 664  * Note that in contrast to g_mkstemp() (and <function>mkstemp()</function>)
 665  * @tmpl is not modified, and might thus be a read-only literal string.
 666  *
 667  * The actual name used is returned in @name_used if non-%NULL. This
 668  * string should be freed with g_free() when not needed any longer.
 669  *
 670  * Return value: A file handle (as from <function>open()</function>) to
 671  * the file opened for reading and writing. The file is opened in binary
 672  * mode on platforms where there is a difference. The file handle should be
 673  * closed with <function>close()</function>. In case of errors, -1 is returned
 674  * and @error will be set.
 675  **/
 676 int
 677 g_file_open_tmp (const char *tmpl,
 678                  char      **name_used,
 679                  GError    **error)
 680 {
 681   int retval;
 682   const char *tmpdir;
 683   char *sep;
 684   char *fulltemplate;
 685
 686   if (tmpl == NULL)
 687     tmpl = ".XXXXXX";
 688
 689   if (strchr (tmpl, G_DIR_SEPARATOR)
 690 #ifdef G_OS_WIN32
 691       || strchr (tmpl, '/')
 692 #endif
 693                                     )
 694     {
 695       g_set_error (error,
 696                    G_FILE_ERROR,
 697                    G_FILE_ERROR_FAILED,
 698                    _("Template '%s' invalid, should not contain a '%s'"),
 699                    tmpl, G_DIR_SEPARATOR_S);
 700
 701       return -1;
 702     }
 703
 704   if (strlen (tmpl) < 6 ||
 705       strcmp (tmpl + strlen (tmpl) - 6, "XXXXXX") != 0)
 706     {
 707       g_set_error (error,
 708                    G_FILE_ERROR,
 709                    G_FILE_ERROR_FAILED,
 710                    _("Template '%s' doesn't end with XXXXXX"),
 711                    tmpl);
 712       return -1;
 713     }
 714
 715   tmpdir = g_get_tmp_dir ();
 716
 717   if (tmpdir [strlen (tmpdir) - 1] == G_DIR_SEPARATOR)
 718     sep = "";
 719   else
 720     sep = G_DIR_SEPARATOR_S;
 721
 722   fulltemplate = g_strconcat (tmpdir, sep, tmpl, NULL);
 723
 724   retval = g_mkstemp (fulltemplate);
 725
 726   if (retval == -1)
 727     {
 728       g_set_error (error,
 729                    G_FILE_ERROR,
 730                    g_file_error_from_errno (errno),
 731                    _("Failed to create file '%s': %s"),
 732                    fulltemplate, strerror (errno));
 733       g_free (fulltemplate);
 734       return -1;
 735     }
 736
 737   if (name_used)
 738     *name_used = fulltemplate;
 739   else
 740     g_free (fulltemplate);
 741
 742   return retval;
 743 }
 744
 745 static gchar *
 746 g_build_pathv (const gchar *separator,
 747                const gchar *first_element,
 748                va_list      args)
 749 {
 750   GString *result;
 751   gint separator_len = strlen (separator);
 752   gboolean is_first = TRUE;
 753   const gchar *next_element;
 754
 755   result = g_string_new (NULL);
 756
 757   next_element = first_element;
 758
 759   while (TRUE)
 760     {
 761       const gchar *element;
 762       const gchar *start;
 763       const gchar *end;
 764
 765       if (next_element)
 766         {
 767           element = next_element;
 768           next_element = va_arg (args, gchar *);
 769         }
 770       else
 771         break;
 772
 773       start = element;
 774
 775       if (is_first)
 776         is_first = FALSE;
 777       else if (separator_len)
 778         {
 779           while (start &&
 780                  strncmp (start, separator, separator_len) == 0)
 781             start += separator_len;
 782         }
 783
 784       end = start + strlen (start);
 785
 786       if (next_element && separator_len)
 787         {
 788           while (end > start + separator_len &&
 789                  strncmp (end - separator_len, separator, separator_len) == 0)
 790             end -= separator_len;
 791         }
 792
 793       if (end > start)
 794         {
 795           if (result->len > 0)
 796             g_string_append (result, separator);
 797
 798           g_string_append_len (result, start, end - start);
 799         }
 800     }
 801
 802   return g_string_free (result, FALSE);
 803 }
 804
 805 /**
 806  * g_build_path:
 807  * @separator: a string used to separator the elements of the path.
 808  * @first_element: the first element in the path
 809  * @Varargs: remaining elements in path
 810  *
 811  * Creates a path from a series of elements using @separator as the
 812  * separator between elements. At the boundary between two elements,
 813  * any trailing occurrences of separator in the first element, or
 814  * leading occurrences of separator in the second element are removed
 815  * and exactly one copy of the separator is inserted.
 816  *
 817  * Return value: a newly-allocated string that must be freed with g_free().
 818  **/
 819 gchar *
 820 g_build_path (const gchar *separator,
 821               const gchar *first_element,
 822               ...)
 823 {
 824   gchar *str;
 825   va_list args;
 826
 827   g_return_val_if_fail (separator != NULL, NULL);
 828
 829   va_start (args, first_element);
 830   str = g_build_pathv (separator, first_element, args);
 831   va_end (args);
 832
 833   return str;
 834 }
 835
 836 /**
 837  * g_build_filename:
 838  * @first_element: the first element in the path
 839  * @Varargs: remaining elements in path
 840  *
 841  * Creates a filename from a series of elements using the correct
 842  * separator for filenames. This function behaves identically
 843  * to <literal>g_build_path (G_DIR_SEPARATOR_S, first_element, ....)</literal>.
 844  *
 845  * No attempt is made to force the resulting filename to be an absolute
 846  * path. If the first element is a relative path, the result will
 847  * be a relative path.
 848  *
 849  * Return value: a newly-allocated string that must be freed with g_free().
 850  **/
 851 gchar *
 852 g_build_filename (const gchar *first_element,
 853                   ...)
 854 {
 855   gchar *str;
 856   va_list args;
 857
 858   va_start (args, first_element);
 859   str = g_build_pathv (G_DIR_SEPARATOR_S, first_element, args);
 860   va_end (args);
 861
 862   return str;
 863 }