LibreOffice
LibreOffice 6.0 SDK C/C++ API Reference
types.h
Go to the documentation of this file.
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3  * This file is part of the LibreOffice project.
4  *
5  * This Source Code Form is subject to the terms of the Mozilla Public
6  * License, v. 2.0. If a copy of the MPL was not distributed with this
7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8  *
9  * This file incorporates work covered by the following license notice:
10  *
11  * Licensed to the Apache Software Foundation (ASF) under one or more
12  * contributor license agreements. See the NOTICE file distributed
13  * with this work for additional information regarding copyright
14  * ownership. The ASF licenses this file to you under the Apache
15  * License, Version 2.0 (the "License"); you may not use this file
16  * except in compliance with the License. You may obtain a copy of
17  * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18  */
19 
20 #ifndef INCLUDED_SAL_TYPES_H
21 #define INCLUDED_SAL_TYPES_H
22 
23 #include <sal/config.h>
24 
25 #include <stddef.h>
26 
27 #include <sal/macros.h>
28 #include <sal/typesizes.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /********************************************************************************/
35 /* Data types
36 */
37 
38 /* Boolean */
39 typedef unsigned char sal_Bool;
40 # define sal_False ((sal_Bool)0)
41 # define sal_True ((sal_Bool)1)
42 
43 /* char is assumed to always be 1 byte long */
44 typedef signed char sal_Int8;
45 typedef unsigned char sal_uInt8;
46 
47 #if SAL_TYPES_SIZEOFSHORT == 2
48  typedef signed short sal_Int16;
49  typedef unsigned short sal_uInt16;
50 #else
51  #error "Could not find 16-bit type, add support for your architecture"
52 #endif
53 
54 #if SAL_TYPES_SIZEOFLONG == 4
55  typedef signed long sal_Int32;
56  typedef unsigned long sal_uInt32;
57  #define SAL_PRIdINT32 "ld"
58  #define SAL_PRIuUINT32 "lu"
59  #define SAL_PRIxUINT32 "lx"
60  #define SAL_PRIXUINT32 "lX"
61 #elif SAL_TYPES_SIZEOFINT == 4
62  typedef signed int sal_Int32;
63  typedef unsigned int sal_uInt32;
64  #define SAL_PRIdINT32 "d"
65  #define SAL_PRIuUINT32 "u"
66  #define SAL_PRIxUINT32 "x"
67  #define SAL_PRIXUINT32 "X"
68 #else
69  #error "Could not find 32-bit type, add support for your architecture"
70 #endif
71 
72 #ifdef _MSC_VER
73  typedef __int64 sal_Int64;
74  typedef unsigned __int64 sal_uInt64;
75 
76  /* The following are macros that will add the 64 bit constant suffix. */
77  #define SAL_CONST_INT64(x) x##i64
78  #define SAL_CONST_UINT64(x) x##ui64
79 
80  #define SAL_PRIdINT64 "I64d"
81  #define SAL_PRIuUINT64 "I64u"
82  #define SAL_PRIxUINT64 "I64x"
83  #define SAL_PRIXUINT64 "I64X"
84 #elif defined (__GNUC__)
85  #if SAL_TYPES_SIZEOFLONG == 8
86  typedef signed long int sal_Int64;
87  typedef unsigned long int sal_uInt64;
88 
89 
90  /* The following are macros that will add the 64 bit constant suffix. */
91  #define SAL_CONST_INT64(x) x##l
92  #define SAL_CONST_UINT64(x) x##ul
93 
94  #define SAL_PRIdINT64 "ld"
95  #define SAL_PRIuUINT64 "lu"
96  #define SAL_PRIxUINT64 "lx"
97  #define SAL_PRIXUINT64 "lX"
98  #elif SAL_TYPES_SIZEOFLONGLONG == 8
99  typedef signed long long sal_Int64;
100  typedef unsigned long long sal_uInt64;
101 
102  /* The following are macros that will add the 64 bit constant suffix. */
103  #define SAL_CONST_INT64(x) x##ll
104  #define SAL_CONST_UINT64(x) x##ull
105 
106  #define SAL_PRIdINT64 "lld"
107  #define SAL_PRIuUINT64 "llu"
108  #define SAL_PRIxUINT64 "llx"
109  #define SAL_PRIXUINT64 "llX"
110  #else
111  #error "Could not find 64-bit type, add support for your architecture"
112  #endif
113 #else
114  #error "Please define the 64-bit types for your architecture/compiler in include/sal/types.h"
115 #endif
116 
121 typedef char sal_Char;
122 
127 typedef signed char sal_sChar;
128 
133 typedef unsigned char sal_uChar;
134 
135 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
136  #define SAL_UNICODE_NOTEQUAL_WCHAR_T
137  typedef char16_t sal_Unicode;
138 #elif defined(SAL_W32)
139  typedef wchar_t sal_Unicode;
140 #else
141  #define SAL_UNICODE_NOTEQUAL_WCHAR_T
142  typedef sal_uInt16 sal_Unicode;
143 #endif
144 
145 typedef void * sal_Handle;
146 
147 /* sal_Size should currently be the native width of the platform */
148 #if SAL_TYPES_SIZEOFPOINTER == 4
149  typedef sal_uInt32 sal_Size;
150  typedef sal_Int32 sal_sSize;
151 #elif SAL_TYPES_SIZEOFPOINTER == 8
152  typedef sal_uInt64 sal_Size;
153  typedef sal_Int64 sal_sSize;
154 #else
155  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
156 #endif
157 
158 /* sal_PtrDiff holds the result of a pointer subtraction */
159 #if SAL_TYPES_SIZEOFPOINTER == 4
160  typedef sal_Int32 sal_PtrDiff;
161 #elif SAL_TYPES_SIZEOFPOINTER == 8
162  typedef sal_Int64 sal_PtrDiff;
163 #else
164  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
165 #endif
166 
167 /* printf-style conversion specification length modifiers for size_t and
168  ptrdiff_t (most platforms support C99, MSC has its own extension) */
169 #if defined(_MSC_VER)
170  #define SAL_PRI_SIZET "I"
171  #define SAL_PRI_PTRDIFFT "I"
172 #else
173  #define SAL_PRI_SIZET "z"
174  #define SAL_PRI_PTRDIFFT "t"
175 #endif
176 
177 /* sal_IntPtr, sal_uIntPtr are integer types designed to hold pointers so that any valid
178  * pointer to void can be converted to this type and back to a pointer to void and the
179  * result will compare to the original pointer */
180 #if SAL_TYPES_SIZEOFPOINTER == 4
181  typedef sal_Int32 sal_IntPtr;
182  typedef sal_uInt32 sal_uIntPtr;
183  #define SAL_PRIdINTPTR SAL_PRIdINT32
184  #define SAL_PRIuUINTPTR SAL_PRIuUINT32
185  #define SAL_PRIxUINTPTR SAL_PRIxUINT32
186  #define SAL_PRIXUINTPTR SAL_PRIXUINT32
187 #elif SAL_TYPES_SIZEOFPOINTER == 8
188  typedef sal_Int64 sal_IntPtr;
189  typedef sal_uInt64 sal_uIntPtr;
190  #define SAL_PRIdINTPTR SAL_PRIdINT64
191  #define SAL_PRIuUINTPTR SAL_PRIuUINT64
192  #define SAL_PRIxUINTPTR SAL_PRIxUINT64
193  #define SAL_PRIXUINTPTR SAL_PRIXUINT64
194 #else
195  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
196 #endif
197 
198 /********************************************************************************/
199 /* Useful defines
200  */
201 
202 /* The following SAL_MIN_INTn defines codify the assumption that the signed
203  * sal_Int types use two's complement representation. Defining them as
204  * "-0x7F... - 1" instead of as "-0x80..." prevents warnings about applying the
205  * unary minus operator to unsigned quantities.
206  */
207 #define SAL_MIN_INT8 ((sal_Int8) (-0x7F - 1))
208 #define SAL_MAX_INT8 ((sal_Int8) 0x7F)
209 #define SAL_MAX_UINT8 ((sal_uInt8) 0xFF)
210 #define SAL_MIN_INT16 ((sal_Int16) (-0x7FFF - 1))
211 #define SAL_MAX_INT16 ((sal_Int16) 0x7FFF)
212 #define SAL_MAX_UINT16 ((sal_uInt16) 0xFFFF)
213 #define SAL_MIN_INT32 ((sal_Int32) (-0x7FFFFFFF - 1))
214 #define SAL_MAX_INT32 ((sal_Int32) 0x7FFFFFFF)
215 #define SAL_MAX_UINT32 ((sal_uInt32) 0xFFFFFFFF)
216 #define SAL_MIN_INT64 ((sal_Int64) (SAL_CONST_INT64(-0x7FFFFFFFFFFFFFFF) - 1))
217 #define SAL_MAX_INT64 ((sal_Int64) SAL_CONST_INT64(0x7FFFFFFFFFFFFFFF))
218 #define SAL_MAX_UINT64 ((sal_uInt64) SAL_CONST_UINT64(0xFFFFFFFFFFFFFFFF))
219 
220 #if SAL_TYPES_SIZEOFPOINTER == 4
221 #define SAL_MAX_SSIZE SAL_MAX_INT32
222 #define SAL_MAX_SIZE SAL_MAX_UINT32
223 #elif SAL_TYPES_SIZEOFPOINTER == 8
224 #define SAL_MAX_SSIZE SAL_MAX_INT64
225 #define SAL_MAX_SIZE SAL_MAX_UINT64
226 #endif
227 
228 #define SAL_MAX_ENUM 0x7fffffff
229 
230 #if defined(_MSC_VER)
231 # define SAL_DLLPUBLIC_EXPORT __declspec(dllexport)
232 # define SAL_JNI_EXPORT __declspec(dllexport)
233 # define SAL_DLLPUBLIC_IMPORT __declspec(dllimport)
234 # define SAL_DLLPRIVATE
235 # define SAL_DLLPUBLIC_TEMPLATE
236 # define SAL_DLLPUBLIC_RTTI
237 # define SAL_CALL __cdecl
238 # define SAL_CALL_ELLIPSE __cdecl
239 #elif defined SAL_UNX
240 # if defined(__GNUC__)
241 # if defined(DISABLE_DYNLOADING)
242 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("hidden")))
243 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
244 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("hidden")))
245 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
246 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("hidden")))
247 # define SAL_DLLPUBLIC_RTTI
248 # else
249 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("default")))
250 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
251 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("default")))
252 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
253 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("default")))
254 # if defined __clang__
255 # if __has_attribute(type_visibility)
256 # define SAL_DLLPUBLIC_RTTI __attribute__ ((type_visibility("default")))
257 # else
258 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
259 # endif
260 # else
261 # define SAL_DLLPUBLIC_RTTI
262 # endif
263 # endif
264 # else
265 # define SAL_DLLPUBLIC_EXPORT
266 # define SAL_JNI_EXPORT
267 # define SAL_DLLPUBLIC_IMPORT
268 # define SAL_DLLPRIVATE
269 # define SAL_DLLPUBLIC_TEMPLATE
270 # define SAL_DLLPUBLIC_RTTI
271 # endif
272 # define SAL_CALL
273 # define SAL_CALL_ELLIPSE
274 #else
275 # error("unknown platform")
276 #endif
277 
284 #if defined(__GNUC__)
285 # if defined(DISABLE_DYNLOADING)
286 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT __attribute__((visibility("default")))
287 # else
288 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT SAL_DLLPUBLIC_EXPORT
289 # endif
290 # define SAL_EXCEPTION_DLLPRIVATE SAL_DLLPRIVATE
291 #else
292 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT
293 # define SAL_EXCEPTION_DLLPRIVATE
294 #endif
295 
302 #if (defined __GNUC__ \
303  && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1))) \
304  || defined __clang__
305 # define SAL_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
306 #else
307 # define SAL_WARN_UNUSED_RESULT
308 #endif
309 
314 #ifdef _MSC_VER
315 # define SAL_NO_VTABLE __declspec(novtable)
316 #else
317 # define SAL_NO_VTABLE
318 #endif
319 
320 #ifdef SAL_W32
321 # pragma pack(push, 8)
322 #endif
323 
327 typedef struct _sal_Sequence
328 {
331  sal_Int32 nRefCount;
334  sal_Int32 nElements;
337  char elements[1];
338 } sal_Sequence;
339 
340 #define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
341 
342 #if defined( SAL_W32)
343 #pragma pack(pop)
344 #endif
345 
346 #if defined __cplusplus
347 
352 #define SAL_THROW_EXTERN_C() throw ()
353 
358 #if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__)
359 # define COVERITY_NOEXCEPT_FALSE noexcept(false)
360 #else
361 # define COVERITY_NOEXCEPT_FALSE
362 #endif
363 
364 #else
365 
366 #define SAL_THROW_EXTERN_C()
367 
368 #endif
369 
370 #ifdef __cplusplus
371 }
372 #endif /* __cplusplus */
373 
374 #ifdef __cplusplus
375 
377 {
381 };
382 
383 namespace com { namespace sun { namespace star { } } }
384 
389 namespace css = ::com::sun::star;
390 
399 #if defined LIBO_INTERNAL_ONLY
400 #define SAL_DELETED_FUNCTION = delete
401 #else
402 #define SAL_DELETED_FUNCTION
403 #endif
404 
412 #if defined LIBO_INTERNAL_ONLY
413 #define SAL_OVERRIDE override
414 #else
415 #define SAL_OVERRIDE
416 #endif
417 
424 #if defined LIBO_INTERNAL_ONLY
425 #define SAL_FINAL final
426 #else
427 #define SAL_FINAL
428 #endif
429 
430 #if defined LIBO_INTERNAL_ONLY
431 #if defined __clang__
432 #define SAL_FALLTHROUGH [[clang::fallthrough]]
433 #elif defined __GNUC__ && __GNUC__ >= 7
434 #define SAL_FALLTHROUGH [[fallthrough]]
435 #else
436 #define SAL_FALLTHROUGH
437 #endif
438 #endif
439 
440 #endif /* __cplusplus */
441 
442 #ifdef __cplusplus
443 
444 namespace sal {
445 
457 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
458  return static_cast< T1 >(n);
459 }
460 
461 }
462 
463 #else /* __cplusplus */
464 
477 #define SAL_INT_CAST(type, expr) ((type) (expr))
478 
479 #endif /* __cplusplus */
480 
486 #if HAVE_GCC_DEPRECATED_MESSAGE
487 # define SAL_DEPRECATED(message) __attribute__((deprecated(message)))
488 #elif defined __GNUC__ || defined __clang__
489 # define SAL_DEPRECATED(message) __attribute__((deprecated))
490 #elif defined(_MSC_VER)
491 # define SAL_DEPRECATED(message) __declspec(deprecated(message))
492 #else
493 # define SAL_DEPRECATED(message)
494 #endif
495 
507 #ifdef LIBO_INTERNAL_ONLY
508 # define SAL_DEPRECATED_INTERNAL(message)
509 #else
510 # define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
511 #endif
512 
520 #if HAVE_GCC_PRAGMA_OPERATOR
521 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
522  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic push)) \
523  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic ignored "-Wdeprecated-declarations"))
524 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
525  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic pop))
526 #else
527 # define SAL_WNODEPRECATED_DECLARATIONS_PUSH
528 # define SAL_WNODEPRECATED_DECLARATIONS_POP
529 #endif
530 
547 #ifdef _MSC_VER
548 #define SAL_WNOUNREACHABLE_CODE_PUSH \
549  __pragma(warning(push)) \
550  __pragma(warning(disable:4702)) \
551  __pragma(warning(disable:4722))
552 #define SAL_WNOUNREACHABLE_CODE_POP \
553  __pragma(warning(pop))
554 #else
555 /* Add definitions for GCC and Clang if needed */
556 #define SAL_WNOUNREACHABLE_CODE_PUSH
557 #define SAL_WNOUNREACHABLE_CODE_POP
558 #endif
559 
583 #if defined __cplusplus
584 #if defined __GNUC__ || defined __clang__
585 #define SAL_UNUSED_PARAMETER __attribute__ ((unused))
586 #else
587 #define SAL_UNUSED_PARAMETER
588 #endif
589 #endif
590 
603 #if HAVE_GCC_ATTRIBUTE_WARN_UNUSED
604 #define SAL_WARN_UNUSED __attribute__((warn_unused))
605 #elif defined __clang__
606 #define SAL_WARN_UNUSED __attribute__((annotate("lo_warn_unused")))
607 #else
608 #define SAL_WARN_UNUSED
609 #endif
610 
612 
613 #if defined __GNUC__ || defined __clang__
614 // Macro to try to catch and warn on assignments inside expr.
615 # define SAL_DETAIL_BOOLEAN_EXPR(expr) \
616  __extension__ ({ \
617  int sal_boolean_var_; \
618  if (expr) \
619  sal_boolean_var_ = 1; \
620  else \
621  sal_boolean_var_ = 0; \
622  sal_boolean_var_; \
623  })
624 
635 # define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
636 
647 # define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
648 
660 # define SAL_HOT __attribute__((hot))
661 
675 # define SAL_COLD __attribute__((cold))
676 #else
677 # define SAL_LIKELY(expr) (expr)
678 # define SAL_UNLIKELY(expr) (expr)
679 # define SAL_HOT
680 # define SAL_COLD
681 #endif
682 
684 
685 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus && defined SAL_W32
686 // Temporary scaffolding for the MSVC sal_Unicode wchar_t -> char16_t change; to
688 // be removed again:
689 inline wchar_t * SAL_W(char16_t * p)
690 { return reinterpret_cast<wchar_t *>(p); }
691 inline wchar_t const * SAL_W(char16_t const * p)
692 { return reinterpret_cast<wchar_t const *>(p); }
693 inline char16_t * SAL_U(wchar_t * p)
694 { return reinterpret_cast<char16_t *>(p); }
695 inline char16_t const * SAL_U(wchar_t const * p)
696 { return reinterpret_cast<char16_t const *>(p); }
698 #endif
699 
701 
710 #ifndef __has_attribute
711 #define __has_attribute(x) 0
712 #endif
713 
714 #if defined LIBO_INTERNAL_ONLY && ((defined __GNUC__ && __GNUC__ > 4) || (defined __clang__ && __has_attribute(returns_nonnull)))
715 #define SAL_RETURNS_NONNULL __attribute__((returns_nonnull))
716 #else
717 #define SAL_RETURNS_NONNULL
718 #endif
719 
721 #endif // INCLUDED_SAL_TYPES_H
722 
723 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
void * sal_Handle
Definition: types.h:145
char sal_Char
A legacy synonym for char.
Definition: types.h:121
unsigned char sal_uChar
A legacy synonym for unsigned char.
Definition: types.h:133
char elements[1]
elements array
Definition: types.h:337
Definition: types.h:444
Definition: types.h:383
Definition: types.h:383
unsigned char sal_Bool
Definition: types.h:39
unsigned char sal_uInt8
Definition: types.h:45
__sal_NoAcquire
Definition: types.h:376
signed char sal_Int8
Definition: types.h:44
sal_uInt16 sal_Unicode
Definition: types.h:142
struct _sal_Sequence sal_Sequence
This is the binary specification of a SAL sequence.
This is the binary specification of a SAL sequence.
Definition: types.h:327
sal_Int32 nRefCount
reference count of sequence
Definition: types.h:331
definition of a no acquire enum for ctors
Definition: types.h:380
sal_Int32 nElements
element count
Definition: types.h:334
signed char sal_sChar
A legacy synonym for signed char.
Definition: types.h:127
T1 static_int_cast(T2 n)
A static_cast between integral types, to avoid C++ compiler warnings.
Definition: types.h:457