source: rtems-docs/c-user/config/posix-api.rst @ d5509d6

Last change on this file since d5509d6 was 9ba26e7, checked in by Joel Sherrill <joel@…>, on 05/20/22 at 13:45:16

c-user: Update references to --enable-* configure options.

Also updated list of SMP architectures and added enough lead in
to let users know the source code was the definitive answer.

  • Property mode set to 100644
File size: 15.7 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
4.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
5
6.. This file is part of the RTEMS quality process and was automatically
7.. generated.  If you find something that needs to be fixed or
8.. worded better please post a report or patch to an RTEMS mailing list
9.. or raise a bug report:
10..
11.. https://www.rtems.org/bugs.html
12..
13.. For information on updating and regenerating please refer to the How-To
14.. section in the Software Requirements Engineering chapter of the
15.. RTEMS Software Engineering manual.  The manual is provided as a part of
16.. a release.  For development sources please refer to the online
17.. documentation at:
18..
19.. https://docs.rtems.org
20
21.. Generated from spec:/acfg/if/group-posix
22
23POSIX API Configuration
24=======================
25
26This section describes configuration options related to the POSIX API.  Most
27POSIX API objects are available by default since RTEMS 5.1.  The queued signals
28and timers are only available if RTEMS was built with the enable POSIX
29build configuration option.
30
31.. Generated from spec:/acfg/if/max-posix-keys
32
33.. raw:: latex
34
35    \clearpage
36
37.. index:: CONFIGURE_MAXIMUM_POSIX_KEYS
38
39.. _CONFIGURE_MAXIMUM_POSIX_KEYS:
40
41CONFIGURE_MAXIMUM_POSIX_KEYS
42----------------------------
43
44.. rubric:: CONSTANT:
45
46``CONFIGURE_MAXIMUM_POSIX_KEYS``
47
48.. rubric:: OPTION TYPE:
49
50This configuration option is an integer define.
51
52.. rubric:: DEFAULT VALUE:
53
54The default value is 0.
55
56.. rubric:: DESCRIPTION:
57
58The value of this configuration option defines the maximum number of POSIX
59API Keys that can be concurrently active.
60
61.. rubric:: NOTES:
62
63This object class can be configured in unlimited allocation mode, see
64:ref:`ConfigUnlimitedObjects`.
65
66.. rubric:: CONSTRAINTS:
67
68The following constraints apply to this configuration option:
69
70* The value of the configuration option shall be greater than or equal to zero.
71
72* The value of the configuration option shall be less than or equal to 65535.
73
74* The value of the configuration option shall be less than or equal to a
75  BSP-specific and application-specific value which depends on the size of the
76  memory available to the application.
77
78* The value of the configuration option may be defined through
79  :c:func:`rtems_resource_unlimited` the enable unlimited objects for the
80  object class, if the value passed to :c:func:`rtems_resource_unlimited`
81  satisfies all other constraints of the configuration option.
82
83.. Generated from spec:/acfg/if/max-posix-key-value-pairs
84
85.. raw:: latex
86
87    \clearpage
88
89.. index:: CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS
90
91.. _CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS:
92
93CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS
94---------------------------------------
95
96.. rubric:: CONSTANT:
97
98``CONFIGURE_MAXIMUM_POSIX_KEY_VALUE_PAIRS``
99
100.. rubric:: OPTION TYPE:
101
102This configuration option is an integer define.
103
104.. rubric:: DEFAULT VALUE:
105
106The default value is
107:ref:`CONFIGURE_MAXIMUM_POSIX_KEYS` *
108( :ref:`CONFIGURE_MAXIMUM_TASKS` +
109:ref:`CONFIGURE_MAXIMUM_POSIX_THREADS` ).
110
111.. rubric:: DESCRIPTION:
112
113The value of this configuration option defines the maximum number of key
114value pairs used by POSIX API Keys that can be concurrently active.
115
116.. rubric:: NOTES:
117
118This object class can be configured in unlimited allocation mode, see
119:ref:`ConfigUnlimitedObjects`.
120
121A key value pair is created by :c:func:`pthread_setspecific` if the value
122is not `NULL <https://en.cppreference.com/w/c/types/NULL>`_, otherwise it is deleted.
123
124.. rubric:: CONSTRAINTS:
125
126The following constraints apply to this configuration option:
127
128* The value of the configuration option shall be greater than or equal to zero.
129
130* The value of the configuration option shall be less than or equal to 65535.
131
132* The value of the configuration option shall be less than or equal to a
133  BSP-specific and application-specific value which depends on the size of the
134  memory available to the application.
135
136* The value of the configuration option may be defined through
137  :c:func:`rtems_resource_unlimited` the enable unlimited objects for the
138  object class, if the value passed to :c:func:`rtems_resource_unlimited`
139  satisfies all other constraints of the configuration option.
140
141.. Generated from spec:/acfg/if/max-posix-message-queues
142
143.. raw:: latex
144
145    \clearpage
146
147.. index:: CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
148
149.. _CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES:
150
151CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES
152--------------------------------------
153
154.. rubric:: CONSTANT:
155
156``CONFIGURE_MAXIMUM_POSIX_MESSAGE_QUEUES``
157
158.. rubric:: OPTION TYPE:
159
160This configuration option is an integer define.
161
162.. rubric:: DEFAULT VALUE:
163
164The default value is 0.
165
166.. rubric:: DESCRIPTION:
167
168The value of this configuration option defines the maximum number of POSIX
169API Message Queues that can be concurrently active.
170
171.. rubric:: NOTES:
172
173This object class can be configured in unlimited allocation mode, see
174:ref:`ConfigUnlimitedObjects`.  You have to account for the memory used to
175store the messages of each message queue, see
176:ref:`CONFIGURE_MESSAGE_BUFFER_MEMORY`.
177
178.. rubric:: CONSTRAINTS:
179
180The following constraints apply to this configuration option:
181
182* The value of the configuration option shall be greater than or equal to zero.
183
184* The value of the configuration option shall be less than or equal to 65535.
185
186* The value of the configuration option shall be less than or equal to a
187  BSP-specific and application-specific value which depends on the size of the
188  memory available to the application.
189
190* The value of the configuration option shall be small enough so that the RTEMS
191  Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not
192  overflow an integer of type `uintptr_t
193  <https://en.cppreference.com/w/c/types/integer>`_.
194
195* The value of the configuration option may be defined through
196  :c:func:`rtems_resource_unlimited` the enable unlimited objects for the
197  object class, if the value passed to :c:func:`rtems_resource_unlimited`
198  satisfies all other constraints of the configuration option.
199
200.. Generated from spec:/acfg/if/max-posix-queued-signals
201
202.. raw:: latex
203
204    \clearpage
205
206.. index:: CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
207
208.. _CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS:
209
210CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS
211--------------------------------------
212
213.. rubric:: CONSTANT:
214
215``CONFIGURE_MAXIMUM_POSIX_QUEUED_SIGNALS``
216
217.. rubric:: OPTION TYPE:
218
219This configuration option is an integer define.
220
221.. rubric:: DEFAULT VALUE:
222
223The default value is 0.
224
225.. rubric:: DESCRIPTION:
226
227The value of this configuration option defines the maximum number of POSIX
228API Queued Signals that can be concurrently active.
229
230.. rubric:: NOTES:
231
232Unlimited objects are not available for queued signals.
233
234Queued signals are only available if RTEMS was built with the POSIX API
235build configuration option enabled.
236
237.. rubric:: CONSTRAINTS:
238
239The following constraints apply to this configuration option:
240
241* The value of the configuration option shall be greater than or equal to zero.
242
243* The value of the configuration option shall be less than or equal to a
244  BSP-specific and application-specific value which depends on the size of the
245  memory available to the application.
246
247* The value of the configuration option shall be small enough so that the RTEMS
248  Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not
249  overflow an integer of type `uintptr_t
250  <https://en.cppreference.com/w/c/types/integer>`_.
251
252* The value of the configuration option shall be zero if the POSIX API is not
253  enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True`` build
254  configuration option).  Otherwise a compile time error in the configuration
255  file will occur.
256
257.. Generated from spec:/acfg/if/max-posix-semaphores
258
259.. raw:: latex
260
261    \clearpage
262
263.. index:: CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
264
265.. _CONFIGURE_MAXIMUM_POSIX_SEMAPHORES:
266
267CONFIGURE_MAXIMUM_POSIX_SEMAPHORES
268----------------------------------
269
270.. rubric:: CONSTANT:
271
272``CONFIGURE_MAXIMUM_POSIX_SEMAPHORES``
273
274.. rubric:: OPTION TYPE:
275
276This configuration option is an integer define.
277
278.. rubric:: DEFAULT VALUE:
279
280The default value is 0.
281
282.. rubric:: DESCRIPTION:
283
284The value of this configuration option defines the maximum number of POSIX
285API Named Semaphores that can be concurrently active.
286
287.. rubric:: NOTES:
288
289This object class can be configured in unlimited allocation mode, see
290:ref:`ConfigUnlimitedObjects`.
291
292Named semaphores are created with :c:func:`sem_open`.  Semaphores
293initialized with :c:func:`sem_init` are not affected by this
294configuration option since the storage space for these semaphores is
295user-provided.
296
297.. rubric:: CONSTRAINTS:
298
299The following constraints apply to this configuration option:
300
301* The value of the configuration option shall be greater than or equal to zero.
302
303* The value of the configuration option shall be less than or equal to 65535.
304
305* The value of the configuration option shall be less than or equal to a
306  BSP-specific and application-specific value which depends on the size of the
307  memory available to the application.
308
309* The value of the configuration option shall be small enough so that the RTEMS
310  Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not
311  overflow an integer of type `uintptr_t
312  <https://en.cppreference.com/w/c/types/integer>`_.
313
314* The value of the configuration option may be defined through
315  :c:func:`rtems_resource_unlimited` the enable unlimited objects for the
316  object class, if the value passed to :c:func:`rtems_resource_unlimited`
317  satisfies all other constraints of the configuration option.
318
319.. Generated from spec:/acfg/if/max-posix-shms
320
321.. raw:: latex
322
323    \clearpage
324
325.. index:: CONFIGURE_MAXIMUM_POSIX_SHMS
326
327.. _CONFIGURE_MAXIMUM_POSIX_SHMS:
328
329CONFIGURE_MAXIMUM_POSIX_SHMS
330----------------------------
331
332.. rubric:: CONSTANT:
333
334``CONFIGURE_MAXIMUM_POSIX_SHMS``
335
336.. rubric:: OPTION TYPE:
337
338This configuration option is an integer define.
339
340.. rubric:: DEFAULT VALUE:
341
342The default value is 0.
343
344.. rubric:: DESCRIPTION:
345
346The value of this configuration option defines the maximum number of POSIX
347API Shared Memory objects that can be concurrently active.
348
349.. rubric:: NOTES:
350
351This object class can be configured in unlimited allocation mode, see
352:ref:`ConfigUnlimitedObjects`.
353
354.. rubric:: CONSTRAINTS:
355
356The following constraints apply to this configuration option:
357
358* The value of the configuration option shall be greater than or equal to zero.
359
360* The value of the configuration option shall be less than or equal to 65535.
361
362* The value of the configuration option shall be less than or equal to a
363  BSP-specific and application-specific value which depends on the size of the
364  memory available to the application.
365
366* The value of the configuration option shall be small enough so that the RTEMS
367  Workspace size calculation carried out by ``<rtems/confdefs.h>`` does not
368  overflow an integer of type `uintptr_t
369  <https://en.cppreference.com/w/c/types/integer>`_.
370
371* The value of the configuration option may be defined through
372  :c:func:`rtems_resource_unlimited` the enable unlimited objects for the
373  object class, if the value passed to :c:func:`rtems_resource_unlimited`
374  satisfies all other constraints of the configuration option.
375
376.. Generated from spec:/acfg/if/max-posix-threads
377
378.. raw:: latex
379
380    \clearpage
381
382.. index:: CONFIGURE_MAXIMUM_POSIX_THREADS
383
384.. _CONFIGURE_MAXIMUM_POSIX_THREADS:
385
386CONFIGURE_MAXIMUM_POSIX_THREADS
387-------------------------------
388
389.. rubric:: CONSTANT:
390
391``CONFIGURE_MAXIMUM_POSIX_THREADS``
392
393.. rubric:: OPTION TYPE:
394
395This configuration option is an integer define.
396
397.. rubric:: DEFAULT VALUE:
398
399The default value is 0.
400
401.. rubric:: DESCRIPTION:
402
403The value of this configuration option defines the maximum number of POSIX
404API Threads that can be concurrently active.
405
406.. rubric:: NOTES:
407
408This object class can be configured in unlimited allocation mode, see
409:ref:`ConfigUnlimitedObjects`.
410
411This calculations for the required memory in the RTEMS Workspace for threads
412assume that each thread has a minimum stack size and has floating point
413support enabled.  The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used
414to specify thread stack requirements **above** the minimum size required.
415
416The maximum number of Classic API Tasks is specified by
417:ref:`CONFIGURE_MAXIMUM_TASKS`.
418
419All POSIX threads have floating point enabled.
420
421.. rubric:: CONSTRAINTS:
422
423The following constraints apply to this configuration option:
424
425* The value of the configuration option shall be greater than or equal to zero.
426
427* The value of the configuration option shall be less than or equal to 65535.
428
429* The value of the configuration option shall be less than or equal to a
430  BSP-specific and application-specific value which depends on the size of the
431  memory available to the application.
432
433* The value of the configuration option shall be small enough so that the task
434  stack space calculation carried out by ``<rtems/confdefs.h>`` does not
435  overflow an integer of type `uintptr_t
436  <https://en.cppreference.com/w/c/types/integer>`_.
437
438.. Generated from spec:/acfg/if/max-posix-timers
439
440.. raw:: latex
441
442    \clearpage
443
444.. index:: CONFIGURE_MAXIMUM_POSIX_TIMERS
445
446.. _CONFIGURE_MAXIMUM_POSIX_TIMERS:
447
448CONFIGURE_MAXIMUM_POSIX_TIMERS
449------------------------------
450
451.. rubric:: CONSTANT:
452
453``CONFIGURE_MAXIMUM_POSIX_TIMERS``
454
455.. rubric:: OPTION TYPE:
456
457This configuration option is an integer define.
458
459.. rubric:: DEFAULT VALUE:
460
461The default value is 0.
462
463.. rubric:: DESCRIPTION:
464
465The value of this configuration option defines the maximum number of POSIX
466API Timers that can be concurrently active.
467
468.. rubric:: NOTES:
469
470This object class can be configured in unlimited allocation mode, see
471:ref:`ConfigUnlimitedObjects`.
472
473Timers are only available if RTEMS was built with the POSIX API build
474configuration option enabled.
475
476.. rubric:: CONSTRAINTS:
477
478The following constraints apply to this configuration option:
479
480* The value of the configuration option shall be greater than or equal
481to zero.
482
483* The value of the configuration option shall be less than or equal
484to 65535.
485
486* The value of the configuration option shall be less than or equal to a
487  BSP-specific and application-specific value which depends on the size
488  of the memory available to the application.
489
490* The value of the configuration option may be defined through
491  :c:func:`rtems_resource_unlimited` the enable unlimited objects for the
492  object class, if the value passed to :c:func:`rtems_resource_unlimited`
493  satisfies all other constraints of the configuration option.
494
495* The value of the configuration option shall be zero if the POSIX API
496is not
497  enabled (e.g. RTEMS was built without the ``RTEMS_POSIX_API = True``
498  build configuration option).  Otherwise a compile time error in the
499  configuration
500  file will occur.
501
502.. Generated from spec:/acfg/if/min-posix-thread-stack-size
503
504.. raw:: latex
505
506    \clearpage
507
508.. index:: CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE
509.. index:: minimum POSIX thread stack size
510
511.. _CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE:
512
513CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE
514-----------------------------------------
515
516.. rubric:: CONSTANT:
517
518``CONFIGURE_MINIMUM_POSIX_THREAD_STACK_SIZE``
519
520.. rubric:: OPTION TYPE:
521
522This configuration option is an integer define.
523
524.. rubric:: DEFAULT VALUE:
525
526The default value is two times the value of
527:ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE`.
528
529.. rubric:: DESCRIPTION:
530
531The value of this configuration option defines the minimum stack size in
532bytes for every POSIX thread in the system.
533
534.. rubric:: CONSTRAINTS:
535
536The following constraints apply to this configuration option:
537
538* The value of the configuration option shall be small enough so that the task
539  stack space calculation carried out by ``<rtems/confdefs.h>`` does not
540  overflow an integer of type `uintptr_t
541  <https://en.cppreference.com/w/c/types/integer>`_.
542
543* The value of the configuration option shall be greater than or equal to a
544  BSP-specific and application-specific minimum value.
Note: See TracBrowser for help on using the repository browser.