src/OSD/OSD.cdl

   1 -- Copyright (c) 1992-1999 Matra Datavision
   2 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   3 --
   4 -- The content of this file is subject to the Open CASCADE Technology Public
   5 -- License Version 6.5 (the "License"). You may not use the content of this file
   6 -- except in compliance with the License. Please obtain a copy of the License
   7 -- at http://www.opencascade.org and read it completely before using this file.
   8 --
   9 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  10 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  11 --
  12 -- The Original Code and all software distributed under the License is
  13 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  14 -- Initial Developer hereby disclaims all such warranties, including without
  15 -- limitation, any warranties of merchantability, fitness for a particular
  16 -- purpose or non-infringement. Please see the License for the specific terms
  17 -- and conditions governing the rights and limitations under the License.
  18
  19 -- Update:
  20 --              20-01-2009 : ABD Integration support of system fonts (using FTGL and FreeType)
  21
  22 package OSD
  23
  24  ---History:
  25  --   Version   Date        Purpose
  26  --   1.1   24/06/92    Operating System Dependent tools
  27  --   1.2
  28  --   2.0
  29  --   3.0
  30  --   Windows NT 30/09/96 ( EUG )
  31  ---Purpose: Set of Operating Sytem Dependent Tools
  32  --         (O)perating (S)ystem (D)ependent
  33
  34 uses
  35
  36     Standard ,
  37     Quantity ,
  38     TCollection
  39
  40 is
  41
  42  exception OSDError inherits Failure from Standard  ;
  43
  44  imported Function;
  45    ---Purpose: This is in fact a pointer to a function.
  46    --          This is not an "enumeration" but a trick to solve an omission
  47    --          from CDL.
  48    --- C++: alias "typedef int (* OSD_Function)(...);"
  49
  50  enumeration OEMType is Unavailable,SUN,DEC,SGI,NEC,MAC,PC,HP,IBM,VAX,LIN,AIX;
  51    ---Purpose: This is set of possible machine types
  52    --          used in OSD_Host::MachineType
  53
  54  enumeration SysType is Unknown,Default,UnixBSD, UnixSystemV, VMS, OS2,
  55                         OSF, MacOs, Taligent, WindowsNT, LinuxREDHAT,Aix;
  56    ---Purpose: Thisd is a set of possible system types.
  57    --          'Default' means SysType of machine operating this process.
  58    --          This can be used with the Path class.
  59    --          All UNIX-like are grouped under "UnixBSD" or "UnixSystemV".
  60    --          Such systems are Solaris, NexTOS ...
  61    --          A category of systems accept MSDOS-like path such as
  62    --          WindowsNT and OS2.
  63
  64  enumeration FromWhere is FromBeginning, FromHere, FromEnd;
  65    ---Purpose: Used by OSD_File in the method Seek.
  66
  67  enumeration LockType is NoLock, ReadLock, WriteLock, ExclusiveLock;
  68    ---Purpose: locks for files.
  69    --          NoLock is the default value when opening a file.
  70    --
  71    --          ReadLock allows only one reading of the file at a time.
  72    --
  73    --          WriteLock prevents others writing into a file(excepted the user
  74    --          who puts the lock)but allows everybody to read.
  75    --
  76    --          ExclusiveLock prevents reading and writing except for the
  77    --          current user of the file.
  78    --          So ExclusiveLock means only one user on the file and this
  79    --          user is the one who puts the lock.
  80
  81  enumeration SingleProtection is None,R,W,RW,X,RX,WX,RWX,D,RD,WD,RWD,XD,RXD,WXD,RWXD;
  82    ---Purpose: Access rights for files.
  83    --          R means Read, W means Write, X means eXecute and D means Delete.
  84    --          On UNIX, the right to Delete is combined with Write access.
  85    --          So if "W"rite is not set and "D"elete is, "W"rite will be set
  86    --          and if "W" is set, "D" will be too.
  87
  88  enumeration OpenMode is ReadOnly, WriteOnly, ReadWrite;
  89    ---Purpose: Specifies the file open mode.
  90
  91  enumeration LoadMode is RTLD_LAZY, RTLD_NOW;
  92    ---Purpose: This enumeration is used to load shareable libraries.
  93
  94  enumeration KindFile is FILE, DIRECTORY, LINK, SOCKET, UNKNOWN;
  95    ---Purpose: Specifies the type of files.
  96
  97  private enumeration WhoAmI is  WDirectory, WDirectoryIterator,
  98              WEnvironment, WFile, WFileNode, WFileIterator, WMailBox,
  99              WPath, WProcess, WProtection, WSemaphore, WHost, WDisk,
 100              WChronometer, WSharedMemory, WTimer, WPackage, WPrinter,
 101              WEnvironmentIterator;
 102    ---Purpose: Allows great accuracy for error management.
 103    --          This is private.
 104
 105
 106          class Error;
 107              ---Purpose: Accurate management of OSD specific errors.
 108
 109          class Protection;
 110              ---Purpose: Gets and sets protection attributes of 'system , user ,
 111              --          group, and world'.
 112
 113          class Path;
 114              ---Purpose: Manages independent system path translation.
 115
 116          deferred class FileNode;
 117              ---Purpose: A set of file/directory manipulation tools.
 118
 119          class Disk;
 120              ---Purpose: A set of disk oriented tools.
 121
 122          class File;
 123              ---Purpose: A set of file oriented tools.
 124
 125          class FileIterator;
 126              ---Purpose: Searches for child files in current directory.
 127
 128          class Directory;
 129              ---Purpose: A set of directory oriented tools
 130
 131          class DirectoryIterator;
 132              ---Purpose: Searches sub-directories in current directory.
 133
 134          class Chronometer;
 135              ---Purpose: Measures time elapsed for performance program tests.
 136              --          Measures CPU time consumed by a method call.
 137
 138          class Timer;
 139              ---Purpose: Measures the effective time elapsed for a method call.
 140
 141          class Printer;
 142              ---Purpose: Selects a printer (used by File).
 143
 144          class Host;
 145              ---Purpose: Carries information about a host.
 146              --          System version ,host name, nodename ...
 147
 148          class Environment;
 149              ---Purpose: Manages environment variables.
 150
 151          class EnvironmentIterator;
 152              ---Purpose: Get all environment variables.
 153
 154          class Process;
 155              ---Purpose: Process specific oriented tools
 156
 157          class SharedMemory;
 158              ---Purpose: Manages shared memory.
 159
 160          class Semaphore;
 161              ---Purpose: Manages semaphores.
 162
 163 --         class Mutex is alias Mutex from Standard;
 164              ---Purpose: Mutex object to synchronize threads within one process
 165
 166          class MailBox;
 167              ---Purpose: Manages asynchronous mail boxes.
 168
 169          class SharedLibrary;
 170              ---Purpose: Provides tools to load a shared library
 171              --          and retrieve the address of an entry point.
 172
 173      imported MemInfo;
 174      imported PThread;
 175      imported ThreadFunction;
 176          class Thread;
 177              ---Purpose: A tool to manage threads
 178
 179     class Real2String;
 180              ---Purpose: Convertion of CString to Real and reciprocally
 181
 182     class Localizer;
 183              ---Purpose: Manages locale.
 184
 185
 186     -----------------------------------------------
 187     --  UNIX specific exceptions and enumeration --
 188     -----------------------------------------------
 189
 190     exception Signal  inherits Failure from  Standard;
 191     exception SIGHUP  inherits Signal;
 192     exception SIGINT  inherits Signal;
 193     exception SIGQUIT inherits Signal;
 194     exception SIGILL  inherits Signal;
 195     exception SIGKILL inherits Signal;
 196     exception SIGBUS  inherits Signal;
 197     exception SIGSEGV inherits Signal;
 198     exception SIGSYS  inherits Signal;
 199
 200
 201     enumeration Signals is
 202       ---purpose:
 203       --     The "posix" signals.
 204       --
 205       S_SIGHUP,          -- "hangup."
 206       S_SIGINT,          -- "interrupt."
 207       S_SIGQUIT,         -- "quit."
 208       S_SIGILL,          -- "illegal instruction."
 209       S_SIGKILL,         -- "kill."
 210       S_SIGBUS,          -- "bus error."
 211       S_SIGSEGV,         -- "segmentation violation."
 212       S_SIGSYS,          -- "bad argument to system call."
 213       S_SIGFPE,          -- "floating point exception."
 214       S_FPE_FLTDIV_TRAP, -- "floating/decimal divide by zero."
 215       S_FPE_INTDIV_TRAP, -- "integer divide by zero."
 216       S_FPE_FLTOVF_TRAP, -- "floating overflow."
 217       S_FPE_INTOVF_TRAP, -- "integer overflow."
 218       S_FPE_FLTUND_TRAP, -- "floating underflow."
 219       S_FPE_FLTINEX_TRAP -- "floating inexact result."
 220     end Signals;
 221
 222     ----------------------------------------
 223     -- Exceptions ( Windows NT specific ) --
 224     ----------------------------------------
 225
 226     exception Exception inherits Failure   from  Standard;
 227
 228     exception Exception_ACCESS_VIOLATION         inherits Exception;
 229     exception Exception_ARRAY_BOUNDS_EXCEEDED    inherits Exception;
 230     exception Exception_FLT_DENORMAL_OPERAND     inherits Exception;
 231     exception Exception_FLT_DIVIDE_BY_ZERO       inherits Exception;
 232     exception Exception_FLT_INEXACT_RESULT       inherits Exception;
 233     exception Exception_FLT_INVALID_OPERATION    inherits Exception;
 234     exception Exception_FLT_OVERFLOW             inherits Exception;
 235     exception Exception_FLT_STACK_CHECK          inherits Exception;
 236     exception Exception_FLT_UNDERFLOW            inherits Exception;
 237     exception Exception_ILLEGAL_INSTRUCTION      inherits Exception;
 238     exception Exception_IN_PAGE_ERROR            inherits Exception;
 239     exception Exception_INT_DIVIDE_BY_ZERO       inherits Exception;
 240     exception Exception_INT_OVERFLOW             inherits Exception;
 241     exception Exception_INVALID_DISPOSITION      inherits Exception;
 242     exception Exception_NONCONTINUABLE_EXCEPTION inherits Exception;
 243     exception Exception_PRIV_INSTRUCTION         inherits Exception;
 244     exception Exception_STACK_OVERFLOW           inherits Exception;
 245     exception Exception_STATUS_NO_MEMORY         inherits Exception; -- generating by 'HeapAlloc'
 246     exception Exception_CTRL_BREAK               inherits Exception; -- generating by 'Ctrl-C' keystroke
 247
 248     ----------------------------------------------
 249     -- Handler and SegvHandler (UNIX specific ) --
 250     ----------------------------------------------
 251
 252     --
 253     --     Handler(aSignal: Signals; aCode: Signals)
 254     --
 255
 256     Handler(aSignal: Signals; aSigInfo: Address; aContext: Address)
 257     ---Purpose:
 258     --   1) Raise a exception when aSignal is a floating point signal.
 259     --    aSignal is SIGFPE.
 260     --    aCode is
 261     --        (FPE:  Floating Point Exception)
 262     --        (FLT:  FLoaTing operation.)
 263     --        (INT:  INTeger  operation.)
 264     --        (DIV:  DIVided by zero.)
 265     --        (OVF:  OVerFlow.)
 266     --        (INEX: INEXact operation.)
 267     --
 268     --        FPE_FLTDIV_TRAP  (the exception "DivideByZero" is raised.)
 269     --        FPE_INTDIV_TRAP  (the exception "DivideByZero" is raised.)
 270     --
 271     --        FPE_FLTOVF_TRAP  (the exception "Overflow" is raised.)
 272     --        FPE_INTOVF_TRAP  (the exception "Overflow" is raised.)
 273     --
 274     --        FPE_FLTINEX_TRAP (the exception "NumericError" is raised.)
 275     --
 276     --   2) Display the signal name, and call "exit" with signal number for
 277     --   a "Hardware" signal.
 278     --
 279     raises
 280         DivideByZero,
 281     Overflow,
 282     Underflow,
 283         SIGHUP,
 284         SIGINT,
 285         SIGQUIT,
 286         SIGILL,
 287         SIGKILL,
 288         SIGBUS,
 289         SIGSEGV,
 290         SIGSYS
 291     is private;
 292
 293     SegvHandler(aSignal: Signals; aSigInfo: Address; aContext: Address)
 294     ---Purpose:
 295     -- Handle access to null object and segmentation violation
 296     --
 297     raises
 298         NullObject,
 299         SIGSEGV
 300     is private;
 301
 302     ---------------------------------------
 303     -- WntHandler (Windows NT specific ) --
 304     ---------------------------------------
 305
 306     WntHandler ( exceptionInfo : Address from Standard )
 307      returns Integer from Standard
 308      raises  DivideByZero,
 309              Overflow,
 310          Underflow,
 311          Exception_ACCESS_VIOLATION,
 312          Exception_ARRAY_BOUNDS_EXCEEDED,
 313          Exception_FLT_DENORMAL_OPERAND,
 314          Exception_FLT_DIVIDE_BY_ZERO,
 315          Exception_FLT_INEXACT_RESULT,
 316          Exception_FLT_INVALID_OPERATION,
 317          Exception_FLT_OVERFLOW,
 318          Exception_FLT_STACK_CHECK,
 319          Exception_FLT_UNDERFLOW,
 320          Exception_ILLEGAL_INSTRUCTION,
 321          Exception_IN_PAGE_ERROR,
 322          Exception_INVALID_DISPOSITION,
 323          Exception_NONCONTINUABLE_EXCEPTION,
 324          Exception_PRIV_INSTRUCTION,
 325          Exception_STACK_OVERFLOW,
 326          Exception_STATUS_NO_MEMORY
 327      is private;
 328         ---Purpose:
 329         --  1) Raises an exception if the exception due to floating point errors.
 330         --     Flosting point errors:
 331         --     EXCEPTION_FLT_DENORMAL_OPERAND
 332         --     EXCEPTION_FLT_DIVIDE_BY_ZERO
 333         --     EXCEPTION_FLT_INEXACT_RESULT
 334         --     EXCEPTION_FLT_INVALID_OPERATION
 335         --     EXCEPTOPN_FLT_OVERFLOW
 336         --     EXCEPTION_FLT_STACK_CHECK
 337         --     EXCEPTION_FLT_UNDERFLOW
 338         --  2) Displays a message box 'Continue' - 'Debugger' - 'Stop' if the environment
 339         --     variable 'CSF_EXCEPTION_PROMPT' is set and takes appropriate action.
 340         --     Raises an exception otherwise.
 341
 342     SetSignal(theFloatingSignal: Boolean = Standard_True);
 343     ---Purpose:
 344     -- Sets signal and exception handlers.
 345     -- <b>Windows-specific notes<\b>
 346     -- Compiled with MS VC++ sets 3 main handlers:
 347     -- @li Signal handlers (via ::signal() functions) that translate system signals
 348     --     (SIGSEGV, SIGFPE, SIGILL) into C++ exceptions (classes inheriting
 349     --     Standard_Failure). They only be called if user calls ::raise() function
 350     --     with one of supported signal type set.
 351     -- @li Exception handler OSD::WntHandler() (via ::SetUnhandledExceptionFilter())
 352     --     that will be used when user's code is compiled with /EHs option.
 353     -- @li Structured exception (SE) translator (via _set_se_translator()) that
 354     --     translates SE exceptions (aka asynchronous exceptions) into the
 355     --     C++ exceptions inheriting Standard_Failure. This translator will be
 356     --     used when user's code is compiled with /EHa option.
 357     -- .
 358     -- This approach ensures that regardless of the option the user chooses to
 359     -- compile his code with (/EHs or /EHa), signals (or SE exceptions) will be
 360     -- translated into Open CASCADE C++ exceptions.
 361     -- .
 362     -- If @a theFloatingSignal is TRUE then floating point exceptions will be
 363     -- generated in accordance with the mask
 364     -- <tt>_EM_INVALID | _EM_DENORMAL | _EM_ZERODIVIDE | _EM_OVERFLOW<\tt> that is
 365     -- used to call ::_controlfp() system function. If @a theFloatingSignal is FALSE
 366     -- corresponding operations (e.g. division by zero) will gracefully complete
 367     -- without an exception.
 368     -- .
 369     -- <b>Unix-specific notes<\b>
 370     -- OSD::SetSignal() sets handlers (via ::sigaction()) for multiple signals
 371     -- (SIGFPE, SIGSEGV, etc). Currently the number of handled signals is much
 372     -- greater than for Windows, in the future this may change to provide better
 373     -- consistency with Windows.
 374     -- .
 375     -- @a theFloatingSignal is recognized on Sun Solaris, Linux, and SGI Irix to
 376     -- generate floating-point exception according to the mask
 377     -- <tt>FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW</tt> (in Linux conventions).<br>
 378     -- When compiled with OBJS macro defined, already set signal handlers (e.g.
 379     -- by Data Base Managers) are not redefined.
 380     -- .
 381     -- <b>Common notes<\b>
 382     -- If OSD::SetSignal() method is used in at least one thread, it must also be
 383     -- called in any other thread where Open CASCADE will be used, to ensure
 384     -- consistency of behavior. Its @a aFloatingSignal argument must be consistent
 385     -- across threads.
 386     -- .
 387     -- Keep in mind that whether the C++ exception will really be thrown (i.e.
 388     -- ::throw() will be called) is regulated by the NO_CXX_EXCEPTIONS and
 389     -- OCC_CONVERT_SIGNALS macros used during compilation of Open CASCADE and
 390     -- user's code. Refer to Foundation Classes User's Guide for further details.
 391     --
 392
 393     AvailableMemory returns Integer from Standard;
 394     ---Purpose: Returns available memory in Kilobytes.
 395     ---Level: Advanced
 396
 397     SecSleep(aDelay: Integer from Standard);
 398     ---Purpose: Commands the process to sleep for a number of seconds.
 399     ---Level: Public
 400
 401     MilliSecSleep(aDelay: Integer from Standard);
 402     ---Purpose: Commands the process to sleep for a number of milliseconds
 403     ---Level: Public
 404
 405     RealToCString(aReal: Real; aString:out PCharacter)
 406         returns Boolean ;
 407     ---Purpose:
 408     --  Converts aReal into aCstring in exponential format with a period as
 409     --  decimal point, no thousand separator and no grouping of digits.
 410     --  The conversion is independant from the current locale
 411     ---Level: Public
 412
 413     CStringToReal(aString: CString; aReal: out Real) returns Boolean ;
 414     ---Purpose:
 415     --  Converts aCstring representing a real with a period as
 416     --  decimal point, no thousand separator and no grouping of digits
 417     --  into aReal .
 418     --  The conversion is independant from the current locale.
 419     ---Level: Public
 420
 421     IsDivisible(aDividend, aDivisor: Real from Standard)
 422     returns Boolean from Standard;
 423     ---Purpose: Tests if the quotient theDividend/theDivisor
 424     --          does not overflow
 425     ---Level: Public
 426
 427     GetExponent(aReal: Real from Standard)
 428     returns Integer from Standard;
 429     ---Purpose: Returns the exponent in base 2 of a floating-point number.
 430     ---Level: Public
 431
 432     GetMantissa(aReal: Real from Standard)
 433     returns Real from Standard;
 434     ---Purpose: Returns the mantissa of a floating-point number.
 435     ---Level: Public
 436
 437     -------------------------
 438     -- Windows NT specific --
 439     -------------------------
 440
 441     ControlBreak raises  Exception_CTRL_BREAK;
 442     ---Purpose: since Windows NT does not support 'SIGINT' signal like UNIX,
 443     --          then this method checks whether Ctrl-Break keystroke was or
 444     --          not. If yes then raises Exception_CTRL_BREAK.
 445
 446 end OSD;