LibreOffice
LibreOffice 7.1 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 typedef unsigned char sal_Bool;
35 # define sal_False ((sal_Bool)0)
36 # define sal_True ((sal_Bool)1)
37 
38 /* char is assumed to always be 1 byte long */
39 typedef signed char sal_Int8;
40 typedef unsigned char sal_uInt8;
41 
42 #if SAL_TYPES_SIZEOFSHORT == 2
43  typedef signed short sal_Int16;
44  typedef unsigned short sal_uInt16;
45 #else
46  #error "Could not find 16-bit type, add support for your architecture"
47 #endif
48 
49 #if SAL_TYPES_SIZEOFLONG == 4
50  typedef signed long sal_Int32;
51  typedef unsigned long sal_uInt32;
52  #define SAL_PRIdINT32 "ld"
53  #define SAL_PRIuUINT32 "lu"
54  #define SAL_PRIxUINT32 "lx"
55  #define SAL_PRIXUINT32 "lX"
56 #elif SAL_TYPES_SIZEOFINT == 4
57  typedef signed int sal_Int32;
58  typedef unsigned int sal_uInt32;
59  #define SAL_PRIdINT32 "d"
60  #define SAL_PRIuUINT32 "u"
61  #define SAL_PRIxUINT32 "x"
62  #define SAL_PRIXUINT32 "X"
63 #else
64  #error "Could not find 32-bit type, add support for your architecture"
65 #endif
66 
67 #ifdef _MSC_VER
68  typedef __int64 sal_Int64;
69  typedef unsigned __int64 sal_uInt64;
70 
71  /* The following are macros that will add the 64 bit constant suffix. */
72  #define SAL_CONST_INT64(x) x##i64
73  #define SAL_CONST_UINT64(x) x##ui64
74 
75  #define SAL_PRIdINT64 "I64d"
76  #define SAL_PRIuUINT64 "I64u"
77  #define SAL_PRIxUINT64 "I64x"
78  #define SAL_PRIXUINT64 "I64X"
79 #elif defined (__GNUC__)
80  #if SAL_TYPES_SIZEOFLONG == 8
81  typedef signed long int sal_Int64;
82  typedef unsigned long int sal_uInt64;
83 
84 
85  /* The following are macros that will add the 64 bit constant suffix. */
86  #define SAL_CONST_INT64(x) x##l
87  #define SAL_CONST_UINT64(x) x##ul
88 
89  #define SAL_PRIdINT64 "ld"
90  #define SAL_PRIuUINT64 "lu"
91  #define SAL_PRIxUINT64 "lx"
92  #define SAL_PRIXUINT64 "lX"
93  #elif SAL_TYPES_SIZEOFLONGLONG == 8
94  typedef signed long long sal_Int64;
95  typedef unsigned long long sal_uInt64;
96 
97  /* The following are macros that will add the 64 bit constant suffix. */
98  #define SAL_CONST_INT64(x) x##ll
99  #define SAL_CONST_UINT64(x) x##ull
100 
101  #define SAL_PRIdINT64 "lld"
102  #define SAL_PRIuUINT64 "llu"
103  #define SAL_PRIxUINT64 "llx"
104  #define SAL_PRIXUINT64 "llX"
105  #else
106  #error "Could not find 64-bit type, add support for your architecture"
107  #endif
108 #else
109  #error "Please define the 64-bit types for your architecture/compiler in include/sal/types.h"
110 #endif
111 
112 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
113  #define SAL_UNICODE_NOTEQUAL_WCHAR_T
114  typedef char16_t sal_Unicode;
115 #elif defined(_WIN32)
116  typedef wchar_t sal_Unicode;
117 #else
118  #define SAL_UNICODE_NOTEQUAL_WCHAR_T
119  typedef sal_uInt16 sal_Unicode;
120 #endif
121 
122 typedef void * sal_Handle;
123 
124 /* sal_Size should currently be the native width of the platform */
125 #if SAL_TYPES_SIZEOFPOINTER == 4
126  typedef sal_uInt32 sal_Size;
127  typedef sal_Int32 sal_sSize;
128 #elif SAL_TYPES_SIZEOFPOINTER == 8
129  typedef sal_uInt64 sal_Size;
130  typedef sal_Int64 sal_sSize;
131 #else
132  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
133 #endif
134 
135 /* sal_PtrDiff holds the result of a pointer subtraction */
136 #if SAL_TYPES_SIZEOFPOINTER == 4
137  typedef sal_Int32 sal_PtrDiff;
138 #elif SAL_TYPES_SIZEOFPOINTER == 8
139  typedef sal_Int64 sal_PtrDiff;
140 #else
141  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
142 #endif
143 
144 /* printf-style conversion specification length modifiers for size_t and
145  ptrdiff_t (most platforms support C99, MSC has its own extension) */
146 #if defined(_MSC_VER)
147  #define SAL_PRI_SIZET "I"
148  #define SAL_PRI_PTRDIFFT "I"
149 #else
150  #define SAL_PRI_SIZET "z"
151  #define SAL_PRI_PTRDIFFT "t"
152 #endif
153 
154 /* sal_IntPtr, sal_uIntPtr are integer types designed to hold pointers so that any valid
155  * pointer to void can be converted to this type and back to a pointer to void and the
156  * result will compare to the original pointer */
157 #if SAL_TYPES_SIZEOFPOINTER == 4
158  typedef sal_Int32 sal_IntPtr;
159  typedef sal_uInt32 sal_uIntPtr;
160  #define SAL_PRIdINTPTR SAL_PRIdINT32
161  #define SAL_PRIuUINTPTR SAL_PRIuUINT32
162  #define SAL_PRIxUINTPTR SAL_PRIxUINT32
163  #define SAL_PRIXUINTPTR SAL_PRIXUINT32
164 #elif SAL_TYPES_SIZEOFPOINTER == 8
165  typedef sal_Int64 sal_IntPtr;
166  typedef sal_uInt64 sal_uIntPtr;
167  #define SAL_PRIdINTPTR SAL_PRIdINT64
168  #define SAL_PRIuUINTPTR SAL_PRIuUINT64
169  #define SAL_PRIxUINTPTR SAL_PRIxUINT64
170  #define SAL_PRIXUINTPTR SAL_PRIXUINT64
171 #else
172  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
173 #endif
174 
175 /* The following SAL_MIN_INTn defines codify the assumption that the signed
176  * sal_Int types use two's complement representation. Defining them as
177  * "-0x7F... - 1" instead of as "-0x80..." prevents warnings about applying the
178  * unary minus operator to unsigned quantities.
179  */
180 #define SAL_MIN_INT8 ((sal_Int8) (-0x7F - 1))
181 #define SAL_MAX_INT8 ((sal_Int8) 0x7F)
182 #define SAL_MAX_UINT8 ((sal_uInt8) 0xFF)
183 #define SAL_MIN_INT16 ((sal_Int16) (-0x7FFF - 1))
184 #define SAL_MAX_INT16 ((sal_Int16) 0x7FFF)
185 #define SAL_MAX_UINT16 ((sal_uInt16) 0xFFFF)
186 #define SAL_MIN_INT32 ((sal_Int32) (-0x7FFFFFFF - 1))
187 #define SAL_MAX_INT32 ((sal_Int32) 0x7FFFFFFF)
188 #define SAL_MAX_UINT32 ((sal_uInt32) 0xFFFFFFFF)
189 #define SAL_MIN_INT64 ((sal_Int64) (SAL_CONST_INT64(-0x7FFFFFFFFFFFFFFF) - 1))
190 #define SAL_MAX_INT64 ((sal_Int64) SAL_CONST_INT64(0x7FFFFFFFFFFFFFFF))
191 #define SAL_MAX_UINT64 ((sal_uInt64) SAL_CONST_UINT64(0xFFFFFFFFFFFFFFFF))
192 
193 #if SAL_TYPES_SIZEOFPOINTER == 4
194 #define SAL_MAX_SSIZE SAL_MAX_INT32
195 #define SAL_MAX_SIZE SAL_MAX_UINT32
196 #elif SAL_TYPES_SIZEOFPOINTER == 8
197 #define SAL_MAX_SSIZE SAL_MAX_INT64
198 #define SAL_MAX_SIZE SAL_MAX_UINT64
199 #endif
200 
201 #define SAL_MAX_ENUM 0x7fffffff
202 
203 #if defined(_MSC_VER)
204 # define SAL_DLLPUBLIC_EXPORT __declspec(dllexport)
205 # define SAL_JNI_EXPORT __declspec(dllexport)
206 # define SAL_DLLPUBLIC_IMPORT __declspec(dllimport)
207 # define SAL_DLLPRIVATE
208 # define SAL_DLLPUBLIC_TEMPLATE
209 # define SAL_DLLPUBLIC_RTTI
210 # define SAL_CALL __cdecl
211 #elif defined SAL_UNX
212 # if defined(__GNUC__)
213 # if defined(DISABLE_DYNLOADING)
214 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("hidden")))
215 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
216 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("hidden")))
217 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
218 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("hidden")))
219 # define SAL_DLLPUBLIC_RTTI
220 # else
221 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("default")))
222 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
223 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("default")))
224 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
225 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("default")))
226 # if defined __clang__
227 # if __has_attribute(type_visibility)
228 # define SAL_DLLPUBLIC_RTTI __attribute__ ((type_visibility("default")))
229 # else
230 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
231 # endif
232 # else
233 # define SAL_DLLPUBLIC_RTTI
234 # endif
235 # endif
236 # else
237 # define SAL_DLLPUBLIC_EXPORT
238 # define SAL_JNI_EXPORT
239 # define SAL_DLLPUBLIC_IMPORT
240 # define SAL_DLLPRIVATE
241 # define SAL_DLLPUBLIC_TEMPLATE
242 # define SAL_DLLPUBLIC_RTTI
243 # endif
244 # define SAL_CALL
245 #else
246 # error("unknown platform")
247 #endif
248 
255 #if defined(__GNUC__)
256 # if defined(DISABLE_DYNLOADING)
257 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT __attribute__((visibility("default")))
258 # else
259 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT SAL_DLLPUBLIC_EXPORT
260 # endif
261 # define SAL_EXCEPTION_DLLPRIVATE SAL_DLLPRIVATE
262 #else
263 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT
264 # define SAL_EXCEPTION_DLLPRIVATE
265 #endif
266 
273 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
274 #define SAL_WARN_UNUSED_RESULT [[nodiscard]]
275 #elif (defined __GNUC__ \
276  && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1))) \
277  || defined __clang__
278 # define SAL_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
279 #else
280 # define SAL_WARN_UNUSED_RESULT
281 #endif
282 
287 #ifdef _MSC_VER
288 # define SAL_NO_VTABLE __declspec(novtable)
289 #else
290 # define SAL_NO_VTABLE
291 #endif
292 
293 #ifdef _WIN32
294 # pragma pack(push, 8)
295 #endif
296 
299 typedef struct _sal_Sequence
300 {
303  sal_Int32 nRefCount;
306  sal_Int32 nElements;
309  char elements[1];
311 
312 #define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
313 
314 #if defined( _WIN32)
315 #pragma pack(pop)
316 #endif
317 
318 #if defined __cplusplus
319 
324 #define SAL_THROW_EXTERN_C() throw ()
325 
330 #if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__)
331 # define COVERITY_NOEXCEPT_FALSE noexcept(false)
332 #else
333 # define COVERITY_NOEXCEPT_FALSE
334 #endif
335 
336 #else
337 
338 #define SAL_THROW_EXTERN_C()
339 
340 #endif
341 
342 #ifdef __cplusplus
343 }
344 #endif /* __cplusplus */
345 
346 #ifdef __cplusplus
347 
349 {
353 };
354 
355 namespace com { namespace sun { namespace star { } } }
356 
361 namespace css = ::com::sun::star;
362 
371 #if defined LIBO_INTERNAL_ONLY
372 #define SAL_DELETED_FUNCTION = delete
373 #else
374 #define SAL_DELETED_FUNCTION
375 #endif
376 
384 #if defined LIBO_INTERNAL_ONLY
385 #define SAL_OVERRIDE override
386 #else
387 #define SAL_OVERRIDE
388 #endif
389 
390 #endif /* __cplusplus */
391 
392 #ifdef __cplusplus
393 
394 namespace sal {
395 
407 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
408  return static_cast< T1 >(n);
409 }
410 
411 }
412 
413 #else /* __cplusplus */
414 
427 #define SAL_INT_CAST(type, expr) ((type) (expr))
428 
429 #endif /* __cplusplus */
430 
436 #if defined __GNUC__ || defined __clang__
437 #if defined LIBO_INTERNAL_ONLY
438 # define SAL_DEPRECATED(message) __attribute__((deprecated(message)))
439 #else
440 # define SAL_DEPRECATED(message) __attribute__((deprecated))
441 #endif
442 #elif defined(_MSC_VER)
443 # define SAL_DEPRECATED(message) __declspec(deprecated(message))
444 #else
445 # define SAL_DEPRECATED(message)
446 #endif
447 
459 #ifdef LIBO_INTERNAL_ONLY
460 # define SAL_DEPRECATED_INTERNAL(message)
461 #else
462 # define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
463 #endif
464 
472 #if defined LIBO_INTERNAL_ONLY && defined __GNUC__
473 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
474  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic push)) \
475  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic ignored "-Wdeprecated-declarations"))
476 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
477  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic pop))
478 #else
479 # define SAL_WNODEPRECATED_DECLARATIONS_PUSH
480 # define SAL_WNODEPRECATED_DECLARATIONS_POP
481 #endif
482 
499 #ifdef _MSC_VER
500 #define SAL_WNOUNREACHABLE_CODE_PUSH \
501  __pragma(warning(push)) \
502  __pragma(warning(disable:4702)) \
503  __pragma(warning(disable:4722))
504 #define SAL_WNOUNREACHABLE_CODE_POP \
505  __pragma(warning(pop))
506 #else
507 /* Add definitions for GCC and Clang if needed */
508 #define SAL_WNOUNREACHABLE_CODE_PUSH
509 #define SAL_WNOUNREACHABLE_CODE_POP
510 #endif
511 
535 #if defined __cplusplus
536 #if defined __GNUC__ || defined __clang__
537 #define SAL_UNUSED_PARAMETER __attribute__ ((unused))
538 #else
539 #define SAL_UNUSED_PARAMETER
540 #endif
541 #endif
542 
555 #if defined LIBO_INTERNAL_ONLY && (defined __GNUC__ || defined __clang__)
556 #define SAL_WARN_UNUSED __attribute__((warn_unused))
557 #else
558 #define SAL_WARN_UNUSED
559 #endif
560 
562 
563 #if defined __GNUC__ || defined __clang__
564 // Macro to try to catch and warn on assignments inside expr.
565 # define SAL_DETAIL_BOOLEAN_EXPR(expr) \
566  __extension__ ({ \
567  int sal_boolean_var_; \
568  if (expr) \
569  sal_boolean_var_ = 1; \
570  else \
571  sal_boolean_var_ = 0; \
572  sal_boolean_var_; \
573  })
574 
585 # define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
586 
597 # define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
598 
610 # define SAL_HOT __attribute__((hot))
611 
625 # define SAL_COLD __attribute__((cold))
626 #else
627 # define SAL_LIKELY(expr) (expr)
628 # define SAL_UNLIKELY(expr) (expr)
629 # define SAL_HOT
630 # define SAL_COLD
631 #endif
632 
634 
636 
645 #ifndef __has_attribute
646 #define __has_attribute(x) 0
647 #endif
648 
649 #if defined LIBO_INTERNAL_ONLY && ((defined __GNUC__ && !defined __clang__) || (defined __clang__ && __has_attribute(returns_nonnull)))
650 #define SAL_RETURNS_NONNULL __attribute__((returns_nonnull))
651 #else
652 #define SAL_RETURNS_NONNULL
653 #endif
655 
656 #endif // INCLUDED_SAL_TYPES_H
657 
658 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
__sal_NoAcquire
Definition: types.h:349
@ SAL_NO_ACQUIRE
definition of a no acquire enum for ctors
Definition: types.h:352
unsigned char sal_uInt8
Definition: types.h:40
struct _sal_Sequence sal_Sequence
This is the binary specification of a SAL sequence.
unsigned char sal_Bool
Definition: types.h:34
sal_uInt16 sal_Unicode
Definition: types.h:119
void * sal_Handle
Definition: types.h:122
signed char sal_Int8
Definition: types.h:39
Definition: types.h:355
Definition: types.h:355
Definition: types.h:394
T1 static_int_cast(T2 n)
A static_cast between integral types, to avoid C++ compiler warnings.
Definition: types.h:407
This is the binary specification of a SAL sequence.
Definition: types.h:300
sal_Int32 nRefCount
reference count of sequence
Definition: types.h:303
sal_Int32 nElements
element count
Definition: types.h:306
char elements[1]
elements array
Definition: types.h:309