]> git.saurik.com Git - wxWidgets.git/blobdiff - src/unix/utilsunx.cpp
removed assert which could be provoked by correct code
[wxWidgets.git] / src / unix / utilsunx.cpp
index 2efc806bd1a2a9c7be983f008a78915fa4c541aa..ad8a078fabd6c6d96e2bf1a4e514748e168e4634 100644 (file)
 
 #include "wx/intl.h"
 #include "wx/log.h"
 
 #include "wx/intl.h"
 #include "wx/log.h"
+#include "wx/app.h"
 
 #include "wx/utils.h"
 #include "wx/process.h"
 #include "wx/thread.h"
 
 
 #include "wx/utils.h"
 #include "wx/process.h"
 #include "wx/thread.h"
 
-#include "wx/unix/execute.h"
+#include "wx/stream.h"
+
+#if wxUSE_GUI
+    #include "wx/unix/execute.h"
+#endif
+
+// SGI signal.h defines signal handler arguments differently depending on
+// whether _LANGUAGE_C_PLUS_PLUS is set or not - do set it
+#if defined(__SGI__) && !defined(_LANGUAGE_C_PLUS_PLUS)
+    #define _LANGUAGE_C_PLUS_PLUS 1
+#endif // SGI hack
 
 #include <stdarg.h>
 #include <dirent.h>
 
 #include <stdarg.h>
 #include <dirent.h>
@@ -124,9 +135,39 @@ void wxUsleep(unsigned long milliseconds)
 // process management
 // ----------------------------------------------------------------------------
 
 // process management
 // ----------------------------------------------------------------------------
 
-int wxKill(long pid, wxSignal sig)
+int wxKill(long pid, wxSignal sig, wxKillError *rc)
 {
 {
-    return kill((pid_t)pid, (int)sig);
+    int err = kill((pid_t)pid, (int)sig);
+    if ( rc )
+    {
+        switch ( err )
+        {
+            case 0:
+                *rc = wxKILL_OK;
+                break;
+
+            case EINVAL:
+                *rc = wxKILL_BAD_SIGNAL;
+                break;
+
+            case EPERM:
+                *rc = wxKILL_ACCESS_DENIED;
+                break;
+
+            case ESRCH:
+                *rc = wxKILL_NO_PROCESS;
+                break;
+
+            default:
+                // this goes against Unix98 docs so log it
+                wxLogDebug(_T("unexpected kill(2) return value %d"), err);
+
+                // something else...
+                *rc = wxKILL_ERROR;
+        }
+    }
+
+    return err;
 }
 
 #define WXEXECUTE_NARGS   127
 }
 
 #define WXEXECUTE_NARGS   127
@@ -201,17 +242,41 @@ long wxExecute( const wxString& command, bool sync, wxProcess *process )
     return lRc;
 }
 
     return lRc;
 }
 
-bool wxShell(const wxString& command)
+// ----------------------------------------------------------------------------
+// wxShell
+// ----------------------------------------------------------------------------
+
+static wxString wxMakeShellCommand(const wxString& command)
 {
     wxString cmd;
 {
     wxString cmd;
-    if ( !!command )
-        cmd.Printf(wxT("xterm -e %s"), command.c_str());
+    if ( !command )
+    {
+        // just an interactive shell
+        cmd = _T("xterm");
+    }
     else
     else
-        cmd = command;
+    {
+        // execute command in a shell
+        cmd << _T("/bin/sh -c '") << command << _T('\'');
+    }
+
+    return cmd;
+}
 
 
-    return wxExecute(cmd) != 0;
+bool wxShell(const wxString& command)
+{
+    return wxExecute(wxMakeShellCommand(command), TRUE /* sync */) == 0;
+}
+
+bool wxShell(const wxString& command, wxArrayString& output)
+{
+    wxCHECK_MSG( !!command, FALSE, _T("can't exec shell non interactively") );
+
+    return wxExecute(wxMakeShellCommand(command), output);
 }
 
 }
 
+#if wxUSE_GUI
+
 void wxHandleProcessTermination(wxEndProcessData *proc_data)
 {
     int pid = (proc_data->pid > 0) ? proc_data->pid : -(proc_data->pid);
 void wxHandleProcessTermination(wxEndProcessData *proc_data)
 {
     int pid = (proc_data->pid > 0) ? proc_data->pid : -(proc_data->pid);
@@ -262,9 +327,124 @@ void wxHandleProcessTermination(wxEndProcessData *proc_data)
     }
 }
 
     }
 }
 
