Merge branch '2484_editor_get_prev_utf8_fix'
[midnight-commander.git] / lib / utilunix.c
blob5d0a207b81d8d4e0972d34478ce577c5f55591b2
1 /* Various utilities - Unix variants
2 Copyright (C) 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003,
3 2004, 2005, 2007 Free Software Foundation, Inc.
4 Written 1994, 1995, 1996 by:
5 Miguel de Icaza, Janne Kukonlehto, Dugan Porter,
6 Jakub Jelinek, Mauricio Plaza.
8 The mc_realpath routine is mostly from uClibc package, written
9 by Rick Sladkey <jrs@world.std.com>
11 This program is free software; you can redistribute it and/or modify
12 it under the terms of the GNU General Public License as published by
13 the Free Software Foundation; either version 2 of the License, or
14 (at your option) any later version.
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, write to the Free Software
23 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */
25 /** \file utilunix.c
26 * \brief Source: various utilities - Unix variant
29 #include <config.h>
31 #include <ctype.h>
32 #include <errno.h>
33 #include <limits.h>
34 #include <signal.h>
35 #include <stdarg.h>
36 #include <stdio.h>
37 #include <stdlib.h>
38 #include <string.h>
39 #include <fcntl.h>
40 #include <sys/param.h>
41 #include <sys/types.h>
42 #include <sys/stat.h>
43 #include <sys/wait.h>
44 #ifdef HAVE_SYS_IOCTL_H
45 #include <sys/ioctl.h>
46 #endif
47 #ifdef HAVE_GET_PROCESS_STATS
48 #include <sys/procstats.h>
49 #endif
50 #include <unistd.h>
51 #include <pwd.h>
52 #include <grp.h>
54 #include "lib/global.h"
55 #include "lib/vfs/mc-vfs/vfs.h" /* VFS_ENCODING_PREFIX */
56 #include "lib/strutil.h" /* str_move() */
57 #include "lib/util.h"
58 #include "lib/widget.h" /* message() */
60 #include "src/execute.h"
61 #ifdef HAVE_CHARSET
62 #include "charsets.h"
63 #endif
65 /*** global variables ****************************************************************************/
67 struct sigaction startup_handler;
69 /*** file scope macro definitions ****************************************************************/
71 #define UID_CACHE_SIZE 200
72 #define GID_CACHE_SIZE 30
74 /* Pipes are guaranteed to be able to hold at least 4096 bytes */
75 /* More than that would be unportable */
76 #define MAX_PIPE_SIZE 4096
78 /*** file scope type declarations ****************************************************************/
80 typedef struct
82 int index;
83 char *string;
84 } int_cache;
86 /*** file scope variables ************************************************************************/
88 static int_cache uid_cache[UID_CACHE_SIZE];
89 static int_cache gid_cache[GID_CACHE_SIZE];
91 static int error_pipe[2]; /* File descriptors of error pipe */
92 static int old_error; /* File descriptor of old standard error */
94 /*** file scope functions ************************************************************************/
95 /* --------------------------------------------------------------------------------------------- */
97 static char *
98 i_cache_match (int id, int_cache * cache, int size)
100 int i;
102 for (i = 0; i < size; i++)
103 if (cache[i].index == id)
104 return cache[i].string;
105 return 0;
108 /* --------------------------------------------------------------------------------------------- */
110 static void
111 i_cache_add (int id, int_cache * cache, int size, char *text, int *last)
113 g_free (cache[*last].string);
114 cache[*last].string = g_strdup (text);
115 cache[*last].index = id;
116 *last = ((*last) + 1) % size;
119 /* --------------------------------------------------------------------------------------------- */
120 /*** public functions ****************************************************************************/
121 /* --------------------------------------------------------------------------------------------- */
123 char *
124 get_owner (int uid)
126 struct passwd *pwd;
127 static char ibuf[10];
128 char *name;
129 static int uid_last;
131 name = i_cache_match (uid, uid_cache, UID_CACHE_SIZE);
132 if (name != NULL)
133 return name;
135 pwd = getpwuid (uid);
136 if (pwd != NULL)
138 i_cache_add (uid, uid_cache, UID_CACHE_SIZE, pwd->pw_name, &uid_last);
139 return pwd->pw_name;
141 else
143 g_snprintf (ibuf, sizeof (ibuf), "%d", uid);
144 return ibuf;
148 /* --------------------------------------------------------------------------------------------- */
150 char *
151 get_group (int gid)
153 struct group *grp;
154 static char gbuf[10];
155 char *name;
156 static int gid_last;
158 name = i_cache_match (gid, gid_cache, GID_CACHE_SIZE);
159 if (name != NULL)
160 return name;
162 grp = getgrgid (gid);
163 if (grp != NULL)
165 i_cache_add (gid, gid_cache, GID_CACHE_SIZE, grp->gr_name, &gid_last);
166 return grp->gr_name;
168 else
170 g_snprintf (gbuf, sizeof (gbuf), "%d", gid);
171 return gbuf;
175 /* --------------------------------------------------------------------------------------------- */
176 /* Since ncurses uses a handler that automatically refreshes the */
177 /* screen after a SIGCONT, and we don't want this behavior when */
178 /* spawning a child, we save the original handler here */
180 void
181 save_stop_handler (void)
183 sigaction (SIGTSTP, NULL, &startup_handler);
186 /* --------------------------------------------------------------------------------------------- */
189 my_system (int flags, const char *shell, const char *command)
191 struct sigaction ignore, save_intr, save_quit, save_stop;
192 pid_t pid;
193 int status = 0;
195 ignore.sa_handler = SIG_IGN;
196 sigemptyset (&ignore.sa_mask);
197 ignore.sa_flags = 0;
199 sigaction (SIGINT, &ignore, &save_intr);
200 sigaction (SIGQUIT, &ignore, &save_quit);
202 /* Restore the original SIGTSTP handler, we don't want ncurses' */
203 /* handler messing the screen after the SIGCONT */
204 sigaction (SIGTSTP, &startup_handler, &save_stop);
206 pid = fork ();
207 if (pid < 0)
209 fprintf (stderr, "\n\nfork () = -1\n");
210 status = -1;
212 else if (pid == 0)
214 signal (SIGINT, SIG_DFL);
215 signal (SIGQUIT, SIG_DFL);
216 signal (SIGTSTP, SIG_DFL);
217 signal (SIGCHLD, SIG_DFL);
219 if (flags & EXECUTE_AS_SHELL)
220 execl (shell, shell, "-c", command, (char *) NULL);
221 else
223 gchar **shell_tokens;
224 const gchar *only_cmd;
226 shell_tokens = g_strsplit (shell, " ", 2);
227 if (shell_tokens == NULL)
228 only_cmd = shell;
229 else
230 only_cmd = (*shell_tokens != NULL) ? *shell_tokens : shell;
232 execlp (only_cmd, shell, command, (char *) NULL);
235 execlp will replace current process,
236 therefore no sence in call of g_strfreev().
237 But this keeped for estetic reason :)
239 g_strfreev (shell_tokens);
243 _exit (127); /* Exec error */
245 else
247 while (TRUE)
249 if (waitpid (pid, &status, 0) > 0)
251 status = WEXITSTATUS (status);
252 break;
254 if (errno != EINTR)
256 status = -1;
257 break;
261 sigaction (SIGINT, &save_intr, NULL);
262 sigaction (SIGQUIT, &save_quit, NULL);
263 sigaction (SIGTSTP, &save_stop, NULL);
265 return status;
269 /* --------------------------------------------------------------------------------------------- */
271 * Perform tilde expansion if possible.
272 * Always return a newly allocated string, even if it's unchanged.
275 char *
276 tilde_expand (const char *directory)
278 struct passwd *passwd;
279 const char *p, *q;
280 char *name;
282 if (*directory != '~')
283 return g_strdup (directory);
285 p = directory + 1;
287 /* d = "~" or d = "~/" */
288 if (!(*p) || (*p == PATH_SEP))
290 passwd = getpwuid (geteuid ());
291 q = (*p == PATH_SEP) ? p + 1 : "";
293 else
295 q = strchr (p, PATH_SEP);
296 if (!q)
298 passwd = getpwnam (p);
300 else
302 name = g_strndup (p, q - p);
303 passwd = getpwnam (name);
304 q++;
305 g_free (name);
309 /* If we can't figure the user name, leave tilde unexpanded */
310 if (!passwd)
311 return g_strdup (directory);
313 return g_strconcat (passwd->pw_dir, PATH_SEP_STR, q, (char *) NULL);
316 /* --------------------------------------------------------------------------------------------- */
318 * Return the directory where mc should keep its temporary files.
319 * This directory is (in Bourne shell terms) "${TMPDIR=/tmp}/mc-$USER"
320 * When called the first time, the directory is created if needed.
321 * The first call should be done early, since we are using fprintf()
322 * and not message() to report possible problems.
325 const char *
326 mc_tmpdir (void)
328 static char buffer[64];
329 static const char *tmpdir;
330 const char *sys_tmp;
331 struct passwd *pwd;
332 struct stat st;
333 const char *error = NULL;
335 /* Check if already correctly initialized */
336 if (tmpdir && lstat (tmpdir, &st) == 0 && S_ISDIR (st.st_mode) &&
337 st.st_uid == getuid () && (st.st_mode & 0777) == 0700)
338 return tmpdir;
340 sys_tmp = getenv ("TMPDIR");
341 if (!sys_tmp || sys_tmp[0] != '/')
343 sys_tmp = TMPDIR_DEFAULT;
346 pwd = getpwuid (getuid ());
348 if (pwd)
349 g_snprintf (buffer, sizeof (buffer), "%s/mc-%s", sys_tmp, pwd->pw_name);
350 else
351 g_snprintf (buffer, sizeof (buffer), "%s/mc-%lu", sys_tmp, (unsigned long) getuid ());
353 canonicalize_pathname (buffer);
355 if (lstat (buffer, &st) == 0)
357 /* Sanity check for existing directory */
358 if (!S_ISDIR (st.st_mode))
359 error = _("%s is not a directory\n");
360 else if (st.st_uid != getuid ())
361 error = _("Directory %s is not owned by you\n");
362 else if (((st.st_mode & 0777) != 0700) && (chmod (buffer, 0700) != 0))
363 error = _("Cannot set correct permissions for directory %s\n");
365 else
367 /* Need to create directory */
368 if (mkdir (buffer, S_IRWXU) != 0)
370 fprintf (stderr,
371 _("Cannot create temporary directory %s: %s\n"),
372 buffer, unix_error_string (errno));
373 error = "";
377 if (error != NULL)
379 int test_fd;
380 char *test_fn, *fallback_prefix;
381 int fallback_ok = 0;
383 if (*error)
384 fprintf (stderr, error, buffer);
386 /* Test if sys_tmp is suitable for temporary files */
387 fallback_prefix = g_strdup_printf ("%s/mctest", sys_tmp);
388 test_fd = mc_mkstemps (&test_fn, fallback_prefix, NULL);
389 g_free (fallback_prefix);
390 if (test_fd != -1)
392 close (test_fd);
393 test_fd = open (test_fn, O_RDONLY);
394 if (test_fd != -1)
396 close (test_fd);
397 unlink (test_fn);
398 fallback_ok = 1;
402 if (fallback_ok)
404 fprintf (stderr, _("Temporary files will be created in %s\n"), sys_tmp);
405 g_snprintf (buffer, sizeof (buffer), "%s", sys_tmp);
406 error = NULL;
408 else
410 fprintf (stderr, _("Temporary files will not be created\n"));
411 g_snprintf (buffer, sizeof (buffer), "%s", "/dev/null/");
414 fprintf (stderr, "%s\n", _("Press any key to continue..."));
415 getc (stdin);
418 tmpdir = buffer;
420 if (!error)
421 g_setenv ("MC_TMPDIR", tmpdir, TRUE);
423 return tmpdir;
426 /* --------------------------------------------------------------------------------------------- */
428 * Creates a pipe to hold standard error for a later analysis.
429 * The pipe can hold 4096 bytes. Make sure no more is written
430 * or a deadlock might occur.
433 void
434 open_error_pipe (void)
436 if (pipe (error_pipe) < 0)
438 message (D_NORMAL, _("Warning"), _("Pipe failed"));
440 old_error = dup (2);
441 if (old_error < 0 || close (2) || dup (error_pipe[1]) != 2)
443 message (D_NORMAL, _("Warning"), _("Dup failed"));
445 close (error_pipe[0]);
446 error_pipe[0] = -1;
448 else
451 * Settng stderr in nonblocking mode as we close it earlier, than
452 * program stops. We try to read some error at program startup,
453 * but we should not block on it.
455 * TODO: make piped stdin/stderr poll()/select()able to get rid
456 * of following hack.
458 int fd_flags;
459 fd_flags = fcntl (error_pipe[0], F_GETFL, NULL);
460 if (fd_flags != -1)
462 fd_flags |= O_NONBLOCK;
463 if (fcntl (error_pipe[0], F_SETFL, fd_flags) == -1)
465 /* TODO: handle it somehow */
469 /* we never write there */
470 close (error_pipe[1]);
471 error_pipe[1] = -1;
474 /* --------------------------------------------------------------------------------------------- */
476 * Returns true if an error was displayed
477 * error: -1 - ignore errors, 0 - display warning, 1 - display error
478 * text is prepended to the error message from the pipe
482 close_error_pipe (int error, const char *text)
484 const char *title;
485 char msg[MAX_PIPE_SIZE];
486 int len = 0;
488 /* already closed */
489 if (error_pipe[0] == -1)
490 return 0;
492 if (error)
493 title = MSG_ERROR;
494 else
495 title = _("Warning");
496 if (old_error >= 0)
498 if (dup2 (old_error, 2) == -1)
500 message (error, MSG_ERROR, _("Error dup'ing old error pipe"));
501 return 1;
503 close (old_error);
504 len = read (error_pipe[0], msg, MAX_PIPE_SIZE - 1);
506 if (len >= 0)
507 msg[len] = 0;
508 close (error_pipe[0]);
509 error_pipe[0] = -1;
511 if (error < 0)
512 return 0; /* Just ignore error message */
513 if (text == NULL)
515 if (len <= 0)
516 return 0; /* Nothing to show */
518 /* Show message from pipe */
519 message (error, title, "%s", msg);
521 else
523 /* Show given text and possible message from pipe */
524 message (error, title, "%s\n%s", text, msg);
526 return 1;
529 /* --------------------------------------------------------------------------------------------- */
531 * Canonicalize path, and return a new path. Do everything in place.
532 * The new path differs from path in:
533 * Multiple `/'s are collapsed to a single `/'.
534 * Leading `./'s and trailing `/.'s are removed.
535 * Trailing `/'s are removed.
536 * Non-leading `../'s and trailing `..'s are handled by removing
537 * portions of the path.
538 * Well formed UNC paths are modified only in the local part.
541 void
542 custom_canonicalize_pathname (char *path, CANON_PATH_FLAGS flags)
544 char *p, *s;
545 int len;
546 char *lpath = path; /* path without leading UNC part */
548 /* Detect and preserve UNC paths: //server/... */
549 if ((flags & CANON_PATH_GUARDUNC) && path[0] == PATH_SEP && path[1] == PATH_SEP)
551 p = path + 2;
552 while (p[0] && p[0] != '/')
553 p++;
554 if (p[0] == '/' && p > path + 2)
555 lpath = p;
558 if (!lpath[0] || !lpath[1])
559 return;
561 if (flags & CANON_PATH_JOINSLASHES)
563 /* Collapse multiple slashes */
564 p = lpath;
565 while (*p)
567 if (p[0] == PATH_SEP && p[1] == PATH_SEP)
569 s = p + 1;
570 while (*(++s) == PATH_SEP);
571 str_move (p + 1, s);
573 p++;
577 if (flags & CANON_PATH_JOINSLASHES)
579 /* Collapse "/./" -> "/" */
580 p = lpath;
581 while (*p)
583 if (p[0] == PATH_SEP && p[1] == '.' && p[2] == PATH_SEP)
584 str_move (p, p + 2);
585 else
586 p++;
590 if (flags & CANON_PATH_REMSLASHDOTS)
592 /* Remove trailing slashes */
593 p = lpath + strlen (lpath) - 1;
594 while (p > lpath && *p == PATH_SEP)
595 *p-- = 0;
597 /* Remove leading "./" */
598 if (lpath[0] == '.' && lpath[1] == PATH_SEP)
600 if (lpath[2] == 0)
602 lpath[1] = 0;
603 return;
605 else
607 str_move (lpath, lpath + 2);
611 /* Remove trailing "/" or "/." */
612 len = strlen (lpath);
613 if (len < 2)
614 return;
615 if (lpath[len - 1] == PATH_SEP)
617 lpath[len - 1] = 0;
619 else
621 if (lpath[len - 1] == '.' && lpath[len - 2] == PATH_SEP)
623 if (len == 2)
625 lpath[1] = 0;
626 return;
628 else
630 lpath[len - 2] = 0;
636 if (flags & CANON_PATH_REMDOUBLEDOTS)
638 const size_t enc_prefix_len = strlen (VFS_ENCODING_PREFIX);
640 /* Collapse "/.." with the previous part of path */
641 p = lpath;
642 while (p[0] && p[1] && p[2])
644 if ((p[0] != PATH_SEP || p[1] != '.' || p[2] != '.') || (p[3] != PATH_SEP && p[3] != 0))
646 p++;
647 continue;
650 /* search for the previous token */
651 s = p - 1;
652 while (s >= lpath && *s != PATH_SEP)
653 s--;
655 s++;
657 /* If the previous token is "..", we cannot collapse it */
658 if (s[0] == '.' && s[1] == '.' && s + 2 == p)
660 p += 3;
661 continue;
664 if (p[3] != 0)
666 if (s == lpath && *s == PATH_SEP)
668 /* "/../foo" -> "/foo" */
669 str_move (s + 1, p + 4);
671 else
673 /* "token/../foo" -> "foo" */
674 #if HAVE_CHARSET
675 if ((strncmp (s, VFS_ENCODING_PREFIX, enc_prefix_len) == 0)
676 && (is_supported_encoding (s + enc_prefix_len)))
677 /* special case: remove encoding */
678 str_move (s, p + 1);
679 else
680 #endif /* HAVE_CHARSET */
681 str_move (s, p + 4);
683 p = (s > lpath) ? s - 1 : s;
684 continue;
687 /* trailing ".." */
688 if (s == lpath)
690 /* "token/.." -> "." */
691 if (lpath[0] != PATH_SEP)
693 lpath[0] = '.';
695 lpath[1] = 0;
697 else
699 /* "foo/token/.." -> "foo" */
700 if (s == lpath + 1)
701 s[0] = 0;
702 #if HAVE_CHARSET
703 else if ((strncmp (s, VFS_ENCODING_PREFIX, enc_prefix_len) == 0)
704 && (is_supported_encoding (s + enc_prefix_len)))
706 /* special case: remove encoding */
707 s[0] = '.';
708 s[1] = '.';
709 s[2] = '\0';
711 /* search for the previous token */
712 /* s[-1] == PATH_SEP */
713 p = s - 1;
714 while (p >= lpath && *p != PATH_SEP)
715 p--;
717 if (p != NULL)
718 continue;
720 #endif /* HAVE_CHARSET */
721 else
722 s[-1] = 0;
723 break;
726 break;
731 /* --------------------------------------------------------------------------------------------- */
733 void
734 canonicalize_pathname (char *path)
736 custom_canonicalize_pathname (path, CANON_PATH_ALL);
739 /* --------------------------------------------------------------------------------------------- */
741 #ifdef HAVE_GET_PROCESS_STATS
743 gettimeofday (struct timeval *tp, void *tzp)
745 return get_process_stats (tp, PS_SELF, 0, 0);
747 #endif /* HAVE_GET_PROCESS_STATS */
749 /* --------------------------------------------------------------------------------------------- */
751 #ifndef HAVE_REALPATH
752 char *
753 mc_realpath (const char *path, char *resolved_path)
755 char copy_path[PATH_MAX];
756 char link_path[PATH_MAX];
757 char got_path[PATH_MAX];
758 char *new_path = got_path;
759 char *max_path;
760 int readlinks = 0;
761 int n;
763 /* Make a copy of the source path since we may need to modify it. */
764 if (strlen (path) >= PATH_MAX - 2)
766 errno = ENAMETOOLONG;
767 return NULL;
769 strcpy (copy_path, path);
770 path = copy_path;
771 max_path = copy_path + PATH_MAX - 2;
772 /* If it's a relative pathname use getwd for starters. */
773 if (*path != '/')
776 new_path = g_get_current_dir ();
777 if (new_path == NULL)
779 strcpy (got_path, "");
781 else
783 g_snprintf (got_path, PATH_MAX, "%s", new_path);
784 g_free (new_path);
785 new_path = got_path;
788 new_path += strlen (got_path);
789 if (new_path[-1] != '/')
790 *new_path++ = '/';
792 else
794 *new_path++ = '/';
795 path++;
797 /* Expand each slash-separated pathname component. */
798 while (*path != '\0')
800 /* Ignore stray "/". */
801 if (*path == '/')
803 path++;
804 continue;
806 if (*path == '.')
808 /* Ignore ".". */
809 if (path[1] == '\0' || path[1] == '/')
811 path++;
812 continue;
814 if (path[1] == '.')
816 if (path[2] == '\0' || path[2] == '/')
818 path += 2;
819 /* Ignore ".." at root. */
820 if (new_path == got_path + 1)
821 continue;
822 /* Handle ".." by backing up. */
823 while ((--new_path)[-1] != '/');
824 continue;
828 /* Safely copy the next pathname component. */
829 while (*path != '\0' && *path != '/')
831 if (path > max_path)
833 errno = ENAMETOOLONG;
834 return NULL;
836 *new_path++ = *path++;
838 #ifdef S_IFLNK
839 /* Protect against infinite loops. */
840 if (readlinks++ > MAXSYMLINKS)
842 errno = ELOOP;
843 return NULL;
845 /* See if latest pathname component is a symlink. */
846 *new_path = '\0';
847 n = readlink (got_path, link_path, PATH_MAX - 1);
848 if (n < 0)
850 /* EINVAL means the file exists but isn't a symlink. */
851 if (errno != EINVAL)
853 /* Make sure it's null terminated. */
854 *new_path = '\0';
855 strcpy (resolved_path, got_path);
856 return NULL;
859 else
861 /* Note: readlink doesn't add the null byte. */
862 link_path[n] = '\0';
863 if (*link_path == '/')
864 /* Start over for an absolute symlink. */
865 new_path = got_path;
866 else
867 /* Otherwise back up over this component. */
868 while (*(--new_path) != '/');
869 /* Safe sex check. */
870 if (strlen (path) + n >= PATH_MAX - 2)
872 errno = ENAMETOOLONG;
873 return NULL;
875 /* Insert symlink contents into path. */
876 strcat (link_path, path);
877 strcpy (copy_path, link_path);
878 path = copy_path;
880 #endif /* S_IFLNK */
881 *new_path++ = '/';
883 /* Delete trailing slash but don't whomp a lone slash. */
884 if (new_path != got_path + 1 && new_path[-1] == '/')
885 new_path--;
886 /* Make sure it's null terminated. */
887 *new_path = '\0';
888 strcpy (resolved_path, got_path);
889 return resolved_path;
891 #endif /* HAVE_REALPATH */
893 /* --------------------------------------------------------------------------------------------- */
895 * Return the index of the permissions triplet
900 get_user_permissions (struct stat *st)
902 static gboolean initialized = FALSE;
903 static gid_t *groups;
904 static int ngroups;
905 static uid_t uid;
906 int i;
908 if (!initialized)
910 uid = geteuid ();
912 ngroups = getgroups (0, NULL);
913 if (ngroups == -1)
914 ngroups = 0; /* ignore errors */
916 /* allocate space for one element in addition to what
917 * will be filled by getgroups(). */
918 groups = g_new (gid_t, ngroups + 1);
920 if (ngroups != 0)
922 ngroups = getgroups (ngroups, groups);
923 if (ngroups == -1)
924 ngroups = 0; /* ignore errors */
927 /* getgroups() may or may not return the effective group ID,
928 * so we always include it at the end of the list. */
929 groups[ngroups++] = getegid ();
931 initialized = TRUE;
934 if (st->st_uid == uid || uid == 0)
935 return 0;
937 for (i = 0; i < ngroups; i++)
939 if (st->st_gid == groups[i])
940 return 1;
943 return 2;
946 /* --------------------------------------------------------------------------------------------- */