0022545: Improved exception handling
[occt.git] / 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;