-long wxExecute( wxChar **argv, bool sync, wxProcess *process )
+#endif // wxUSE_GUI
+
+// ----------------------------------------------------------------------------
+// wxStream classes to support IO redirection in wxExecute
+// ----------------------------------------------------------------------------
+
+#if wxUSE_STREAMS
+
+class wxProcessFileInputStream : public wxInputStream
+{
+public:
+    wxProcessFileInputStream(int fd) { m_fd = fd; }
+    ~wxProcessFileInputStream() { close(m_fd); }
+
+    virtual bool Eof() const;
+
+protected:
+    size_t OnSysRead(void *buffer, size_t bufsize);
+
+protected:
+    int m_fd;
+};
+
+class wxProcessFileOutputStream : public wxOutputStream
+{
+public:
+    wxProcessFileOutputStream(int fd) { m_fd = fd; }
+    ~wxProcessFileOutputStream() { close(m_fd); }
+
+protected:
+    size_t OnSysWrite(const void *buffer, size_t bufsize);
+
+protected:
+    int m_fd;
+};
+
+bool wxProcessFileInputStream::Eof() const
+{
+    if ( m_lasterror == wxSTREAM_EOF )
+        return TRUE;
+
+    // check if there is any input available
+    struct timeval tv;
+    tv.tv_sec = 0;
+    tv.tv_usec = 0;
+
+    fd_set readfds;
+    FD_ZERO(&readfds);
+    FD_SET(m_fd, &readfds);
+    switch ( select(m_fd + 1, &readfds, NULL, NULL, &tv) )
+    {
+        case -1:
+            wxLogSysError(_("Impossible to get child process input"));
+            // fall through
+
+        case 0:
+            return TRUE;
+
+        default:
+            wxFAIL_MSG(_T("unexpected select() return value"));
+            // still fall through
+
+        case 1:
+            // input available: check if there is any
+            return wxInputStream::Eof();
+    }
+}
+
+size_t wxProcessFileInputStream::OnSysRead(void *buffer, size_t bufsize)
+{
+    int ret = read(m_fd, buffer, bufsize);
+    if ( ret == 0 )
+    {
+        m_lasterror = wxSTREAM_EOF;
+    }
+    else if ( ret == -1 )
+    {
+        m_lasterror = wxSTREAM_READ_ERROR;
+        ret = 0;
+    }
+    else
+    {
+        m_lasterror = wxSTREAM_NOERROR;
+    }
+
+    return ret;
+}
+
+size_t wxProcessFileOutputStream::OnSysWrite(const void *buffer, size_t bufsize)
+{
+    int ret = write(m_fd, buffer, bufsize);
+    if ( ret == -1 )
+    {
+        m_lasterror = wxSTREAM_WRITE_ERROR;
+        ret = 0;
+    }
+    else
+    {
+        m_lasterror = wxSTREAM_NOERROR;
+    }
+
+    return ret;
+}
+
+#endif // wxUSE_STREAMS
+
+long wxExecute(wxChar **argv,
+               bool sync,
+               wxProcess *process)
 {
 {
-    wxCHECK_MSG( *argv, 0, wxT("can't exec empty command") );
+    // for the sync execution, we return -1 to indicate failure, but for async
+    // case we return 0 which is never a valid PID
+    //
+    // we define this as a macro, not a variable, to avoid compiler warnings
+    // about "ERROR_RETURN_CODE value may be clobbered by fork()"
+    #define ERROR_RETURN_CODE ((sync) ? -1 : 0)
+
+    wxCHECK_MSG( *argv, ERROR_RETURN_CODE, wxT("can't exec empty command") );
 
 #if wxUSE_UNICODE
     int mb_argc = 0;
 
 #if wxUSE_UNICODE
     int mb_argc = 0;
@@ -272,9 +452,9 @@ long wxExecute( wxChar **argv, bool sync, wxProcess *process )
 
     while (argv[mb_argc])
     {
 
     while (argv[mb_argc])
     {
-      wxWX2MBbuf mb_arg = wxConvertWX2MB(argv[mb_argc]);
-      mb_argv[mb_argc] = strdup(mb_arg);
-      mb_argc++;
+        wxWX2MBbuf mb_arg = wxConvertWX2MB(argv[mb_argc]);
+        mb_argv[mb_argc] = strdup(mb_arg);
+        mb_argc++;
     }
     mb_argv[mb_argc] = (char *) NULL;
 
     }
     mb_argv[mb_argc] = (char *) NULL;
 
@@ -292,92 +472,160 @@ long wxExecute( wxChar **argv, bool sync, wxProcess *process )
 #if wxUSE_GUI
     // create pipes
     int end_proc_detect[2];
 #if wxUSE_GUI
     // create pipes
     int end_proc_detect[2];
-    if (pipe(end_proc_detect) == -1)
+    if ( pipe(end_proc_detect) == -1 )
     {
         wxLogSysError( _("Pipe creation failed") );
     {
         wxLogSysError( _("Pipe creation failed") );
+        wxLogError( _("Failed to execute '%s'\n"), *argv );
 
         ARGS_CLEANUP;
 
 
         ARGS_CLEANUP;
 
-        return 0;
+        return ERROR_RETURN_CODE;
     }
 #endif // wxUSE_GUI
 
     }
 #endif // wxUSE_GUI
 
+    // pipes for inter process communication
+    int pipeIn[2],      // stdin
+        pipeOut[2],     // stdout
+        pipeErr[2];     // stderr
+
+    pipeIn[0] = pipeIn[1] =
+    pipeOut[0] = pipeOut[1] =
+    pipeErr[0] = pipeErr[1] = -1;
+
+    if ( process && process->IsRedirected() )
+    {
+        if ( pipe(pipeIn) == -1 || pipe(pipeOut) == -1 || pipe(pipeErr) == -1 )
+        {
+#if wxUSE_GUI
+            // free previously allocated resources
+            close(end_proc_detect[0]);
+            close(end_proc_detect[1]);
+#endif // wxUSE_GUI
+
+            wxLogSysError( _("Pipe creation failed") );
+            wxLogError( _("Failed to execute '%s'\n"), *argv );
+
+            ARGS_CLEANUP;
+
+            return ERROR_RETURN_CODE;
+        }
+    }
+
     // fork the process
 #ifdef HAVE_VFORK
     pid_t pid = vfork();
 #else
     pid_t pid = fork();
 #endif
     // fork the process
 #ifdef HAVE_VFORK
     pid_t pid = vfork();
 #else
     pid_t pid = fork();
 #endif
-    if (pid == -1)
+
+    if ( pid == -1 )     // error?
     {
     {
+#if wxUSE_GUI
+        close(end_proc_detect[0]);
+        close(end_proc_detect[1]);
+        close(pipeIn[0]);
+        close(pipeIn[1]);
+        close(pipeOut[0]);
+        close(pipeOut[1]);
+        close(pipeErr[0]);
+        close(pipeErr[1]);
+#endif // wxUSE_GUI
+
         wxLogSysError( _("Fork failed") );
 
         ARGS_CLEANUP;
 
         wxLogSysError( _("Fork failed") );
 
         ARGS_CLEANUP;
 
-        return 0;
+        return ERROR_RETURN_CODE;
     }
     }
-    else if (pid == 0)
+    else if ( pid == 0 )  // we're in child
     {
 #if wxUSE_GUI
     {
 #if wxUSE_GUI
-        // we're in child
         close(end_proc_detect[0]); // close reading side
 #endif // wxUSE_GUI
 
         close(end_proc_detect[0]); // close reading side
 #endif // wxUSE_GUI
 
-        // These three lines close the open file descriptors to to avoid any
+        // These lines close the open file descriptors to to avoid any
         // input/output which might block the process or irritate the user. If
         // input/output which might block the process or irritate the user. If
-        // one wants proper IO for the subprocess, the right thing to do is
-        // to start an xterm executing it.
-        if (sync == 0)
+        // one wants proper IO for the subprocess, the right thing to do is to
+        // start an xterm executing it.
+        if ( !sync )
         {
         {
-            // leave stderr opened, it won't do any hurm
             for ( int fd = 0; fd < FD_SETSIZE; fd++ )
             {
             for ( int fd = 0; fd < FD_SETSIZE; fd++ )
             {
+                if ( fd == pipeIn[0] || fd == pipeOut[1] || fd == pipeErr[1]
 #if wxUSE_GUI
 #if wxUSE_GUI
-                if ( fd == end_proc_detect[1] )
-                    continue;
+                     || fd == end_proc_detect[1]
 #endif // wxUSE_GUI
 #endif // wxUSE_GUI
+                   )
+                {
+                    // don't close this one, we still need it
+                    continue;
+                }
 
 
+                // leave stderr opened too, it won't do any hurm
                 if ( fd != STDERR_FILENO )
                     close(fd);
             }
         }
 
                 if ( fd != STDERR_FILENO )
                     close(fd);
             }
         }
 
-#if 0
-        close(STDERR_FILENO);
+        // redirect stdio, stdout and stderr
+        if ( pipeIn[0] != -1 )
+        {
+            if ( dup2(pipeIn[0], STDIN_FILENO) == -1 ||
+                 dup2(pipeOut[1], STDOUT_FILENO) == -1 ||
+                 dup2(pipeErr[1], STDERR_FILENO) == -1 )
+            {
+                wxLogSysError(_("Failed to redirect child process input/output"));
+            }
 
 
-        // some programs complain about stderr not being open, so redirect
-        // them:
-        open("/dev/null", O_RDONLY);  // stdin
-        open("/dev/null", O_WRONLY);  // stdout
-        open("/dev/null", O_WRONLY);  // stderr
-#endif
+            close(pipeIn[0]);
+            close(pipeOut[1]);
+            close(pipeErr[1]);
+        }
 
         execvp (*mb_argv, mb_argv);
 
         // there is no return after successful exec()
 
         execvp (*mb_argv, mb_argv);
 
         // there is no return after successful exec()
-        wxFprintf(stderr, _("Can't execute '%s'\n"), *argv);
-
         _exit(-1);
     }
         _exit(-1);
     }
-    else
+    else // we're in parent
     {
     {
-#if wxUSE_GUI
-        wxEndProcessData *data = new wxEndProcessData;
+        ARGS_CLEANUP;
 
 
+        // pipe initialization: construction of the wxStreams
+        if ( process && process->IsRedirected() )
+        {
+#if wxUSE_STREAMS
+            // These two streams are relative to this process.
+            wxOutputStream *outStream = new wxProcessFileOutputStream(pipeIn[1]);
+            wxInputStream *inStream = new wxProcessFileInputStream(pipeOut[0]);
+            wxInputStream *errStream = new wxProcessFileInputStream(pipeErr[0]);
+
+            process->SetPipeStreams(inStream, outStream, errStream);
+#endif // wxUSE_STREAMS
+
+            close(pipeIn[0]); // close reading side
+            close(pipeOut[1]); // close writing side
+            close(pipeErr[1]); // close writing side
+        }
 
 
-        ARGS_CLEANUP;
+#if wxUSE_GUI && !defined(__WXMICROWIN__)
+        wxEndProcessData *data = new wxEndProcessData;
 
         if ( sync )
         {
 
         if ( sync )
         {
-            wxASSERT_MSG( !process, wxT("wxProcess param ignored for sync exec") );
+            // we may have process for capturing the program output, but it's
+            // not used in wxEndProcessData in the case of sync execution
             data->process = NULL;
 
             // sync execution: indicate it by negating the pid
             data->pid = -pid;
             data->tag = wxAddProcessCallback(data, end_proc_detect[0]);
             data->process = NULL;
 
             // sync execution: indicate it by negating the pid
             data->pid = -pid;
             data->tag = wxAddProcessCallback(data, end_proc_detect[0]);
-            // we're in parent
+
             close(end_proc_detect[1]); // close writing side
 
             close(end_proc_detect[1]); // close writing side
 
+            wxBusyCursor bc;
+            wxWindowDisabler wd;
+
             // it will be set to 0 from GTK_EndProcessDetector
             while (data->pid != 0)
                 wxYield();
             // it will be set to 0 from GTK_EndProcessDetector
             while (data->pid != 0)
                 wxYield();
@@ -388,15 +636,15 @@ long wxExecute( wxChar **argv, bool sync, wxProcess *process )
 
             return exitcode;
         }
 
             return exitcode;
         }
-        else
+        else // async execution
         {
             // async execution, nothing special to do - caller will be
             // notified about the process termination if process != NULL, data
             // will be deleted in GTK_EndProcessDetector
         {
             // async execution, nothing special to do - caller will be
             // notified about the process termination if process != NULL, data
             // will be deleted in GTK_EndProcessDetector
-            data->process = process;
-            data->pid = pid;
-            data->tag = wxAddProcessCallback(data, end_proc_detect[0]);
-            // we're in parent
+            data->process  = process;
+            data->pid      = pid;
+            data->tag      = wxAddProcessCallback(data, end_proc_detect[0]);
+
             close(end_proc_detect[1]); // close writing side
 
             return pid;
             close(end_proc_detect[1]); // close writing side
 
             return pid;
@@ -413,11 +661,18 @@ long wxExecute( wxChar **argv, bool sync, wxProcess *process )
         return exitcode;
 #endif // wxUSE_GUI
     }
         return exitcode;
 #endif // wxUSE_GUI
     }
+#ifdef __VMS
+   // VMS does not recognise exit as a return and complains about
+   // a missing return
+   // I think VMS is wrong in this
+   //     JJ
    return 0;
    return 0;
-
-    #undef ARGS_CLEANUP
+#endif
 }
 
 }
 
+#undef ERROR_RETURN_CODE
+#undef ARGS_CLEANUP
+
 // ----------------------------------------------------------------------------
 // file and directory functions
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
 // file and directory functions
 // ----------------------------------------------------------------------------
@@ -425,9 +680,14 @@ long wxExecute( wxChar **argv, bool sync, wxProcess *process )
 const wxChar* wxGetHomeDir( wxString *home  )
 {
     *home = wxGetUserHome( wxString() );
 const wxChar* wxGetHomeDir( wxString *home  )
 {
     *home = wxGetUserHome( wxString() );
+   wxString tmp;
     if ( home->IsEmpty() )
         *home = wxT("/");
     if ( home->IsEmpty() )
         *home = wxT("/");
-
+#ifdef __VMS
+   tmp = *home;
+   if ( tmp.Last() != wxT(']'))
+     if ( tmp.Last() != wxT('/')) *home << wxT('/');
+#endif
     return home->c_str();
 }
 
     return home->c_str();
 }
 
@@ -572,7 +832,7 @@ bool wxGetUserName(wxChar *buf, int sz)
     if ((who = getpwuid (getuid ())) != NULL)
     {
         // pw_gecos field in struct passwd is not standard
     if ((who = getpwuid (getuid ())) != NULL)
     {
         // pw_gecos field in struct passwd is not standard
-#if HAVE_PW_GECOS
+#ifdef HAVE_PW_GECOS
        char *comma = strchr(who->pw_gecos, ',');
        if (comma)
            *comma = '\0'; // cut off non-name comment fields
        char *comma = strchr(who->pw_gecos, ',');
        if (comma)
            *comma = '\0'; // cut off non-name comment fields
@@ -595,6 +855,175 @@ wxString wxGetOsDescription()
 #endif
 }
 
 #endif
 }
 
+// this function returns the GUI toolkit version in GUI programs, but OS
+// version in non-GUI ones
+#if !wxUSE_GUI
+
+int wxGetOsVersion(int *majorVsn, int *minorVsn)
+{
+    int major, minor;
+    char name[256];
+
+    if ( sscanf(WXWIN_OS_DESCRIPTION, "%s %d.%d", name, &major, &minor) != 3 )
+    {
+        // unreckognized uname string format
+        major = minor = -1;
+    }
+
+    if ( majorVsn )
+        *majorVsn = major;
+    if ( minorVsn )
+        *minorVsn = minor;
+
+    return wxUNIX;
+}
+
+#endif // !wxUSE_GUI
+
+long wxGetFreeMemory()
+{
+#if defined(__LINUX__)
+    // get it from /proc/meminfo
+    FILE *fp = fopen("/proc/meminfo", "r");
+    if ( fp )
+    {
+        long memFree = -1;
+
+        char buf[1024];
+        if ( fgets(buf, WXSIZEOF(buf), fp) && fgets(buf, WXSIZEOF(buf), fp) )
+        {
+            long memTotal, memUsed;
+            sscanf(buf, "Mem: %ld %ld %ld", &memTotal, &memUsed, &memFree);
+        }
+
+        fclose(fp);
+
+        return memFree;
+    }
+#elif defined(__SUN__) && defined(_SC_AVPHYS_PAGES)
+    return sysconf(_SC_AVPHYS_PAGES)*sysconf(_SC_PAGESIZE);
+//#elif defined(__FREEBSD__) -- might use sysctl() to find it out, probably
+#endif
+
+    // can't find it out
+    return -1;
+}
+
+// ----------------------------------------------------------------------------
+// env vars
+// ----------------------------------------------------------------------------
+
+bool wxGetEnv(const wxString& var, wxString *value)
+{
+    // wxGetenv is defined as getenv()
+    wxChar *p = wxGetenv(var);
+    if ( !p )
+        return FALSE;
+
+    if ( value )
+    {
+        *value = p;
+    }
+
+    return TRUE;
+}
+
+bool wxSetEnv(const wxString& variable, const wxChar *value)
+{
+#if defined(HAVE_SETENV)
+    return setenv(variable.mb_str(), value ? wxString(value).mb_str().data()
+                                           : NULL, 1 /* overwrite */) == 0;
+#elif defined(HAVE_PUTENV)
+    wxString s = variable;
+    if ( value )
+        s << _T('=') << value;
+
+    // transform to ANSI
+    const char *p = s.mb_str();
+
+    // the string will be free()d by libc
+    char *buf = (char *)malloc(strlen(p) + 1);
+    strcpy(buf, p);
+
+    return putenv(buf) == 0;
+#else // no way to set an env var
+    return FALSE;
+#endif
+}
+
+// ----------------------------------------------------------------------------
+// signal handling
+// ----------------------------------------------------------------------------
+
+#if wxUSE_ON_FATAL_EXCEPTION
+
+#include <signal.h>
+
+static void wxFatalSignalHandler(wxTYPE_SA_HANDLER)
+{
+    if ( wxTheApp )
+    {
+        // give the user a chance to do something special about this
+        wxTheApp->OnFatalException();
+    }
+
+    abort();
+}
+
+bool wxHandleFatalExceptions(bool doit)
+{
+    // old sig handlers
+    static bool s_savedHandlers = FALSE;
+    static struct sigaction s_handlerFPE,
+                            s_handlerILL,
+                            s_handlerBUS,
+                            s_handlerSEGV;
+
+    bool ok = TRUE;
+    if ( doit && !s_savedHandlers )
+    {
+        // install the signal handler
+        struct sigaction act;
+
+        // some systems extend it with non std fields, so zero everything
+        memset(&act, 0, sizeof(act));
+
+        act.sa_handler = wxFatalSignalHandler;
+        sigemptyset(&act.sa_mask);
+        act.sa_flags = 0;
+
+        ok &= sigaction(SIGFPE, &act, &s_handlerFPE) == 0;
+        ok &= sigaction(SIGILL, &act, &s_handlerILL) == 0;
+        ok &= sigaction(SIGBUS, &act, &s_handlerBUS) == 0;
+        ok &= sigaction(SIGSEGV, &act, &s_handlerSEGV) == 0;
+        if ( !ok )
+        {
+            wxLogDebug(_T("Failed to install our signal handler."));
+        }
+
+        s_savedHandlers = TRUE;
+    }
+    else if ( s_savedHandlers )
+    {
+        // uninstall the signal handler
+        ok &= sigaction(SIGFPE, &s_handlerFPE, NULL) == 0;
+        ok &= sigaction(SIGILL, &s_handlerILL, NULL) == 0;
+        ok &= sigaction(SIGBUS, &s_handlerBUS, NULL) == 0;
+        ok &= sigaction(SIGSEGV, &s_handlerSEGV, NULL) == 0;
+        if ( !ok )
+        {
+            wxLogDebug(_T("Failed to uninstall our signal handler."));
+        }
+
+        s_savedHandlers = FALSE;
+    }
+    //else: nothing to do
+
+    return ok;
+}
+
+#endif // wxUSE_ON_FATAL_EXCEPTION
+
 // ----------------------------------------------------------------------------
 // error and debug output routines (deprecated, use wxLog)
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
 // error and debug output routines (deprecated, use wxLog)
 // ----------------------------------------------------------------------------