src/filemanager/dir.c

   1 /* Directory routines
   2    Copyright (C) 1994, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
   3    2006, 2007 Free Software Foundation, Inc.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 2 of the License, or
   8    (at your option) any later version.
   9
  10    This program 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
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software
  17    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  */
  18
  19 /** \file dir.c
  20  *  \brief Source: directory routines
  21  */
  22
  23 #include <config.h>
  24
  25 #include <stdio.h>
  26 #include <stdlib.h>
  27 #include <string.h>
  28 #include <sys/stat.h>
  29
  30 #include "lib/global.h"
  31 #include "lib/tty/tty.h"
  32 #include "lib/search.h"
  33 #include "lib/vfs/vfs.h"
  34 #include "lib/fs.h"
  35 #include "lib/strutil.h"
  36 #include "lib/util.h"
  37 #include "lib/widget.h"         /* message() */
  38
  39 #include "src/setup.h"          /* panels_options */
  40
  41 #include "treestore.h"
  42 #include "dir.h"
  43 #include "layout.h"             /* rotate_dash() */
  44
  45 /*** global variables ****************************************************************************/
  46
  47 /*** file scope macro definitions ****************************************************************/
  48
  49 #define MY_ISDIR(x) (\
  50     (is_exe (x->st.st_mode) && !(S_ISDIR (x->st.st_mode) || x->f.link_to_dir) && exec_first) \
  51         ? 1 \
  52         : ( (S_ISDIR (x->st.st_mode) || x->f.link_to_dir) ? 2 : 0) )
  53
  54 /*** file scope type declarations ****************************************************************/
  55
  56 /*** file scope variables ************************************************************************/
  57
  58 /* Reverse flag */
  59 static int reverse = 1;
  60
  61 /* Are the files sorted case sensitively? */
  62 static int case_sensitive = OS_SORT_CASE_SENSITIVE_DEFAULT;
  63
  64 /* Are the exec_bit files top in list */
  65 static gboolean exec_first = TRUE;
  66
  67 static dir_list dir_copy = { 0, 0 };
  68
  69 /*** file scope functions ************************************************************************/
  70 /* --------------------------------------------------------------------------------------------- */
  71
  72 /*
  73    sort_orders_t sort_orders [SORT_TYPES_TOTAL] = {
  74    { N_("&Unsorted"),    unsorted },
  75    { N_("&Name"),        sort_name },
  76    { N_("&Extension"),   sort_ext },
  77    { N_("&Modify time"), sort_time },
  78    { N_("&Access time"), sort_atime },
  79    { N_("C&Hange time"), sort_ctime },
  80    { N_("&Size"),        sort_size },
  81    { N_("&Inode"),       sort_inode },
  82    };
  83  */
  84
  85 static inline int
  86 key_collate (const char *t1, const char *t2)
  87 {
  88     int dotdot = 0;
  89     int ret;
  90
  91     dotdot = (t1[0] == '.' ? 1 : 0) | ((t2[0] == '.' ? 1 : 0) << 1);
  92
  93     switch (dotdot)
  94     {
  95     case 0:
  96     case 3:
  97         ret = str_key_collate (t1, t2, case_sensitive) * reverse;
  98         break;
  99     case 1:
 100         ret = -1;               /* t1 < t2 */
 101         break;
 102     case 2:
 103         ret = 1;                /* t1 > t2 */
 104         break;
 105     default:
 106         ret = 0;                /* it must not happen */
 107     }
 108
 109     return ret;
 110 }
 111
 112 /* --------------------------------------------------------------------------------------------- */
 113 /** clear keys, should be call after sorting is finished */
 114
 115 static void
 116 clean_sort_keys (dir_list * list, int start, int count)
 117 {
 118     int i;
 119
 120     for (i = 0; i < count; i++)
 121     {
 122         str_release_key (list->list[i + start].sort_key, case_sensitive);
 123         list->list[i + start].sort_key = NULL;
 124         str_release_key (list->list[i + start].second_sort_key, case_sensitive);
 125         list->list[i + start].second_sort_key = NULL;
 126     }
 127 }
 128
 129 /* --------------------------------------------------------------------------------------------- */
 130 /**
 131  * If you change handle_dirent then check also handle_path.
 132  * @returns -1 = failure, 0 = don't add, 1 = add to the list
 133  */
 134
 135 static int
 136 handle_dirent (dir_list * list, const char *fltr, struct dirent *dp,
 137                struct stat *buf1, int next_free, int *link_to_dir, int *stale_link)
 138 {
 139     if (dp->d_name[0] == '.' && dp->d_name[1] == 0)
 140         return 0;
 141     if (dp->d_name[0] == '.' && dp->d_name[1] == '.' && dp->d_name[2] == 0)
 142         return 0;
 143     if (!panels_options.show_dot_files && (dp->d_name[0] == '.'))
 144         return 0;
 145     if (!panels_options.show_backups && dp->d_name[NLENGTH (dp) - 1] == '~')
 146         return 0;
 147
 148     if (mc_lstat (dp->d_name, buf1) == -1)
 149     {
 150         /*
 151          * lstat() fails - such entries should be identified by
 152          * buf1->st_mode being 0.
 153          * It happens on QNX Neutrino for /fs/cd0 if no CD is inserted.
 154          */
 155         memset (buf1, 0, sizeof (*buf1));
 156     }
 157
 158     if (S_ISDIR (buf1->st_mode))
 159         tree_store_mark_checked (dp->d_name);
 160
 161     /* A link to a file or a directory? */
 162     *link_to_dir = 0;
 163     *stale_link = 0;
 164     if (S_ISLNK (buf1->st_mode))
 165     {
 166         struct stat buf2;
 167         if (!mc_stat (dp->d_name, &buf2))
 168             *link_to_dir = S_ISDIR (buf2.st_mode) != 0;
 169         else
 170             *stale_link = 1;
 171     }
 172     if (!(S_ISDIR (buf1->st_mode) || *link_to_dir) && (fltr != NULL)
 173         && !mc_search (fltr, dp->d_name, MC_SEARCH_T_GLOB))
 174         return 0;
 175
 176     /* Need to grow the *list? */
 177     if (next_free == list->size)
 178     {
 179         list->list = g_try_realloc (list->list, sizeof (file_entry) * (list->size + RESIZE_STEPS));
 180         if (list->list == NULL)
 181             return -1;
 182         list->size += RESIZE_STEPS;
 183     }
 184     return 1;
 185 }
 186
 187 /* --------------------------------------------------------------------------------------------- */
 188 /** get info about ".." */
 189
 190 static gboolean
 191 get_dotdot_dir_stat (const char *path, struct stat *st)
 192 {
 193     gboolean ret = FALSE;
 194
 195     if ((path != NULL) && (path[0] != '\0') && (st != NULL))
 196     {
 197         char *dotdot_dir;
 198         struct stat s;
 199
 200         dotdot_dir = g_strdup_printf ("%s/../", path);
 201         canonicalize_pathname (dotdot_dir);
 202         ret = mc_stat (dotdot_dir, &s) == 0;
 203         g_free (dotdot_dir);
 204         *st = s;
 205     }
 206
 207     return ret;
 208 }
 209
 210 /* --------------------------------------------------------------------------------------------- */
 211
 212 static void
 213 alloc_dir_copy (int size)
 214 {
 215     if (dir_copy.size < size)
 216     {
 217         if (dir_copy.list)
 218         {
 219             int i;
 220             for (i = 0; i < dir_copy.size; i++)
 221                 g_free (dir_copy.list[i].fname);
 222             g_free (dir_copy.list);
 223         }
 224
 225         dir_copy.list = g_new0 (file_entry, size);
 226         dir_copy.size = size;
 227     }
 228 }
 229
 230 /* --------------------------------------------------------------------------------------------- */
 231 /*** public functions ****************************************************************************/
 232 /* --------------------------------------------------------------------------------------------- */
 233
 234 int
 235 unsorted (file_entry * a, file_entry * b)
 236 {
 237     (void) a;
 238     (void) b;
 239     return 0;
 240 }
 241
 242 /* --------------------------------------------------------------------------------------------- */
 243
 244 int
 245 sort_name (file_entry * a, file_entry * b)
 246 {
 247     int ad = MY_ISDIR (a);
 248     int bd = MY_ISDIR (b);
 249
 250     if (ad == bd || panels_options.mix_all_files)
 251     {
 252         /* create key if does not exist, key will be freed after sorting */
 253         if (a->sort_key == NULL)
 254             a->sort_key = str_create_key_for_filename (a->fname, case_sensitive);
 255         if (b->sort_key == NULL)
 256             b->sort_key = str_create_key_for_filename (b->fname, case_sensitive);
 257
 258         return key_collate (a->sort_key, b->sort_key);
 259     }
 260     return bd - ad;
 261 }
 262
 263 /* --------------------------------------------------------------------------------------------- */
 264
 265 int
 266 sort_vers (file_entry * a, file_entry * b)
 267 {
 268     int ad = MY_ISDIR (a);
 269     int bd = MY_ISDIR (b);
 270
 271     if (ad == bd || panels_options.mix_all_files)
 272     {
 273         return str_verscmp (a->fname, b->fname) * reverse;
 274     }
 275     else
 276     {
 277         return bd - ad;
 278     }
 279 }
 280
 281 /* --------------------------------------------------------------------------------------------- */
 282
 283 int
 284 sort_ext (file_entry * a, file_entry * b)
 285 {
 286     int r;
 287     int ad = MY_ISDIR (a);
 288     int bd = MY_ISDIR (b);
 289
 290     if (ad == bd || panels_options.mix_all_files)
 291     {
 292         if (a->second_sort_key == NULL)
 293             a->second_sort_key = str_create_key (extension (a->fname), case_sensitive);
 294         if (b->second_sort_key == NULL)
 295             b->second_sort_key = str_create_key (extension (b->fname), case_sensitive);
 296
 297         r = str_key_collate (a->second_sort_key, b->second_sort_key, case_sensitive);
 298         if (r)
 299             return r * reverse;
 300         else
 301             return sort_name (a, b);
 302     }
 303     else
 304         return bd - ad;
 305 }
 306
 307 /* --------------------------------------------------------------------------------------------- */
 308
 309 int
 310 sort_time (file_entry * a, file_entry * b)
 311 {
 312     int ad = MY_ISDIR (a);
 313     int bd = MY_ISDIR (b);
 314
 315     if (ad == bd || panels_options.mix_all_files)
 316     {
 317         int result = a->st.st_mtime < b->st.st_mtime ? -1 : a->st.st_mtime > b->st.st_mtime;
 318         if (result != 0)
 319             return result * reverse;
 320         else
 321             return sort_name (a, b);
 322     }
 323     else
 324         return bd - ad;
 325 }
 326
 327 /* --------------------------------------------------------------------------------------------- */
 328
 329 int
 330 sort_ctime (file_entry * a, file_entry * b)
 331 {
 332     int ad = MY_ISDIR (a);
 333     int bd = MY_ISDIR (b);
 334
 335     if (ad == bd || panels_options.mix_all_files)
 336     {
 337         int result = a->st.st_ctime < b->st.st_ctime ? -1 : a->st.st_ctime > b->st.st_ctime;
 338         if (result != 0)
 339             return result * reverse;
 340         else
 341             return sort_name (a, b);
 342     }
 343     else
 344         return bd - ad;
 345 }
 346
 347 /* --------------------------------------------------------------------------------------------- */
 348
 349 int
 350 sort_atime (file_entry * a, file_entry * b)
 351 {
 352     int ad = MY_ISDIR (a);
 353     int bd = MY_ISDIR (b);
 354
 355     if (ad == bd || panels_options.mix_all_files)
 356     {
 357         int result = a->st.st_atime < b->st.st_atime ? -1 : a->st.st_atime > b->st.st_atime;
 358         if (result != 0)
 359             return result * reverse;
 360         else
 361             return sort_name (a, b);
 362     }
 363     else
 364         return bd - ad;
 365 }
 366
 367 /* --------------------------------------------------------------------------------------------- */
 368
 369 int
 370 sort_inode (file_entry * a, file_entry * b)
 371 {
 372     int ad = MY_ISDIR (a);
 373     int bd = MY_ISDIR (b);
 374
 375     if (ad == bd || panels_options.mix_all_files)
 376         return (a->st.st_ino - b->st.st_ino) * reverse;
 377     else
 378         return bd - ad;
 379 }
 380
 381 /* --------------------------------------------------------------------------------------------- */
 382
 383 int
 384 sort_size (file_entry * a, file_entry * b)
 385 {
 386     int ad = MY_ISDIR (a);
 387     int bd = MY_ISDIR (b);
 388     int result = 0;
 389
 390     if (ad != bd && !panels_options.mix_all_files)
 391         return bd - ad;
 392
 393     result = a->st.st_size < b->st.st_size ? -1 : a->st.st_size > b->st.st_size;
 394     if (result != 0)
 395         return result * reverse;
 396     else
 397         return sort_name (a, b);
 398 }
 399
 400 /* --------------------------------------------------------------------------------------------- */
 401
 402 void
 403 do_sort (dir_list * list, sortfn * sort, int top, gboolean reverse_f, gboolean case_sensitive_f,
 404          gboolean exec_first_f)
 405 {
 406     int dot_dot_found = 0;
 407
 408     if (top == 0)
 409         return;
 410
 411     /* If there is an ".." entry the caller must take care to
 412        ensure that it occupies the first list element. */
 413     if (strcmp (list->list[0].fname, "..") == 0)
 414         dot_dot_found = 1;
 415
 416     reverse = reverse_f ? -1 : 1;
 417     case_sensitive = case_sensitive_f ? 1 : 0;
 418     exec_first = exec_first_f;
 419     qsort (&(list->list)[dot_dot_found], top + 1 - dot_dot_found, sizeof (file_entry), sort);
 420
 421     clean_sort_keys (list, dot_dot_found, top + 1 - dot_dot_found);
 422 }
 423
 424 /* --------------------------------------------------------------------------------------------- */
 425
 426 void
 427 clean_dir (dir_list * list, int count)
 428 {
 429     int i;
 430
 431     for (i = 0; i < count; i++)
 432     {
 433         g_free (list->list[i].fname);
 434         list->list[i].fname = NULL;
 435     }
 436 }
 437
 438 /* --------------------------------------------------------------------------------------------- */
 439 /** Used to set up a directory list when there is no access to a directory */
 440
 441 gboolean
 442 set_zero_dir (dir_list * list)
 443 {
 444     /* Need to grow the *list? */
 445     if (list->size == 0)
 446     {
 447         list->list = g_try_realloc (list->list, sizeof (file_entry) * (list->size + RESIZE_STEPS));
 448         if (list->list == NULL)
 449             return FALSE;
 450
 451         list->size += RESIZE_STEPS;
 452     }
 453
 454     memset (&(list->list)[0], 0, sizeof (file_entry));
 455     list->list[0].fnamelen = 2;
 456     list->list[0].fname = g_strdup ("..");
 457     list->list[0].f.link_to_dir = 0;
 458     list->list[0].f.stale_link = 0;
 459     list->list[0].f.dir_size_computed = 0;
 460     list->list[0].f.marked = 0;
 461     list->list[0].st.st_mode = 040755;
 462     return TRUE;
 463 }
 464
 465 /* --------------------------------------------------------------------------------------------- */
 466 /**
 467    handle_path is a simplified handle_dirent. The difference is that
 468    handle_path doesn't pay attention to panels_options.show_dot_files
 469    and panels_options.show_backups.
 470    Moreover handle_path can't be used with a filemask.
 471    If you change handle_path then check also handle_dirent. */
 472 /* Return values: -1 = failure, 0 = don't add, 1 = add to the list */
 473
 474 int
 475 handle_path (dir_list * list, const char *path,
 476              struct stat *buf1, int next_free, int *link_to_dir, int *stale_link)
 477 {
 478     if (path[0] == '.' && path[1] == 0)
 479         return 0;
 480     if (path[0] == '.' && path[1] == '.' && path[2] == 0)
 481         return 0;
 482     if (mc_lstat (path, buf1) == -1)
 483         return 0;
 484
 485     if (S_ISDIR (buf1->st_mode))
 486         tree_store_mark_checked (path);
 487
 488     /* A link to a file or a directory? */
 489     *link_to_dir = 0;
 490     *stale_link = 0;
 491     if (S_ISLNK (buf1->st_mode))
 492     {
 493         struct stat buf2;
 494         if (!mc_stat (path, &buf2))
 495             *link_to_dir = S_ISDIR (buf2.st_mode) != 0;
 496         else
 497             *stale_link = 1;
 498     }
 499
 500     /* Need to grow the *list? */
 501     if (next_free == list->size)
 502     {
 503         list->list = g_try_realloc (list->list, sizeof (file_entry) * (list->size + RESIZE_STEPS));
 504         if (list->list == NULL)
 505             return -1;
 506         list->size += RESIZE_STEPS;
 507     }
 508     return 1;
 509 }
 510
 511 /* --------------------------------------------------------------------------------------------- */
 512
 513 int
 514 do_load_dir (const char *path, dir_list * list, sortfn * sort, gboolean lc_reverse,
 515              gboolean lc_case_sensitive, gboolean exec_ff, const char *fltr)
 516 {
 517     DIR *dirp;
 518     struct dirent *dp;
 519     int status, link_to_dir, stale_link;
 520     int next_free = 0;
 521     struct stat st;
 522
 523     /* ".." (if any) must be the first entry in the list */
 524     if (!set_zero_dir (list))
 525         return next_free;
 526
 527     if (get_dotdot_dir_stat (path, &st))
 528         list->list[next_free].st = st;
 529     next_free++;
 530
 531     dirp = mc_opendir (path);
 532     if (!dirp)
 533     {
 534         message (D_ERROR, MSG_ERROR, _("Cannot read directory contents"));
 535         return next_free;
 536     }
 537
 538     tree_store_start_check (path);
 539
 540     /* Do not add a ".." entry to the root directory */
 541     if ((path[0] == PATH_SEP) && (path[1] == '\0'))
 542         next_free--;
 543
 544     while ((dp = mc_readdir (dirp)))
 545     {
 546         status = handle_dirent (list, fltr, dp, &st, next_free, &link_to_dir, &stale_link);
 547         if (status == 0)
 548             continue;
 549         if (status == -1)
 550         {
 551             tree_store_end_check ();
 552             mc_closedir (dirp);
 553             return next_free;
 554         }
 555         list->list[next_free].fnamelen = NLENGTH (dp);
 556         list->list[next_free].fname = g_strdup (dp->d_name);
 557         list->list[next_free].f.marked = 0;
 558         list->list[next_free].f.link_to_dir = link_to_dir;
 559         list->list[next_free].f.stale_link = stale_link;
 560         list->list[next_free].f.dir_size_computed = 0;
 561         list->list[next_free].st = st;
 562         list->list[next_free].sort_key = NULL;
 563         list->list[next_free].second_sort_key = NULL;
 564         next_free++;
 565
 566         if ((next_free & 31) == 0)
 567             rotate_dash ();
 568     }
 569
 570     if (next_free != 0)
 571         do_sort (list, sort, next_free - 1, lc_reverse, lc_case_sensitive, exec_ff);
 572
 573     mc_closedir (dirp);
 574     tree_store_end_check ();
 575     return next_free;
 576 }
 577
 578
 579 /* --------------------------------------------------------------------------------------------- */
 580
 581 gboolean
 582 if_link_is_exe (const char *full_name, const file_entry * file)
 583 {
 584     struct stat b;
 585
 586     if (S_ISLNK (file->st.st_mode) && mc_stat (full_name, &b) == 0)
 587         return is_exe (b.st_mode);
 588     return TRUE;
 589 }
 590
 591 /* --------------------------------------------------------------------------------------------- */
 592 /** If fltr is null, then it is a match */
 593
 594 int
 595 do_reload_dir (const char *path, dir_list * list, sortfn * sort, int count,
 596                gboolean lc_reverse, gboolean lc_case_sensitive, gboolean exec_ff, const char *fltr)
 597 {
 598     DIR *dirp;
 599     struct dirent *dp;
 600     int next_free = 0;
 601     int i, status, link_to_dir, stale_link;
 602     struct stat st;
 603     int marked_cnt;
 604     GHashTable *marked_files;
 605
 606     dirp = mc_opendir (path);
 607     if (!dirp)
 608     {
 609         message (D_ERROR, MSG_ERROR, _("Cannot read directory contents"));
 610         clean_dir (list, count);
 611         return set_zero_dir (list) ? 1 : 0;
 612     }
 613
 614     tree_store_start_check (path);
 615     marked_files = g_hash_table_new (g_str_hash, g_str_equal);
 616     alloc_dir_copy (list->size);
 617     for (marked_cnt = i = 0; i < count; i++)
 618     {
 619         dir_copy.list[i].fnamelen = list->list[i].fnamelen;
 620         dir_copy.list[i].fname = list->list[i].fname;
 621         dir_copy.list[i].f.marked = list->list[i].f.marked;
 622         dir_copy.list[i].f.dir_size_computed = list->list[i].f.dir_size_computed;
 623         dir_copy.list[i].f.link_to_dir = list->list[i].f.link_to_dir;
 624         dir_copy.list[i].f.stale_link = list->list[i].f.stale_link;
 625         dir_copy.list[i].sort_key = NULL;
 626         dir_copy.list[i].second_sort_key = NULL;
 627         if (list->list[i].f.marked)
 628         {
 629             g_hash_table_insert (marked_files, dir_copy.list[i].fname, &dir_copy.list[i]);
 630             marked_cnt++;
 631         }
 632     }
 633
 634     /* Add ".." except to the root directory. The ".." entry
 635        (if any) must be the first in the list. */
 636     if (!((path[0] == PATH_SEP) && (path[1] == '\0')))
 637     {
 638         if (!set_zero_dir (list))
 639         {
 640             clean_dir (list, count);
 641             clean_dir (&dir_copy, count);
 642             return next_free;
 643         }
 644
 645         if (get_dotdot_dir_stat (path, &st))
 646             list->list[next_free].st = st;
 647
 648         next_free++;
 649     }
 650
 651     while ((dp = mc_readdir (dirp)))
 652     {
 653         status = handle_dirent (list, fltr, dp, &st, next_free, &link_to_dir, &stale_link);
 654         if (status == 0)
 655             continue;
 656         if (status == -1)
 657         {
 658             mc_closedir (dirp);
 659             /* Norbert (Feb 12, 1997):
 660                Just in case someone finds this memory leak:
 661                -1 means big trouble (at the moment no memory left),
 662                I don't bother with further cleanup because if one gets to
 663                this point he will have more problems than a few memory
 664                leaks and because one 'clean_dir' would not be enough (and
 665                because I don't want to spent the time to make it working,
 666                IMHO it's not worthwhile).
 667                clean_dir (&dir_copy, count);
 668              */
 669             tree_store_end_check ();
 670             g_hash_table_destroy (marked_files);
 671             return next_free;
 672         }
 673
 674         list->list[next_free].f.marked = 0;
 675
 676         /*
 677          * If we have marked files in the copy, scan through the copy
 678          * to find matching file.  Decrease number of remaining marks if
 679          * we copied one.
 680          */
 681         if (marked_cnt > 0)
 682         {
 683             if ((g_hash_table_lookup (marked_files, dp->d_name)))
 684             {
 685                 list->list[next_free].f.marked = 1;
 686                 marked_cnt--;
 687             }
 688         }
 689
 690         list->list[next_free].fnamelen = NLENGTH (dp);
 691         list->list[next_free].fname = g_strdup (dp->d_name);
 692         list->list[next_free].f.link_to_dir = link_to_dir;
 693         list->list[next_free].f.stale_link = stale_link;
 694         list->list[next_free].f.dir_size_computed = 0;
 695         list->list[next_free].st = st;
 696         list->list[next_free].sort_key = NULL;
 697         list->list[next_free].second_sort_key = NULL;
 698         next_free++;
 699         if (!(next_free % 16))
 700             rotate_dash ();
 701     }
 702     mc_closedir (dirp);
 703     tree_store_end_check ();
 704     g_hash_table_destroy (marked_files);
 705     if (next_free)
 706     {
 707         do_sort (list, sort, next_free - 1, lc_reverse, lc_case_sensitive, exec_ff);
 708     }
 709     clean_dir (&dir_copy, count);
 710     return next_free;
 711 }
 712
 713 /* --------------------------------------------------------------------------------------------- */