Changeset fa70fd2 in rtems-docs


Ignore:
Timestamp:
Feb 26, 2016, 7:22:07 AM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
1ea5fb7
Parents:
238bf99
git-author:
Chris Johns <chrisj@…> (02/26/16 07:22:07)
git-committer:
Amar Takhar <verm@…> (05/03/16 00:51:26)
Message:

POSIX User clean up.

Location:
posix_users
Files:
23 edited

Legend:

Unmodified
Added
Removed
  • posix_users/clock.rst

    r238bf99 rfa70fd2  
     1.. COMMENT: This is the chapter from the RTEMS POSIX 1003.1b API User's Guide that
     2.. COMMENT: documents the services provided by the timer @c  manager.
     3
    14Clock Manager
    25#############
     
    58============
    69
    7 The clock manager provides services two primary classes
    8 of services.  The first focuses on obtaining and setting
    9 the current date and time.  The other category of services
    10 focus on allowing a thread to delay for a specific length
    11 of time.
     10The clock manager provides services two primary classes of services.  The first
     11focuses on obtaining and setting the current date and time.  The other category
     12of services focus on allowing a thread to delay for a specific length of time.
    1213
    1314The directives provided by the clock manager are:
    1415
    15 - ``clock_gettime`` - Obtain Time of Day
    16 
    17 - ``clock_settime`` - Set Time of Day
    18 
    19 - ``clock_getres`` - Get Clock Resolution
    20 
    21 - ``sleep`` - Delay Process Execution
    22 
    23 - ``usleep`` - Delay Process Execution in Microseconds
    24 
    25 - ``nanosleep`` - Delay with High Resolution
    26 
    27 - ``gettimeofday`` - Get the Time of Day
    28 
    29 - ``time`` - Get time in seconds
     16- clock_gettime_ - Obtain Time of Day
     17
     18- clock_settime_ - Set Time of Day
     19
     20- clock_getres_ - Get Clock Resolution
     21
     22- sleep_ - Delay Process Execution
     23
     24- usleep_ - Delay Process Execution in Microseconds
     25
     26- nanosleep_ - Delay with High Resolution
     27
     28- gettimeofday_ - Get the Time of Day
     29
     30- time_ - Get time in seconds
    3031
    3132Background
     
    4243==========
    4344
    44 This section details the clock manager's directives.
    45 A subsection is dedicated to each of this manager's directives
    46 and describes the calling sequence, related constants, usage,
    47 and status codes.
     45This section details the clock manager's directives.  A subsection is dedicated
     46to each of this manager's directives and describes the calling sequence,
     47related constants, usage, and status codes.
     48
     49.. _clock_gettime:
    4850
    4951clock_gettime - Obtain Time of Day
     
    5456**CALLING SEQUENCE:**
    5557
    56 .. code:: c
     58.. code-block:: c
    5759
    5860    #include <time.h>
    5961    int clock_gettime(
    60     clockid_t        clock_id,
    61     struct timespec \*tp
    62     );
    63 
    64 **STATUS CODES:**
    65 
    66 On error, this routine returns -1 and sets errno to one of the following:
    67 
    68 *EINVAL*
    69     The tp pointer parameter is invalid.
    70 
    71 *EINVAL*
    72     The clock_id specified is invalid.
     62        clockid_t        clock_id,
     63        struct timespec *tp
     64    );
     65
     66**STATUS CODES:**
     67
     68On error, this routine returns -1 and sets ``errno`` to one of the following:
     69
     70.. list-table::
     71 :class: rtems-table
     72
     73 * - ``EINVAL``
     74   - The tp pointer parameter is invalid.
     75 * - ``EINVAL``
     76   - The clock_id specified is invalid.
    7377
    7478**DESCRIPTION:**
     
    7781
    7882NONE
     83
     84.. _clock_settime:
    7985
    8086clock_settime - Set Time of Day
     
    8591**CALLING SEQUENCE:**
    8692
    87 .. code:: c
     93.. code-block:: c
    8894
    8995    #include <time.h>
    9096    int clock_settime(
    91     clockid_t              clock_id,
    92     const struct timespec \*tp
    93     );
    94 
    95 **STATUS CODES:**
    96 
    97 On error, this routine returns -1 and sets errno to one of the following:
    98 
    99 *EINVAL*
    100     The tp pointer parameter is invalid.
    101 
    102 *EINVAL*
    103     The clock_id specified is invalid.
    104 
    105 *EINVAL*
    106     The contents of the tp structure are invalid.
     97        clockid_t              clock_id,
     98        const struct timespec *tp
     99    );
     100
     101**STATUS CODES:**
     102
     103On error, this routine returns -1 and sets ``errno`` to one of the following:
     104
     105.. list-table::
     106 :class: rtems-table
     107
     108 * - ``EINVAL``
     109   - The tp pointer parameter is invalid.
     110 * - ``EINVAL``
     111   - The clock_id specified is invalid.
     112 * - ``EINVAL``
     113   - The contents of the tp structure are invalid.
    107114
    108115**DESCRIPTION:**
     
    111118
    112119NONE
     120
     121.. _clock_getres:
    113122
    114123clock_getres - Get Clock Resolution
     
    119128**CALLING SEQUENCE:**
    120129
    121 .. code:: c
     130.. code-block:: c
    122131
    123132    #include <time.h>
    124133    int clock_getres(
    125     clockid_t        clock_id,
    126     struct timespec \*res
    127     );
    128 
    129 **STATUS CODES:**
    130 
    131 On error, this routine returns -1 and sets errno to one of the following:
    132 
    133 *EINVAL*
    134     The res pointer parameter is invalid.
    135 
    136 *EINVAL*
    137     The clock_id specified is invalid.
    138 
    139 **DESCRIPTION:**
    140 
    141 **NOTES:**
    142 
    143 If res is NULL, then the resolution is not returned.
     134        clockid_t        clock_id,
     135        struct timespec *res
     136    );
     137
     138**STATUS CODES:**
     139
     140On error, this routine returns -1 and sets ``errno`` to one of the following:
     141
     142.. list-table::
     143 :class: rtems-table
     144
     145 * - ``EINVAL``
     146   - The res pointer parameter is invalid.
     147 * - ``EINVAL``
     148   - The clock_id specified is invalid.
     149
     150**DESCRIPTION:**
     151
     152**NOTES:**
     153
     154If ``res`` is ``NULL``, then the resolution is not returned.
     155
     156.. _sleep:
    144157
    145158sleep - Delay Process Execution
     
    150163**CALLING SEQUENCE:**
    151164
    152 .. code:: c
     165.. code-block:: c
    153166
    154167    #include <unistd.h>
    155168    unsigned int sleep(
    156     unsigned int seconds
     169        unsigned int seconds
    157170    );
    158171
     
    163176**DESCRIPTION:**
    164177
    165 The ``sleep()`` function delays the calling thread by the specified
    166 number of ``seconds``.
     178The ``sleep()`` function delays the calling thread by the specified number of
     179``seconds``.
    167180
    168181**NOTES:**
    169182
    170183This call is interruptible by a signal.
     184
     185.. _usleep:
    171186
    172187usleep - Delay Process Execution in Microseconds
     
    180195**CALLING SEQUENCE:**
    181196
    182 .. code:: c
     197.. code-block:: c
    183198
    184199    #include <time.h>
    185200    useconds_t usleep(
    186     useconds_t useconds
     201        useconds_t useconds
    187202    );
    188203
     
    193208**DESCRIPTION:**
    194209
    195 The ``sleep()`` function delays the calling thread by the specified
    196 number of ``seconds``.
    197 
    198 The ``usleep()`` function suspends the calling thread from execution
    199 until either the number of microseconds specified by the``useconds`` argument has elapsed or a signal is delivered to the
    200 calling thread and its action is to invoke a signal-catching function
    201 or to terminate the process.
    202 
    203 Because of other activity, or because of the time spent in
    204 processing the call, the actual length of time the thread is
    205 blocked may be longer than
    206 the amount of time specified.
     210The ``sleep()`` function delays the calling thread by the specified number of
     211``seconds``.
     212
     213The ``usleep()`` function suspends the calling thread from execution until
     214either the number of microseconds specified by the ``useconds`` argument has
     215elapsed or a signal is delivered to the calling thread and its action is to
     216invoke a signal-catching function or to terminate the process.
     217
     218Because of other activity, or because of the time spent in processing the call,
     219the actual length of time the thread is blocked may be longer than the amount
     220of time specified.
    207221
    208222**NOTES:**
     
    210224This call is interruptible by a signal.
    211225
    212 The Single UNIX Specification allows this service to be implemented using
    213 the same timer as that used by the ``alarm()`` service.  This is*NOT* the case for *RTEMS* and this call has no interaction with
    214 the ``SIGALRM`` signal.
     226The Single UNIX Specification allows this service to be implemented using the
     227same timer as that used by the ``alarm()`` service.  This is *NOT* the case for
     228*RTEMS* and this call has no interaction with the ``SIGALRM`` signal.
     229
     230.. _nanosleep:
    215231
    216232nanosleep - Delay with High Resolution
     
    221237**CALLING SEQUENCE:**
    222238
    223 .. code:: c
     239.. code-block:: c
    224240
    225241    #include <time.h>
    226242    int nanosleep(
    227     const struct timespec \*rqtp,
    228     struct timespec       \*rmtp
    229     );
    230 
    231 **STATUS CODES:**
    232 
    233 On error, this routine returns -1 and sets errno to one of the following:
    234 
    235 *EINTR*
    236     The routine was interrupted by a signal.
    237 
    238 *EAGAIN*
    239     The requested sleep period specified negative seconds or nanoseconds.
    240 
    241 *EINVAL*
    242     The requested sleep period specified an invalid number for the nanoseconds
    243     field.
     243        const struct timespec *rqtp,
     244        struct timespec       *rmtp
     245    );
     246
     247**STATUS CODES:**
     248
     249On error, this routine returns -1 and sets ``errno`` to one of the following:
     250
     251.. list-table::
     252 :class: rtems-table
     253
     254 * - ``EINTR``
     255   - The routine was interrupted by a signal.
     256 * - ``EAGAIN``
     257   - The requested sleep period specified negative seconds or nanoseconds.
     258 * - ``EINVAL``
     259   - The requested sleep period specified an invalid number for the nanoseconds
     260     field.
    244261
    245262**DESCRIPTION:**
     
    248265
    249266This call is interruptible by a signal.
     267
     268.. _gettimeofday:
    250269
    251270gettimeofday - Get the Time of Day
     
    256275**CALLING SEQUENCE:**
    257276
    258 .. code:: c
     277.. code-block:: c
    259278
    260279    #include <sys/time.h>
    261280    #include <unistd.h>
    262281    int gettimeofday(
    263     struct timeval  \*tp,
    264     struct timezone \*tzp
     282        struct timeval  *tp,
     283        struct timezone *tzp
    265284    );
    266285
     
    269288On error, this routine returns -1 and sets ``errno`` as appropriate.
    270289
    271 *EPERM*
    272     ``settimeofdat`` is called by someone other than the superuser.
    273 
    274 *EINVAL*
    275     Timezone (or something else) is invalid.
    276 
    277 *EFAULT*
    278     One of ``tv`` or ``tz`` pointed outside your accessible address
    279     space
     290.. list-table::
     291 :class: rtems-table
     292
     293 * - ``EPERM``
     294   - ``settimeofdat`` is called by someone other than the superuser.
     295 * - ``EINVAL``
     296   - Timezone (or something else) is invalid.
     297 * - ``EFAULT``
     298   - One of ``tv`` or ``tz`` pointed outside your accessible address space
    280299
    281300**DESCRIPTION:**
     
    285304**NOTES:**
    286305
    287 Currently, the timezone information is not supported. The ``tzp``
    288 argument is ignored.
     306Currently, the timezone information is not supported. The ``tzp`` argument is
     307ignored.
     308
     309.. _time:
    289310
    290311time - Get time in seconds
     
    295316**CALLING SEQUENCE:**
    296317
    297 .. code:: c
     318.. code-block:: c
    298319
    299320    #include <time.h>
    300321    int time(
    301     time_t \*tloc
     322        time_t *tloc
    302323    );
    303324
     
    308329**DESCRIPTION:**
    309330
    310 ``time`` returns the time since 00:00:00 GMT, January 1, 1970,
    311 measured in seconds
    312 
    313 If ``tloc`` in non null, the return value is also stored in the
    314 memory pointed to by ``t``.
     331``time`` returns the time since 00:00:00 GMT, January 1, 1970, measured in
     332seconds
     333
     334If ``tloc`` in non null, the return value is also stored in the memory pointed
     335to by ``t``.
    315336
    316337**NOTES:**
    317338
    318339NONE
    319 
    320 .. COMMENT: This is the chapter from the RTEMS POSIX 1003.1b API User's Guide that
    321 
    322 .. COMMENT: documents the services provided by the timer @c  manager.
    323 
  • posix_users/condition_variable.rst

    r238bf99 rfa70fd2  
     1.. COMMENT: COPYRIGHT (c) 1988-2002.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Condition Variable Manager
    26##########################
     
    913The directives provided by the condition variable manager are:
    1014
    11 - ``pthread_condattr_init`` - Initialize a Condition Variable Attribute Set
    12 
    13 - ``pthread_condattr_destroy`` - Destroy a Condition Variable Attribute Set
    14 
    15 - ``pthread_condattr_setpshared`` - Set Process Shared Attribute
    16 
    17 - ``pthread_condattr_getpshared`` - Get Process Shared Attribute
    18 
    19 - ``pthread_cond_init`` - Initialize a Condition Variable
    20 
    21 - ``pthread_cond_destroy`` - Destroy a Condition Variable
    22 
    23 - ``pthread_cond_signal`` - Signal a Condition Variable
    24 
    25 - ``pthread_cond_broadcast`` - Broadcast a Condition Variable
    26 
    27 - ``pthread_cond_wait`` - Wait on a Condition Variable
    28 
    29 - ``pthread_cond_timedwait`` - With with Timeout a Condition Variable
     15- pthread_condattr_init_ - Initialize a Condition Variable Attribute Set
     16
     17- pthread_condattr_destroy_ - Destroy a Condition Variable Attribute Set
     18
     19- pthread_condattr_setpshared_ - Set Process Shared Attribute
     20
     21- pthread_condattr_getpshared_ - Get Process Shared Attribute
     22
     23- pthread_cond_init_ - Initialize a Condition Variable
     24
     25- pthread_cond_destroy_ - Destroy a Condition Variable
     26
     27- pthread_cond_signal_ - Signal a Condition Variable
     28
     29- pthread_cond_broadcast_ - Broadcast a Condition Variable
     30
     31- pthread_cond_wait_ - Wait on a Condition Variable
     32
     33- pthread_cond_timedwait_ - With with Timeout a Condition Variable
    3034
    3135Background
     
    4246==========
    4347
    44 This section details the condition variable manager's directives.
    45 A subsection is dedicated to each of this manager's directives
    46 and describes the calling sequence, related constants, usage,
    47 and status codes.
     48This section details the condition variable manager's directives.  A subsection
     49is dedicated to each of this manager's directives and describes the calling
     50sequence, related constants, usage, and status codes.
     51
     52.. _pthread_condattr_init:
    4853
    4954pthread_condattr_init - Initialize a Condition Variable Attribute Set
     
    5459**CALLING SEQUENCE:**
    5560
    56 .. code:: c
     61.. code-block:: c
    5762
    5863    #include <pthread.h>
    5964    int pthread_condattr_init(
    60     pthread_condattr_t \*attr
    61     );
    62 
    63 **STATUS CODES:**
    64 
    65 *ENOMEM*
    66     Insufficient memory is available to initialize the condition variable
    67     attributes object.
    68 
    69 **DESCRIPTION:**
    70 
    71 **NOTES:**
     65        pthread_condattr_t *attr
     66    );
     67
     68**STATUS CODES:**
     69
     70 * - ``ENOMEM``
     71   - Insufficient memory is available to initialize the condition variable
     72     attributes object.
     73
     74**DESCRIPTION:**
     75
     76**NOTES:**
     77
     78.. _pthread_condattr_destroy:
    7279
    7380pthread_condattr_destroy - Destroy a Condition Variable Attribute Set
     
    7885**CALLING SEQUENCE:**
    7986
    80 .. code:: c
     87.. code-block:: c
    8188
    8289    #include <pthread.h>
    8390    int pthread_condattr_destroy(
    84     pthread_condattr_t \*attr
    85     );
    86 
    87 **STATUS CODES:**
    88 
    89 *EINVAL*
    90     The attribute object specified is invalid.
    91 
    92 **DESCRIPTION:**
    93 
    94 **NOTES:**
     91        pthread_condattr_t *attr
     92    );
     93
     94**STATUS CODES:**
     95
     96.. list-table::
     97 :class: rtems-table
     98
     99 * - ``EINVAL``
     100   - The attribute object specified is invalid.
     101
     102**DESCRIPTION:**
     103
     104**NOTES:**
     105
     106.. _pthread_condattr_setpshared:
    95107
    96108pthread_condattr_setpshared - Set Process Shared Attribute
     
    101113**CALLING SEQUENCE:**
    102114
    103 .. code:: c
     115.. code-block:: c
    104116
    105117    #include <pthread.h>
    106118    int pthread_condattr_setpshared(
    107     pthread_condattr_t \*attr,
    108     int                 pshared
    109     );
    110 
    111 **STATUS CODES:**
    112 
    113 *EINVAL*
    114     Invalid argument passed.
    115 
    116 **DESCRIPTION:**
    117 
    118 **NOTES:**
     119        pthread_condattr_t *attr,
     120        int                 pshared
     121    );
     122
     123**STATUS CODES:**
     124
     125.. list-table::
     126 :class: rtems-table
     127
     128 * - ``EINVAL``
     129   - Invalid argument passed.
     130
     131**DESCRIPTION:**
     132
     133**NOTES:**
     134
     135.. _pthread_condattr_getpshared:
    119136
    120137pthread_condattr_getpshared - Get Process Shared Attribute
     
    125142**CALLING SEQUENCE:**
    126143
    127 .. code:: c
     144.. code-block:: c
    128145
    129146    #include <pthread.h>
    130147    int pthread_condattr_getpshared(
    131     const pthread_condattr_t \*attr,
    132     int                      \*pshared
    133     );
    134 
    135 **STATUS CODES:**
    136 
    137 *EINVAL*
    138     Invalid argument passed.
    139 
    140 **DESCRIPTION:**
    141 
    142 **NOTES:**
     148        const pthread_condattr_t *attr,
     149        int                      *pshared
     150    );
     151
     152**STATUS CODES:**
     153
     154.. list-table::
     155 :class: rtems-table
     156
     157 * - ``EINVAL``
     158   - Invalid argument passed.
     159
     160**DESCRIPTION:**
     161
     162**NOTES:**
     163
     164.. _pthread_cond_init:
    143165
    144166pthread_cond_init - Initialize a Condition Variable
     
    149171**CALLING SEQUENCE:**
    150172
    151 .. code:: c
     173.. code-block:: c
    152174
    153175    #include <pthread.h>
    154176    int pthread_cond_init(
    155     pthread_cond_t           \*cond,
    156     const pthread_condattr_t \*attr
    157     );
    158 
    159 **STATUS CODES:**
    160 
    161 *EAGAIN*
    162     The system lacked a resource other than memory necessary to create the
    163     initialize the condition variable object.
    164 
    165 *ENOMEM*
    166     Insufficient memory is available to initialize the condition variable object.
    167 
    168 *EBUSY*
    169     The specified condition variable has already been initialized.
    170 
    171 *EINVAL*
    172     The specified attribute value is invalid.
    173 
    174 **DESCRIPTION:**
    175 
    176 **NOTES:**
     177        pthread_cond_t           *cond,
     178        const pthread_condattr_t *attr
     179    );
     180
     181**STATUS CODES:**
     182
     183.. list-table::
     184 :class: rtems-table
     185
     186 * - ``EAGAIN``
     187   - The system lacked a resource other than memory necessary to create the
     188     initialize the condition variable object.
     189 * - ``ENOMEM``
     190   - Insufficient memory is available to initialize the condition variable
     191     object.
     192 * - ``EBUSY``
     193   - The specified condition variable has already been initialized.
     194 * - ``EINVAL``
     195   - The specified attribute value is invalid.
     196
     197**DESCRIPTION:**
     198
     199**NOTES:**
     200
     201.. _pthread_cond_destroy:
    177202
    178203pthread_cond_destroy - Destroy a Condition Variable
     
    183208**CALLING SEQUENCE:**
    184209
    185 .. code:: c
     210.. code-block:: c
    186211
    187212    #include <pthread.h>
    188213    int pthread_cond_destroy(
    189     pthread_cond_t \*cond
    190     );
    191 
    192 **STATUS CODES:**
    193 
    194 *EINVAL*
    195     The specified condition variable is invalid.
    196 
    197 *EBUSY*
    198     The specified condition variable is currently in use.
    199 
    200 **DESCRIPTION:**
    201 
    202 **NOTES:**
     214        pthread_cond_t *cond
     215    );
     216
     217**STATUS CODES:**
     218
     219.. list-table::
     220 :class: rtems-table
     221
     222 * - ``EINVAL``
     223   - The specified condition variable is invalid.
     224 * - ``EBUSY``
     225   - The specified condition variable is currently in use.
     226
     227**DESCRIPTION:**
     228
     229**NOTES:**
     230
     231.. _pthread_cond_signal:
    203232
    204233pthread_cond_signal - Signal a Condition Variable
     
    209238**CALLING SEQUENCE:**
    210239
    211 .. code:: c
     240.. code-block:: c
    212241
    213242    #include <pthread.h>
    214243    int pthread_cond_signal(
    215     pthread_cond_t \*cond
    216     );
    217 
    218 **STATUS CODES:**
    219 
    220 *EINVAL*
    221     The specified condition variable is not valid.
     244        pthread_cond_t *cond
     245    );
     246
     247**STATUS CODES:**
     248
     249.. list-table::
     250 :class: rtems-table
     251
     252 * - ``EINVAL``
     253   - The specified condition variable is not valid.
    222254
    223255**DESCRIPTION:**
     
    227259This routine should not be invoked from a handler from an asynchronous signal
    228260handler or an interrupt service routine.
     261
     262.. _pthread_cond_broadcast:
    229263
    230264pthread_cond_broadcast - Broadcast a Condition Variable
     
    235269**CALLING SEQUENCE:**
    236270
    237 .. code:: c
     271.. code-block:: c
    238272
    239273    #include <pthread.h>
    240274    int pthread_cond_broadcast(
    241     pthread_cond_t \*cond
    242     );
    243 
    244 **STATUS CODES:**
    245 
    246 *EINVAL*
    247     The specified condition variable is not valid.
     275        pthread_cond_t *cond
     276    );
     277
     278**STATUS CODES:**
     279
     280.. list-table::
     281 :class: rtems-table
     282
     283 * - ``EINVAL``
     284   - The specified condition variable is not valid.
    248285
    249286**DESCRIPTION:**
     
    253290This routine should not be invoked from a handler from an asynchronous signal
    254291handler or an interrupt service routine.
     292
     293.. _pthread_cond_wait:
    255294
    256295pthread_cond_wait - Wait on a Condition Variable
     
    261300**CALLING SEQUENCE:**
    262301
    263 .. code:: c
     302.. code-block:: c
    264303
    265304    #include <pthread.h>
    266305    int pthread_cond_wait(
    267     pthread_cond_t \*cond,
    268     pthread_mutex_t \*mutex
    269     );
    270 
    271 **STATUS CODES:**
    272 
    273 *EINVAL*
    274     The specified condition variable or mutex is not initialized OR different
    275     mutexes were specified for concurrent pthread_cond_wait() and
    276     pthread_cond_timedwait() operations on the same condition variable OR
    277     the mutex was not owned by the current thread at the time of the call.
    278 
    279 **DESCRIPTION:**
    280 
    281 **NOTES:**
     306        pthread_cond_t *cond,
     307        pthread_mutex_t *mutex
     308    );
     309
     310**STATUS CODES:**
     311
     312.. list-table::
     313 :class: rtems-table
     314
     315 * - ``EINVAL``
     316   - The specified condition variable or mutex is not initialized OR different
     317     mutexes were specified for concurrent ``pthread_cond_wait()`` and
     318     ``pthread_cond_timedwait()`` operations on the same condition variable OR
     319     the mutex was not owned by the current thread at the time of the call.
     320
     321**DESCRIPTION:**
     322
     323**NOTES:**
     324
     325.. _pthread_cond_timedwait:
    282326
    283327pthread_cond_timedwait - Wait with Timeout a Condition Variable
     
    288332**CALLING SEQUENCE:**
    289333
    290 .. code:: c
     334.. code-block:: c
    291335
    292336    #include <pthread.h>
    293337    int pthread_cond_timedwait(
    294     pthread_cond_t        \*cond,
    295     pthread_mutex_t       \*mutex,
    296     const struct timespec \*abstime
    297     );
    298 
    299 **STATUS CODES:**
    300 
    301 *EINVAL*
    302     The specified condition variable or mutex is not initialized OR different
    303     mutexes were specified for concurrent pthread_cond_wait() and
    304     pthread_cond_timedwait() operations on the same condition variable OR
    305     the mutex was not owned by the current thread at the time of the call.
    306 
    307 *ETIMEDOUT*
    308     The specified time has elapsed without the condition variable being
    309     satisfied.
    310 
    311 **DESCRIPTION:**
    312 
    313 **NOTES:**
    314 
    315 .. COMMENT: COPYRIGHT (c) 1988-2002.
    316 
    317 .. COMMENT: On-Line Applications Research Corporation (OAR).
    318 
    319 .. COMMENT: All rights reserved.
    320 
     338        pthread_cond_t        *cond,
     339        pthread_mutex_t       *mutex,
     340        const struct timespec *abstime
     341    );
     342
     343**STATUS CODES:**
     344
     345.. list-table::
     346 :class: rtems-table
     347
     348 * - ``EINVAL``
     349   - The specified condition variable or mutex is not initialized OR different
     350     mutexes were specified for concurrent ``pthread_cond_wait()`` and
     351     ``pthread_cond_timedwait()`` operations on the same condition variable OR
     352     the mutex was not owned by the current thread at the time of the call.
     353 * - ``ETIMEDOUT``
     354   - The specified time has elapsed without the condition variable being
     355     satisfied.
     356
     357**DESCRIPTION:**
     358
     359**NOTES:**
  • posix_users/device_and_class_specific.rst

    r238bf99 rfa70fd2  
     1.. COMMENT: COPYRIGHT (c) 1988-2002.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Device- and Class- Specific Functions Manager
    26#############################################
     
    711The device- and class- specific functions manager is ...
    812
    9 The directives provided by the device- and class- specific functions
    10 manager are:
    11 
    12 - ``cfgetispeed`` - Reads terminal input baud rate
    13 
    14 - ``cfgetospeed`` - Reads terminal output baud rate
    15 
    16 - ``cfsetispeed`` - Sets terminal input baud rate
    17 
    18 - ``cfsetospeed`` - Set terminal output baud rate
    19 
    20 - ``tcgetattr`` - Gets terminal attributes
    21 
    22 - ``tcsetattr`` - Set terminal attributes
    23 
    24 - ``tcsendbreak`` - Sends a break to a terminal
    25 
    26 - ``tcdrain`` - Waits for all output to be transmitted to the terminal
    27 
    28 - ``tcflush`` - Discards terminal data
    29 
    30 - ``tcflow`` - Suspends/restarts terminal output
    31 
    32 - ``tcgetpgrp`` - Gets foreground process group ID
    33 
    34 - ``tcsetpgrp`` - Sets foreground process group ID
     13The directives provided by the device- and class- specific functions manager
     14are:
     15
     16- cfgetispeed_ - Reads terminal input baud rate
     17
     18- cfgetospeed_ - Reads terminal output baud rate
     19
     20- cfsetispeed_ - Sets terminal input baud rate
     21
     22- cfsetospeed_ - Set terminal output baud rate
     23
     24- tcgetattr_ - Gets terminal attributes
     25
     26- tcsetattr_ - Set terminal attributes
     27
     28- tcsendbreak_ - Sends a break to a terminal
     29
     30- tcdrain_ - Waits for all output to be transmitted to the terminal
     31
     32- tcflush_ - Discards terminal data
     33
     34- tcflow_ - Suspends/restarts terminal output
     35
     36- tcgetpgrp_ - Gets foreground process group ID
     37
     38- tcsetpgrp_ - Sets foreground process group ID
    3539
    3640Background
     
    5256and status codes.
    5357
     58.. _cfgetispeed:
     59
    5460cfgetispeed - Reads terminal input baud rate
    5561--------------------------------------------
     
    5965**CALLING SEQUENCE:**
    6066
    61 .. code:: c
     67.. code-block:: c
    6268
    6369    #include <termios.h>
    6470    int cfgetispeed(
    65     const struct termios \*p
     71        const struct termios *p
    6672    );
    6773
     
    7278**DESCRIPTION:**
    7379
    74 The ``cfsetispeed()`` function stores a code for the terminal speed
    75 stored in a struct termios. The codes are defined in ``<termios.h>``
    76 by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
    77 B1800, B2400, B4800, B9600, B19200, and B38400.
    78 
    79 The ``cfsetispeed()`` function does not do anything to the hardware.
    80 It merely stores a value for use by ``tcsetattr()``.
    81 
    82 **NOTES:**
    83 
    84 Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
    85 number returned for any given speed may change from system to system.
     80The ``cfsetispeed()`` function stores a code for the terminal speed stored in a
     81struct termios. The codes are defined in ``<termios.h>`` by the macros ``BO``,
     82``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``, ``B600``,
     83``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``, and
     84``B38400``.
     85
     86The ``cfsetispeed()`` function does not do anything to the hardware.  It merely
     87stores a value for use by ``tcsetattr()``.
     88
     89**NOTES:**
     90
     91Baud rates are defined by symbols, such as ``B110``, ``B1200``, ``B2400``. The
     92actual number returned for any given speed may change from system to system.
     93
     94.. _cfgetospeed:
    8695
    8796cfgetospeed - Reads terminal output baud rate
     
    92101**CALLING SEQUENCE:**
    93102
    94 .. code:: c
    95 
    96     #include <termios.h>
    97     int cfgetospeed(
    98     const struct termios \*p
     103.. code-block:: c
     104
     105    #include <termios.h>
     106        int cfgetospeed(
     107        const struct termios *p
    99108    );
    100109
     
    105114**DESCRIPTION:**
    106115
    107 The ``cfgetospeed()`` function returns a code for the terminal speed
    108 stored in a ``struct termios``. The codes are defined in ``<termios.h>``
    109 by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800,
    110 B2400, B4800, B9600, B19200, and B38400.
    111 
    112 The ``cfgetospeed()`` function does not do anything to the hardware.
    113 It merely returns the value stored by a previous call to ``tcgetattr()``.
    114 
    115 **NOTES:**
    116 
    117 Baud rates are defined by symbols, such as B110, B1200, B2400. The actual
    118 number returned for any given speed may change from system to system.
     116The ``cfgetospeed()`` function returns a code for the terminal speed stored in
     117a ``struct termios``. The codes are defined in ``<termios.h>`` by the macros
     118``BO``, ``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``,
     119``B600``, ``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``,
     120and ``B38400``.
     121
     122The ``cfgetospeed()`` function does not do anything to the hardware.  It merely
     123returns the value stored by a previous call to ``tcgetattr()``.
     124
     125**NOTES:**
     126
     127Baud rates are defined by symbols, such as ``B110``, ``B1200``, ``B2400``. The
     128actual number returned for any given speed may change from system to system.
     129
     130.. _cfsetispeed:
    119131
    120132cfsetispeed - Sets terminal input baud rate
     
    125137**CALLING SEQUENCE:**
    126138
    127 .. code:: c
     139.. code-block:: c
    128140
    129141    #include <termios.h>
    130142    int cfsetispeed(
    131     struct termios \*p,
    132     speed_t         speed
    133     );
    134 
    135 **STATUS CODES:**
    136 
    137 The ``cfsetispeed()`` function returns a zero when successful and
    138 returns -1 when an error occurs.
    139 
    140 **DESCRIPTION:**
    141 
    142 The ``cfsetispeed()`` function stores a code for the terminal speed
    143 stored in a struct termios. The codes are defined in ``<termios.h>``
    144 by the macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200,
    145 B1800, B2400, B4800, B9600, B19200, and B38400.
    146 
    147 **NOTES:**
    148 
    149 This function merely stores a value in the ``termios`` structure. It
    150 does not change the terminal speed until a ``tcsetattr()`` is done.
    151 It does not detect impossible terminal speeds.
     143        struct termios *p,
     144        speed_t         speed
     145    );
     146
     147**STATUS CODES:**
     148
     149The ``cfsetispeed()`` function returns a zero when successful and returns -1
     150when an error occurs.
     151
     152**DESCRIPTION:**
     153
     154The ``cfsetispeed()`` function stores a code for the terminal speed stored in a
     155struct termios. The codes are defined in ``<termios.h>`` by the macros ``BO``,
     156``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``, ``B600``,
     157``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``, and
     158``B38400``.
     159
     160**NOTES:**
     161
     162This function merely stores a value in the ``termios`` structure. It does not
     163change the terminal speed until a ``tcsetattr()`` is done.  It does not detect
     164impossible terminal speeds.
     165
     166.. _cfsetospeed:
    152167
    153168cfsetospeed - Sets terminal output baud rate
     
    158173**CALLING SEQUENCE:**
    159174
    160 .. code:: c
     175.. code-block:: c
    161176
    162177    #include <termios.h>
    163178    int cfsetospeed(
    164     struct termios \*p,
    165     speed_t         speed
     179        struct termios *p,
     180        speed_t         speed
    166181    );
    167182
     
    173188**DESCRIPTION:**
    174189
    175 The ``cfsetospeed()`` function stores a code for the terminal speed stored
    176 in a struct ``termios``. The codes are defiined in ``<termios.h>`` by the
    177 macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400,
    178 B4800, B9600, B19200, and B38400.
    179 
    180 The ``cfsetospeed()`` function does not do anything to the hardware. It
    181 merely stores a value for use by ``tcsetattr()``.
    182 
    183 **NOTES:**
    184 
    185 This function merely stores a value in the ``termios`` structure.
    186 It does not change the terminal speed until a ``tcsetattr()`` is done.
    187 It does not detect impossible terminal speeds.
     190The ``cfsetospeed()`` function stores a code for the terminal speed stored in a
     191struct ``termios``. The codes are defiined in ``<termios.h>`` by the macros
     192``BO``, ``B50``, ``B75``, ``B110``, ``B134``, ``B150``, ``B200``, ``B300``,
     193``B600``, ``B1200``, ``B1800``, ``B2400``, ``B4800``, ``B9600``, ``B19200``,
     194and ``B38400``.
     195
     196The ``cfsetospeed()`` function does not do anything to the hardware. It merely
     197stores a value for use by ``tcsetattr()``.
     198
     199**NOTES:**
     200
     201This function merely stores a value in the ``termios`` structure.  It does not
     202change the terminal speed until a ``tcsetattr()`` is done.  It does not detect
     203impossible terminal speeds.
     204
     205.. _tcgetattr:
    188206
    189207tcgetattr - Gets terminal attributes
     
    194212**CALLING SEQUENCE:**
    195213
    196 .. code:: c
     214.. code-block:: c
    197215
    198216    #include <termios.h>
    199217    #include <unistd.h>
    200218    int tcgetattr(
    201     int             fildes,
    202     struct termios \*p
    203     );
    204 
    205 **STATUS CODES:**
    206 
    207 *EBADF*
    208     Invalid file descriptor
    209 
    210 *ENOOTY*
    211     Terminal control function attempted for a file that is not a terminal.
    212 
    213 **DESCRIPTION:**
    214 
    215 The ``tcgetattr()`` gets the parameters associated with the terminal
    216 referred to by ``fildes`` and stores them into the ``termios()``
    217 structure pointed to by ``termios_p``.
     219        int             fildes,
     220        struct termios *p
     221    );
     222
     223**STATUS CODES:**
     224
     225.. list-table::
     226 :class: rtems-table
     227
     228 * - ``EBADF``
     229   - Invalid file descriptor
     230 * - ``ENOOTY``
     231   - Terminal control function attempted for a file that is not a terminal.
     232
     233**DESCRIPTION:**
     234
     235The ``tcgetattr()`` gets the parameters associated with the terminal referred
     236to by ``fildes`` and stores them into the ``termios()`` structure pointed to by
     237``termios_p``.
    218238
    219239**NOTES:**
    220240
    221241NONE
     242
     243.. _tcsetattr:
    222244
    223245tcsetattr - Set terminal attributes
     
    228250**CALLING SEQUENCE:**
    229251
    230 .. code:: c
     252.. code-block:: c
    231253
    232254    #include <termios.h>
    233255    #include <unistd.h>
    234256    int tcsetattr(
    235     int                   fildes,
    236     int                   options,
    237     const struct termios \*tp
    238     );
    239 
    240 **STATUS CODES:**
    241 
    242 *E*
    243     The
    244 
    245 **DESCRIPTION:**
    246 
    247 **NOTES:**
     257        int                   fildes,
     258        int                   options,
     259        const struct termios *tp
     260    );
     261
     262**STATUS CODES:**
     263
     264.. list-table::
     265 :class: rtems-table
     266
     267 * - ``E``
     268   - The
     269
     270**DESCRIPTION:**
     271
     272**NOTES:**
     273
     274.. _tcsendbreak:
    248275
    249276tcsendbreak - Sends a break to a terminal
     
    254281**CALLING SEQUENCE:**
    255282
    256 .. code:: c
     283.. code-block:: c
    257284
    258285    int tcsendbreak(
    259     int fd
    260     );
    261 
    262 **STATUS CODES:**
    263 
    264 *E*
    265     The
     286        int fd
     287    );
     288
     289**STATUS CODES:**
     290
     291.. list-table::
     292 :class: rtems-table
     293
     294 * - ``E``
     295   - The
    266296
    267297**DESCRIPTION:**
     
    271301This routine is not currently supported by RTEMS but could be
    272302in a future version.
     303
     304.. _tcdrain:
    273305
    274306tcdrain - Waits for all output to be transmitted to the terminal.
     
    279311**CALLING SEQUENCE:**
    280312
    281 .. code:: c
     313.. code-block:: c
    282314
    283315    #include <termios.h>
    284316    #include <unistd.h>
    285317    int tcdrain(
    286     int fildes
    287     );
    288 
    289 **STATUS CODES:**
    290 
    291 *EBADF*
    292     Invalid file descriptor
    293 
    294 *EINTR*
    295     Function was interrupted by a signal
    296 
    297 *ENOTTY*
    298     Terminal control function attempted for a file that is not a terminal.
    299 
    300 **DESCRIPTION:**
    301 
    302 The ``tcdrain()`` function waits until all output written to``fildes`` has been transmitted.
     318        int fildes
     319    );
     320
     321**STATUS CODES:**
     322
     323.. list-table::
     324 :class: rtems-table
     325
     326 * - ``EBADF``
     327   - Invalid file descriptor
     328 * - ``EINTR``
     329   - Function was interrupted by a signal
     330 * - ``ENOTTY``
     331   - Terminal control function attempted for a file that is not a terminal.
     332
     333**DESCRIPTION:**
     334
     335The ``tcdrain()`` function waits until all output written to ``fildes`` has been
     336transmitted.
    303337
    304338**NOTES:**
    305339
    306340NONE
     341
     342.. _tcflush:
    307343
    308344tcflush - Discards terminal data
     
    313349**CALLING SEQUENCE:**
    314350
    315 .. code:: c
     351.. code-block:: c
    316352
    317353    int tcflush(
    318     int fd
    319     );
    320 
    321 **STATUS CODES:**
    322 
    323 *E*
    324     The
    325 
    326 **DESCRIPTION:**
    327 
    328 **NOTES:**
    329 
    330 This routine is not currently supported by RTEMS but could be
    331 in a future version.
     354        int fd
     355    );
     356
     357**STATUS CODES:**
     358
     359.. list-table::
     360 :class: rtems-table
     361
     362 * - ``E``
     363   - The
     364
     365**DESCRIPTION:**
     366
     367**NOTES:**
     368
     369This routine is not currently supported by RTEMS but could be in a future
     370version.
     371
     372.. _tcflow:
    332373
    333374tcflow - Suspends/restarts terminal output.
     
    338379**CALLING SEQUENCE:**
    339380
    340 .. code:: c
     381.. code-block:: c
    341382
    342383    int tcflow(
    343     int fd
    344     );
    345 
    346 **STATUS CODES:**
    347 
    348 *E*
    349     The
    350 
    351 **DESCRIPTION:**
    352 
    353 **NOTES:**
    354 
    355 This routine is not currently supported by RTEMS but could be
    356 in a future version.
     384        int fd
     385    );
     386
     387**STATUS CODES:**
     388
     389.. list-table::
     390 :class: rtems-table
     391
     392 * - ``E``
     393   - The
     394
     395**DESCRIPTION:**
     396
     397**NOTES:**
     398
     399This routine is not currently supported by RTEMS but could be in a future
     400version.
     401
     402.. _tcgetpgrp:
    357403
    358404tcgetpgrp - Gets foreground process group ID
     
    363409**CALLING SEQUENCE:**
    364410
    365 .. code:: c
     411.. code-block:: c
    366412
    367413    int tcgetpgrp(
     
    370416**STATUS CODES:**
    371417
    372 *E*
    373     The
    374 
    375 **DESCRIPTION:**
    376 
    377 **NOTES:**
    378 
    379 This routine is not currently supported by RTEMS but could be
    380 in a future version.
     418.. list-table::
     419 :class: rtems-table
     420
     421 * - ``E``
     422   - The
     423
     424**DESCRIPTION:**
     425
     426**NOTES:**
     427
     428This routine is not currently supported by RTEMS but could be in a future
     429version.
     430
     431.. _tcsetpgrp:
    381432
    382433tcsetpgrp - Sets foreground process group ID
     
    387438**CALLING SEQUENCE:**
    388439
    389 .. code:: c
     440.. code-block:: c
    390441
    391442    int tcsetpgrp(
     
    394445**STATUS CODES:**
    395446
    396 *E*
    397     The
    398 
    399 **DESCRIPTION:**
    400 
    401 **NOTES:**
    402 
    403 This routine is not currently supported by RTEMS but could be
    404 in a future version.
    405 
    406 .. COMMENT: COPYRIGHT (c) 1988-2002.
    407 
    408 .. COMMENT: On-Line Applications Research Corporation (OAR).
    409 
    410 .. COMMENT: All rights reserved.
    411 
     447.. list-table::
     448 :class: rtems-table
     449
     450 * - ``E``
     451   - The
     452
     453**DESCRIPTION:**
     454
     455**NOTES:**
     456
     457This routine is not currently supported by RTEMS but could be in a future
     458version.
  • posix_users/files_and_directory.rst

    r238bf99 rfa70fd2  
     1.. COMMENT: COPYRIGHT (c) 1988-2002.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Files and Directories Manager
    26#############################
     
    913The directives provided by the files and directories manager are:
    1014
    11 - ``opendir`` - Open a Directory
    12 
    13 - ``readdir`` - Reads a directory
    14 
    15 - ``rewinddir`` - Resets the ``readdir()`` pointer
    16 
    17 - ``scandir`` - Scan a directory for matching entries
    18 
    19 - ``telldir`` - Return current location in directory stream
    20 
    21 - ``closedir`` - Ends directory read operation
    22 
    23 - ``getdents`` - Get directory entries
    24 
    25 - ``chdir`` - Changes the current working directory
    26 
    27 - ``fchdir`` - Changes the current working directory
    28 
    29 - ``getcwd`` - Gets current working directory
    30 
    31 - ``open`` - Opens a file
    32 
    33 - ``creat`` - Create a new file or rewrite an existing one
    34 
    35 - ``umask`` - Sets a file creation mask
    36 
    37 - ``link`` - Creates a link to a file
    38 
    39 - ``symlink`` - Creates a symbolic link to a file
    40 
    41 - ``readlink`` - Obtain the name of the link destination
    42 
    43 - ``mkdir`` - Makes a directory
    44 
    45 - ``mkfifo`` - Makes a FIFO special file
    46 
    47 - ``unlink`` - Removes a directory entry
    48 
    49 - ``rmdir`` - Delete a directory
    50 
    51 - ``rename`` - Renames a file
    52 
    53 - ``stat`` - Gets information about a file.
    54 
    55 - ``fstat`` - Gets file status
    56 
    57 - ``lstat`` - Gets file status
    58 
    59 - ``access`` - Check permissions for a file.
    60 
    61 - ``chmod`` - Changes file mode
    62 
    63 - ``fchmod`` - Changes permissions of a file
    64 
    65 - ``chown`` - Changes the owner and/ or group of a file
    66 
    67 - ``utime`` - Change access and/or modification times of an inode
    68 
    69 - ``ftruncate`` - Truncate a file to a specified length
    70 
    71 - ``truncate`` - Truncate a file to a specified length
    72 
    73 - ``pathconf`` - Gets configuration values for files
    74 
    75 - ``fpathconf`` - Get configuration values for files
    76 
    77 - ``mknod`` - Create a directory
     15- opendir_ - Open a Directory
     16
     17- readdir_ - Reads a directory
     18
     19- rewinddir_ - Resets the ``readdir()`` pointer
     20
     21- scandir_ - Scan a directory for matching entries
     22
     23- telldir_ - Return current location in directory stream
     24
     25- closedir_ - Ends directory read operation
     26
     27- getdents_ - Get directory entries
     28
     29- chdir_ - Changes the current working directory
     30
     31- fchdir_ - Changes the current working directory
     32
     33- getcwd_ - Gets current working directory
     34
     35- open_ - Opens a file
     36
     37- creat_ - Create a new file or rewrite an existing one
     38
     39- umask_ - Sets a file creation mask
     40
     41- link_ - Creates a link to a file
     42
     43- symlink_ - Creates a symbolic link to a file
     44
     45- readlink_ - Obtain the name of the link destination
     46
     47- mkdir_ - Makes a directory
     48
     49- mkfifo_ - Makes a FIFO special file
     50
     51- unlink_ - Removes a directory entry
     52
     53- rmdir_ - Delete a directory
     54
     55- rename_ - Renames a file
     56
     57- stat_ - Gets information about a file.
     58
     59- fstat_ - Gets file status
     60
     61- lstat_ - Gets file status
     62
     63- access_ - Check permissions for a file.
     64
     65- chmod_ - Changes file mode
     66
     67- fchmod_ - Changes permissions of a file
     68
     69- chown_ - Changes the owner and/ or group of a file
     70
     71- utime_ - Change access and/or modification times of an inode
     72
     73- ftruncate_ - Truncate a file to a specified length
     74
     75- truncate_ - Truncate a file to a specified length
     76
     77- pathconf_ - Gets configuration values for files
     78
     79- fpathconf_ - Get configuration values for files
     80
     81- mknod_ - Create a directory
    7882
    7983Background
     
    8387--------------------
    8488
    85 A pathname is a string that consists of no more than ``PATH_MAX``
    86 bytes, including the terminating null character. A pathname has an optional
    87 beginning slash, followed by zero or more filenames separated by slashes.
    88 If the pathname refers to a directory, it may also have one or more trailing
    89 slashes. Multiple successive slahes are considered to be the same as
    90 one slash.
     89A pathname is a string that consists of no more than ``PATH_MAX`` bytes,
     90including the terminating null character. A pathname has an optional beginning
     91slash, followed by zero or more filenames separated by slashes.  If the
     92pathname refers to a directory, it may also have one or more trailing
     93slashes. Multiple successive slahes are considered to be the same as one slash.
    9194
    9295POSIX allows a pathname that begins with precisely two successive slashes to be
    9396interpreted in an implementation-defined manner. RTEMS does not currently
    94 recognize this as a special condition. Any number of successive
    95 slashes is treated the same as a single slash. POSIX requires that
    96 an implementation treat more than two leading slashes as a single slash.
     97recognize this as a special condition. Any number of successive slashes is
     98treated the same as a single slash. POSIX requires that an implementation treat
     99more than two leading slashes as a single slash.
    97100
    98101Operations
     
    104107==========
    105108
    106 This section details the files and directories manager's directives.
    107 A subsection is dedicated to each of this manager's directives
    108 and describes the calling sequence, related constants, usage,
    109 and status codes.
     109This section details the files and directories manager's directives.  A
     110subsection is dedicated to each of this manager's directives and describes the
     111calling sequence, related constants, usage, and status codes.
     112
     113.. _opendir:
    110114
    111115opendir - Open a Directory
     
    116120**CALLING SEQUENCE:**
    117121
    118 .. code:: c
     122.. code-block:: c
    119123
    120124    #include <sys/types.h>
    121125    #include <dirent.h>
    122126    int opendir(
    123     const char \*dirname
    124     );
    125 
    126 **STATUS CODES:**
    127 
    128 *EACCES*
    129     Search permission was denied on a component of the path
    130     prefix of ``dirname``, or read permission is denied
    131 
    132 *EMFILE*
    133     Too many file descriptors in use by process
    134 
    135 *ENFILE*
    136     Too many files are currently open in the system.
    137 
    138 *ENOENT*
    139     Directory does not exist, or ``name`` is an empty string.
    140 
    141 *ENOMEM*
    142     Insufficient memory to complete the operation.
    143 
    144 *ENOTDIR*
    145     ``name`` is not a directory.
     127        const char *dirname
     128    );
     129
     130**STATUS CODES:**
     131
     132.. list-table::
     133 :class: rtems-table
     134
     135 * - ``EACCES``
     136   - Search permission was denied on a component of the path prefix of
     137     ``dirname``, or read permission is denied
     138 * - ``EMFILE``
     139   - Too many file descriptors in use by process
     140 * - ``ENFILE``
     141   - Too many files are currently open in the system.
     142 * - ``ENOENT``
     143   - Directory does not exist, or ``name`` is an empty string.
     144 * - ``ENOMEM``
     145   - Insufficient memory to complete the operation.
     146 * - ``ENOTDIR``
     147   - ``name`` is not a directory.
    146148
    147149**DESCRIPTION:**
     
    154156
    155157The routine is implemented in Cygnus newlib.
     158
     159.. _readdir:
    156160
    157161readdir - Reads a directory
     
    162166**CALLING SEQUENCE:**
    163167
    164 .. code:: c
     168.. code-block:: c
    165169
    166170    #include <sys/types.h>
    167171    #include <dirent.h>
    168     int readdir(
    169     DIR \*dirp
    170     );
    171 
    172 **STATUS CODES:**
    173 
    174 *EBADF*
    175     Invalid file descriptor
     172        int readdir(
     173        DIR *dirp
     174    );
     175
     176**STATUS CODES:**
     177
     178.. list-table::
     179 :class: rtems-table
     180
     181 * - ``EBADF``
     182   - Invalid file descriptor
    176183
    177184**DESCRIPTION:**
    178185
    179186The ``readdir()`` function returns a pointer to a structure ``dirent``
    180 representing the next directory entry from the directory stream pointed to
    181 by ``dirp``. On end-of-file, NULL is returned.
    182 
    183 The ``readdir()`` function may (or may not) return entries for . or .. Your
    184 program should tolerate reading dot and dot-dot but not require them.
    185 
    186 The data pointed to be ``readdir()`` may be overwritten by another call to``readdir()`` for the same directory stream. It will not be overwritten by
    187 a call for another directory.
    188 
    189 **NOTES:**
    190 
    191 If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or``realloc()`` or has been deallocated with ``free()`` or``realloc()``, the results are not portable and are probably disastrous.
     187representing the next directory entry from the directory stream pointed to by
     188``dirp``. On end-of-file, ``NULL`` is returned.
     189
     190The ``readdir()`` function may (or may not) return entries for ``.`` or ``..``
     191Your program should tolerate reading dot and dot-dot but not require them.
     192
     193The data pointed to be ``readdir()`` may be overwritten by another call to
     194``readdir()`` for the same directory stream. It will not be overwritten by a
     195call for another directory.
     196
     197**NOTES:**
     198
     199If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or
     200``realloc()`` or has been deallocated with ``free()`` or ``realloc()``, the
     201results are not portable and are probably disastrous.
    192202
    193203The routine is implemented in Cygnus newlib.
     204
     205.. _rewinddir:
    194206
    195207rewinddir - Resets the readdir() pointer
     
    200212**CALLING SEQUENCE:**
    201213
    202 .. code:: c
     214.. code-block:: c
    203215
    204216    #include <sys/types.h>
    205217    #include <dirent.h>
    206218    void rewinddir(
    207     DIR \*dirp
     219        DIR *dirp
    208220    );
    209221
     
    214226**DESCRIPTION:**
    215227
    216 The ``rewinddir()`` function resets the position associated with
    217 the directory stream pointed to by ``dirp``. It also causes the
    218 directory stream to refer to the current state of the directory.
    219 
    220 **NOTES:**
    221 
    222 NONE
    223 
    224 If ``dirp`` is not a pointer by ``opendir()``, the results are
    225 undefined.
     228The ``rewinddir()`` function resets the position associated with the directory
     229stream pointed to by ``dirp``. It also causes the directory stream to refer to
     230the current state of the directory.
     231
     232**NOTES:**
     233
     234NONE
     235
     236If ``dirp`` is not a pointer by ``opendir()``, the results are undefined.
    226237
    227238The routine is implemented in Cygnus newlib.
     239
     240.. _scandir:
    228241
    229242scandir - Scan a directory for matching entries
     
    234247**CALLING SEQUENCE:**
    235248
    236 .. code:: c
     249.. code-block:: c
    237250
    238251    #include <dirent.h>
    239252    int scandir(
    240     const char       \*dir,
    241     struct dirent \***namelist,
    242     int  (\*select)(const struct dirent \*),
    243     int  (\*compar)(const struct dirent \**, const struct dirent \**)
    244     );
    245 
    246 **STATUS CODES:**
    247 
    248 *ENOMEM*
    249     Insufficient memory to complete the operation.
    250 
    251 **DESCRIPTION:**
    252 
    253 The ``scandir()`` function scans the directory ``dir``, calling``select()`` on each directory entry. Entries for which ``select()``
    254 returns non-zero are stored in strings allocated via ``malloc()``,
    255 sorted using ``qsort()`` with the comparison function ``compar()``,
    256 and collected in array ``namelist`` which is allocated via ``malloc()``.
    257 If ``select`` is NULL, all entries are selected.
     253        const char       *dir,
     254        struct dirent ***namelist,
     255        int  (*select)(const struct dirent *),
     256        int  (*compar)(const struct dirent **, const struct dirent **)
     257    );
     258
     259**STATUS CODES:**
     260
     261.. list-table::
     262 :class: rtems-table
     263
     264 * - ``ENOMEM``
     265   - Insufficient memory to complete the operation.
     266
     267**DESCRIPTION:**
     268
     269The ``scandir()`` function scans the directory ``dir``, calling ``select()`` on
     270each directory entry. Entries for which ``select()`` returns non-zero are
     271stored in strings allocated via ``malloc()``, sorted using ``qsort()`` with the
     272comparison function ``compar()``, and collected in array ``namelist`` which is
     273allocated via ``malloc()``.  If ``select`` is ``NULL``, all entries are
     274selected.
    258275
    259276**NOTES:**
    260277
    261278The routine is implemented in Cygnus newlib.
     279
     280.. _telldir:
    262281
    263282telldir - Return current location in directory stream
     
    268287**CALLING SEQUENCE:**
    269288
    270 .. code:: c
     289.. code-block:: c
    271290
    272291    #include <dirent.h>
    273292    off_t telldir(
    274     DIR \*dir
    275     );
    276 
    277 **STATUS CODES:**
    278 
    279 *EBADF*
    280     Invalid directory stream descriptor ``dir``.
     293        DIR *dir
     294    );
     295
     296**STATUS CODES:**
     297
     298.. list-table::
     299 :class: rtems-table
     300
     301 * - ``EBADF``
     302   - Invalid directory stream descriptor ``dir``.
    281303
    282304**DESCRIPTION:**
     
    288310
    289311The routine is implemented in Cygnus newlib.
     312
     313.. _closedir:
    290314
    291315closedir - Ends directory read operation
     
    296320**CALLING SEQUENCE:**
    297321
    298 .. code:: c
     322.. code-block:: c
    299323
    300324    #include <sys/types.h>
    301325    #include <dirent.h>
    302326    int closedir(
    303     DIR \*dirp
    304     );
    305 
    306 **STATUS CODES:**
    307 
    308 *EBADF*
    309     Invalid file descriptor
    310 
    311 **DESCRIPTION:**
    312 
    313 The directory stream associated with ``dirp`` is closed.
    314 The value in ``dirp`` may not be usable after a call to``closedir()``.
    315 
    316 **NOTES:**
    317 
    318 NONE
    319 
    320 The argument to ``closedir()`` must be a pointer returned by``opendir()``. If it is not, the results are not portable and
    321 most likely unpleasant.
     327        DIR *dirp
     328    );
     329
     330**STATUS CODES:**
     331
     332.. list-table::
     333 :class: rtems-table
     334
     335 * - ``EBADF``
     336   - Invalid file descriptor
     337
     338**DESCRIPTION:**
     339
     340The directory stream associated with ``dirp`` is closed.  The value in ``dirp``
     341may not be usable after a call to ``closedir()``.
     342
     343**NOTES:**
     344
     345NONE
     346
     347The argument to ``closedir()`` must be a pointer returned by ``opendir()``. If
     348it is not, the results are not portable and most likely unpleasant.
    322349
    323350The routine is implemented in Cygnus newlib.
     351
     352.. _chdir:
    324353
    325354chdir - Changes the current working directory
     
    330359**CALLING SEQUENCE:**
    331360
    332 .. code:: c
     361.. code-block:: c
    333362
    334363    #include <unistd.h>
    335364    int chdir(
    336     const char \*path
    337     );
    338 
    339 **STATUS CODES:**
    340 
    341 On error, this routine returns -1 and sets ``errno`` to one of
    342 the following:
    343 
    344 *EACCES*
    345     Search permission is denied for a directory in a file's path prefix.
    346 
    347 *ENAMETOOLONG*
    348     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
    349     in effect.
    350 
    351 *ENOENT*
    352     A file or directory does not exist.
    353 
    354 *ENOTDIR*
    355     A component of the specified pathname was not a directory when directory
    356     was expected.
    357 
    358 **DESCRIPTION:**
    359 
    360 The ``chdir()`` function causes the directory named by ``path`` to
    361 become the current working directory; that is, the starting point for
    362 searches of pathnames not beginning with a slash.
    363 
    364 If ``chdir()`` detects an error, the current working directory is not
    365 changed.
    366 
    367 **NOTES:**
    368 
    369 NONE
     365        const char *path
     366    );
     367
     368**STATUS CODES:**
     369
     370On error, this routine returns -1 and sets ``errno`` to one of the following:
     371
     372.. list-table::
     373 :class: rtems-table
     374
     375 * - ``EACCES``
     376   - Search permission is denied for a directory in a file's path prefix.
     377 * - ``ENAMETOOLONG``
     378   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     379     is in effect.
     380 * - ``ENOENT``
     381   - A file or directory does not exist.
     382 * - ``ENOTDIR``
     383   - A component of the specified pathname was not a directory when directory
     384     was expected.
     385
     386**DESCRIPTION:**
     387
     388The ``chdir()`` function causes the directory named by ``path`` to become the
     389current working directory; that is, the starting point for searches of
     390pathnames not beginning with a slash.
     391
     392If ``chdir()`` detects an error, the current working directory is not changed.
     393
     394**NOTES:**
     395
     396NONE
     397
     398.. _fchdir:
    370399
    371400fchdir - Changes the current working directory
     
    376405**CALLING SEQUENCE:**
    377406
    378 .. code:: c
     407.. code-block:: c
    379408
    380409    #include <unistd.h>
    381410    int fchdir(
    382     int fd
    383     );
    384 
    385 **STATUS CODES:**
    386 
    387 On error, this routine returns -1 and sets ``errno`` to one of
    388 the following:
    389 
    390 *EACCES*
    391     Search permission is denied for a directory in a file's path prefix.
    392 
    393 *ENAMETOOLONG*
    394     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
    395     in effect.
    396 
    397 *ENOENT*
    398     A file or directory does not exist.
    399 
    400 *ENOTDIR*
    401     A component of the specified pathname was not a directory when directory
    402     was expected.
    403 
    404 **DESCRIPTION:**
    405 
    406 The ``fchdir()`` function causes the directory named by ``fd`` to
    407 become the current working directory; that is, the starting point for
    408 searches of pathnames not beginning with a slash.
    409 
    410 If ``fchdir()`` detects an error, the current working directory is not
    411 changed.
    412 
    413 **NOTES:**
    414 
    415 NONE
     411        int fd
     412    );
     413
     414**STATUS CODES:**
     415
     416On error, this routine returns -1 and sets ``errno`` to one of the following:
     417
     418.. list-table::
     419 :class: rtems-table
     420
     421 * - ``EACCES``
     422   - Search permission is denied for a directory in a file's path prefix.
     423 * - ``ENAMETOOLONG``
     424   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     425     is in effect.
     426 * - ``ENOENT``
     427   - A file or directory does not exist.
     428 * - ``ENOTDIR``
     429   - A component of the specified pathname was not a directory when directory
     430     was expected.
     431
     432**DESCRIPTION:**
     433
     434The ``fchdir()`` function causes the directory named by ``fd`` to become the
     435current working directory; that is, the starting point for searches of
     436pathnames not beginning with a slash.
     437
     438If ``fchdir()`` detects an error, the current working directory is not changed.
     439
     440**NOTES:**
     441
     442NONE
     443
     444.. _getcwd:
    416445
    417446getcwd - Gets current working directory
     
    422451**CALLING SEQUENCE:**
    423452
    424 .. code:: c
     453.. code-block:: c
    425454
    426455    #include <unistd.h>
     
    429458**STATUS CODES:**
    430459
    431 *EINVAL*
    432     Invalid argument
    433 
    434 *ERANGE*
    435     Result is too large
    436 
    437 *EACCES*
    438     Search permission is denied for a directory in a file's path prefix.
    439 
    440 **DESCRIPTION:**
    441 
    442 The ``getcwd()`` function copies the absolute pathname of the current
    443 working directory to the character array pointed to by ``buf``. The``size`` argument is the number of bytes available in ``buf``
    444 
    445 **NOTES:**
    446 
    447 There is no way to determine the maximum string length that ``fetcwd()``
    448 may need to return. Applications should tolerate getting ``ERANGE``
    449 and allocate a larger buffer.
    450 
    451 It is possible for ``getcwd()`` to return EACCES if, say, ``login``
    452 puts the process into a directory without read access.
    453 
    454 The 1988 standard uses ``int`` instead of ``size_t`` for the second
    455 parameter.
     460.. list-table::
     461 :class: rtems-table
     462
     463 * - ``EINVAL``
     464   - Invalid argument
     465 * - ``ERANGE``
     466   - Result is too large
     467 * - ``EACCES``
     468   - Search permission is denied for a directory in a file's path prefix.
     469
     470**DESCRIPTION:**
     471
     472The ``getcwd()`` function copies the absolute pathname of the current working
     473directory to the character array pointed to by ``buf``. The ``size`` argument
     474is the number of bytes available in ``buf``
     475
     476**NOTES:**
     477
     478There is no way to determine the maximum string length that ``fetcwd()`` may
     479need to return. Applications should tolerate getting ``ERANGE`` and allocate a
     480larger buffer.
     481
     482It is possible for ``getcwd()`` to return EACCES if, say, ``login`` puts the
     483process into a directory without read access.
     484
     485The 1988 standard uses ``int`` instead of ``size_t`` for the second parameter.
     486
     487.. _open:
    456488
    457489open - Opens a file
     
    462494**CALLING SEQUENCE:**
    463495
    464 .. code:: c
     496.. code-block:: c
    465497
    466498    #include <sys/types.h>
     
    468500    #include <fcntl.h>
    469501    int open(
    470     const char \*path,
    471     int         oflag,
    472     mode_t      mode
    473     );
    474 
    475 **STATUS CODES:**
    476 
    477 *EACCES*
    478     Search permission is denied for a directory in a file's path prefix.
    479 
    480 *EEXIST*
    481     The named file already exists.
    482 
    483 *EINTR*
    484     Function was interrupted by a signal.
    485 
    486 *EISDIR*
    487     Attempt to open a directory for writing or to rename a file to be a
    488     directory.
    489 
    490 *EMFILE*
    491     Too many file descriptors are in use by this process.
    492 
    493 *ENAMETOOLONG*
    494     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    495     effect.
    496 
    497 *ENFILE*
    498     Too many files are currently open in the system.
    499 
    500 *ENOENT*
    501     A file or directory does not exist.
    502 
    503 *ENOSPC*
    504     No space left on disk.
    505 
    506 *ENOTDIR*
    507     A component of the specified pathname was not a directory when a directory
    508     was expected.
    509 
    510 *ENXIO*
    511     No such device. This error may also occur when a device is not ready, for
    512     example, a tape drive is off-line.
    513 
    514 *EROFS*
    515     Read-only file system.
     502        const char *path,
     503        int         oflag,
     504        mode_t      mode
     505    );
     506
     507**STATUS CODES:**
     508
     509.. list-table::
     510 :class: rtems-table
     511
     512 * - ``EACCES``
     513   - Search permission is denied for a directory in a file's path prefix.
     514 * - ``EEXIST``
     515   - The named file already exists.
     516 * - ``EINTR``
     517   - Function was interrupted by a signal.
     518 * - ``EISDIR``
     519   - Attempt to open a directory for writing or to rename a file to be a
     520     directory.
     521 * - ``EMFILE``
     522   - Too many file descriptors are in use by this process.
     523 * - ``ENAMETOOLONG``
     524   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     525     is in effect.
     526 * - ``ENFILE``
     527   - Too many files are currently open in the system.
     528 * - ``ENOENT``
     529   - A file or directory does not exist.
     530 * - ``ENOSPC``
     531   - No space left on disk.
     532 * - ``ENOTDIR``
     533   - A component of the specified pathname was not a directory when a directory
     534     was expected.
     535 * - ``ENXIO``
     536   - No such device. This error may also occur when a device is not ready, for
     537     example, a tape drive is off-line.
     538 * - ``EROFS``
     539   - Read-only file system.
    516540
    517541**DESCRIPTION:**
     
    519543The ``open`` function establishes a connection between a file and a file
    520544descriptor. The file descriptor is a small integer that is used by I/O
    521 functions to reference the file. The ``path`` argument points to the
    522 pathname for the file.
    523 
    524 The ``oflag`` argument is the bitwise inclusive OR of the values of
    525 symbolic constants. The programmer must specify exactly one of the following
    526 three symbols:
    527 
    528 *O_RDONLY*
    529     Open for reading only.
    530 
    531 *O_WRONLY*
    532     Open for writing only.
    533 
    534 *O_RDWR*
    535     Open for reading and writing.
     545functions to reference the file. The ``path`` argument points to the pathname
     546for the file.
     547
     548The ``oflag`` argument is the bitwise inclusive OR of the values of symbolic
     549constants. The programmer must specify exactly one of the following three
     550symbols:
     551
     552.. list-table::
     553 :class: rtems-table
     554
     555 * - ``O_RDONLY``
     556   - Open for reading only.
     557 * - ``O_WRONLY``
     558   - Open for writing only.
     559 * - ``O_RDWR``
     560   - Open for reading and writing.
    536561
    537562Any combination of the following symbols may also be used.
    538563
    539 *O_APPEND*
    540     Set the file offset to the end-of-file prior to each write.
    541 
    542 *O_CREAT*
    543     If the file does not exist, allow it to be created. This flag indicates
    544     that the ``mode`` argument is present in the call to ``open``.
    545 
    546 *O_EXCL*
    547     This flag may be used only if O_CREAT is also set. It causes the call
    548     to ``open`` to fail if the file already exists.
    549 
    550 *O_NOCTTY*
    551     If ``path`` identifies a terminal, this flag prevents that teminal from
    552     becoming the controlling terminal for thi9s process. See Chapter 8 for a
    553     description of terminal I/O.
    554 
    555 *O_NONBLOCK*
    556     Do no wait for the device or file to be ready or available. After the file
    557     is open, the ``read`` and ``write`` calls return immediately. If the
    558     process would be delayed in the read or write opermation, -1 is returned and``errno`` is set to ``EAGAIN`` instead of blocking the caller.
    559 
    560 *O_TRUNC*
    561     This flag should be used only on ordinary files opened for writing. It
    562     causes the file to be tuncated to zero length..
    563 
    564 Upon successful completion, ``open`` returns a non-negative file
    565 descriptor.
    566 
    567 **NOTES:**
    568 
    569 NONE
     564.. list-table::
     565 :class: rtems-table
     566
     567 * - ``O_APPEND``
     568   - Set the file offset to the end-of-file prior to each write.
     569 * - ``O_CREAT``
     570   - If the file does not exist, allow it to be created. This flag indicates
     571     that the ``mode`` argument is present in the call to ``open``.
     572 * - ``O_EXCL``
     573   - This flag may be used only if ``O_CREAT`` is also set. It causes the call
     574     to ``open`` to fail if the file already exists.
     575 * - ``O_NOCTTY``
     576   - Do not assign controlling terminal.
     577 * - ``O_NONBLOCK``
     578   - Do no wait for the device or file to be ready or available. After the file
     579     is open, the ``read`` and ``write`` calls return immediately. If the
     580     process would be delayed in the read or write opermation, -1 is returned
     581     and``errno`` is set to ``EAGAIN`` instead of blocking the caller.
     582 * - ``O_TRUNC``
     583   - This flag should be used only on ordinary files opened for writing. It
     584     causes the file to be tuncated to zero length..
     585
     586Upon successful completion, ``open`` returns a non-negative file descriptor.
     587
     588**NOTES:**
     589
     590NONE
     591
     592.. _creat:
    570593
    571594creat - Create a new file or rewrite an existing one
     
    576599**CALLING SEQUENCE:**
    577600
    578 .. code:: c
     601.. code-block:: c
    579602
    580603    #include <sys/types.h>
     
    582605    #include <fcntl.h>
    583606    int creat(
    584     const char \*path,
    585     mode_t      mode
    586     );
    587 
    588 **STATUS CODES:**
    589 
    590 *EEXIST*
    591     ``path`` already exists and O_CREAT and O_EXCL were used.
    592 
    593 *EISDIR*
    594     ``path`` refers to a directory and the access requested involved
    595     writing
    596 
    597 *ETXTBSY*
    598     ``path`` refers to an executable image which is currently being
    599     executed and write access was requested
    600 
    601 *EFAULT*
    602     ``path`` points outside your accessible address space
    603 
    604 *EACCES*
    605     The requested access to the file is not allowed, or one of the
    606     directories in ``path`` did not allow search (execute) permission.
    607 
    608 *ENAMETOOLONG*
    609     ``path`` was too long.
    610 
    611 *ENOENT*
    612     A directory component in ``path`` does not exist or is a dangling
    613     symbolic link.
    614 
    615 *ENOTDIR*
    616     A component used as a directory in ``path`` is not, in fact, a
    617     directory.
    618 
    619 *EMFILE*
    620     The process alreadyh has the maximum number of files open.
    621 
    622 *ENFILE*
    623     The limit on the total number of files open on the system has been
    624     reached.
    625 
    626 *ENOMEM*
    627     Insufficient kernel memory was available.
    628 
    629 *EROFS*
    630     ``path`` refers to a file on a read-only filesystem and write access
    631     was requested
    632 
    633 **DESCRIPTION:**
    634 
    635 ``creat`` attempts to create a file and return a file descriptor for
    636 use in read, write, etc.
     607        const char *path,
     608        mode_t      mode
     609    );
     610
     611**STATUS CODES:**
     612
     613.. list-table::
     614 :class: rtems-table
     615
     616 * - ``EEXIST``
     617   - ``path`` already exists and ``O_CREAT`` and ``O_EXCL`` were used.
     618 * - ``EISDIR``
     619   - ``path`` refers to a directory and the access requested involved writing
     620 * - ``ETXTBSY``
     621   - ``path`` refers to an executable image which is currently being executed
     622     and write access was requested
     623 * - ``EFAULT``
     624   - ``path`` points outside your accessible address space
     625 * - ``EACCES``
     626   - The requested access to the file is not allowed, or one of the directories
     627     in ``path`` did not allow search (execute) permission.
     628 * - ``ENAMETOOLONG``
     629   - ``path`` was too long.
     630 * - ``ENOENT``
     631   - A directory component in ``path`` does not exist or is a dangling symbolic
     632     link.
     633 * - ``ENOTDIR``
     634   - A component used as a directory in ``path`` is not, in fact, a directory.
     635 * - ``EMFILE``
     636   - The process alreadyh has the maximum number of files open.
     637 * - ``ENFILE``
     638   - The limit on the total number of files open on the system has been
     639     reached.
     640 * - ``ENOMEM``
     641   - Insufficient kernel memory was available.
     642 * - ``EROFS``
     643   - ``path`` refers to a file on a read-only filesystem and write access was
     644     requested
     645
     646**DESCRIPTION:**
     647
     648``creat`` attempts to create a file and return a file descriptor for use in
     649read, write, etc.
    637650
    638651**NOTES:**
     
    641654
    642655The routine is implemented in Cygnus newlib.
     656
     657.. _umask:
    643658
    644659umask - Sets a file creation mask.
     
    649664**CALLING SEQUENCE:**
    650665
    651 .. code:: c
     666.. code-block:: c
    652667
    653668    #include <sys/types.h>
    654669    #include <sys/stat.h>
    655670    mode_t umask(
    656     mode_t cmask
    657     );
    658 
    659 **STATUS CODES:**
    660 
    661 **DESCRIPTION:**
    662 
    663 The ``umask()`` function sets the process file creation mask to ``cmask``.
    664 The file creation mask is used during ``open()``, ``creat()``, ``mkdir()``,``mkfifo()`` calls to turn off permission bits in the ``mode`` argument.
    665 Bit positions that are set in ``cmask`` are cleared in the mode of the
    666 created file.
    667 
    668 **NOTES:**
    669 
    670 NONE
    671 
    672 The ``cmask`` argument should have only permission bits set. All other
    673 bits should be zero.
    674 
    675 In a system which supports multiple processes, the file creation mask is inherited
    676 across ``fork()`` and ``exec()`` calls. This makes it possible to alter the
    677 default permission bits of created files. RTEMS does not support multiple processes
    678 so this behavior is not possible.
     671        mode_t cmask
     672    );
     673
     674**STATUS CODES:**
     675
     676**DESCRIPTION:**
     677
     678The ``umask()`` function sets the process file creation mask to ``cmask``.  The
     679file creation mask is used during ``open()``, ``creat()``, ``mkdir()``,
     680``mkfifo()`` calls to turn off permission bits in the ``mode`` argument.  Bit
     681positions that are set in ``cmask`` are cleared in the mode of the created
     682file.
     683
     684**NOTES:**
     685
     686NONE
     687
     688The ``cmask`` argument should have only permission bits set. All other bits
     689should be zero.
     690
     691In a system which supports multiple processes, the file creation mask is
     692inherited across ``fork()`` and ``exec()`` calls. This makes it possible to
     693alter the default permission bits of created files. RTEMS does not support
     694multiple processes so this behavior is not possible.
     695
     696.. _link:
    679697
    680698link - Creates a link to a file
     
    685703**CALLING SEQUENCE:**
    686704
    687 .. code:: c
     705.. code-block:: c
    688706
    689707    #include <unistd.h>
    690708    int link(
    691     const char \*existing,
    692     const char \*new
    693     );
    694 
    695 **STATUS CODES:**
    696 
    697 *EACCES*
    698     Search permission is denied for a directory in a file's path prefix
    699 
    700 *EEXIST*
    701     The named file already exists.
    702 
    703 *EMLINK*
    704     The number of links would exceed ``LINK_MAX``.
    705 
    706 *ENAMETOOLONG*
    707     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    708     effect.
    709 
    710 *ENOENT*
    711     A file or directory does not exist.
    712 
    713 *ENOSPC*
    714     No space left on disk.
    715 
    716 *ENOTDIR*
    717     A component of the specified pathname was not a directory when a directory
    718     was expected.
    719 
    720 *EPERM*
    721     Operation is not permitted. Process does not have the appropriate priviledges
    722     or permissions to perform the requested operations.
    723 
    724 *EROFS*
    725     Read-only file system.
    726 
    727 *EXDEV*
    728     Attempt to link a file to another file system.
    729 
    730 **DESCRIPTION:**
    731 
    732 The ``link()`` function atomically creates a new link for an existing file
    733 and increments the link count for the file.
     709        const char *existing,
     710        const char *new
     711    );
     712
     713**STATUS CODES:**
     714
     715.. list-table::
     716 :class: rtems-table
     717
     718 * - ``EACCES``
     719   - Search permission is denied for a directory in a file's path prefix
     720 * - ``EEXIST``
     721   - The named file already exists.
     722 * - ``EMLINK``
     723   - The number of links would exceed ``LINK_MAX``.
     724 * - ``ENAMETOOLONG``
     725   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     726     is in effect.
     727 * - ``ENOENT``
     728   - A file or directory does not exist.
     729 * - ``ENOSPC``
     730   - No space left on disk.
     731 * - ``ENOTDIR``
     732   - A component of the specified pathname was not a directory when a directory
     733     was expected.
     734 * - ``EPERM``
     735   - Operation is not permitted. Process does not have the appropriate
     736     priviledges or permissions to perform the requested operations.
     737 * - ``EROFS``
     738   - Read-only file system.
     739 * - ``EXDEV``
     740   - Attempt to link a file to another file system.
     741
     742**DESCRIPTION:**
     743
     744The ``link()`` function atomically creates a new link for an existing file and
     745increments the link count for the file.
    734746
    735747If the ``link()`` function fails, no directories are modified.
     
    742754
    743755NONE
     756
     757.. _symlink:
    744758
    745759symlink - Creates a symbolic link to a file
     
    750764**CALLING SEQUENCE:**
    751765
    752 .. code:: c
     766.. code-block:: c
    753767
    754768    #include <unistd.h>
    755769    int symlink(
    756     const char \*topath,
    757     const char \*frompath
    758     );
    759 
    760 **STATUS CODES:**
    761 
    762 *EACCES*
    763     Search permission is denied for a directory in a file's path prefix
    764 
    765 *EEXIST*
    766     The named file already exists.
    767 
    768 *ENAMETOOLONG*
    769     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    770     effect.
    771 
    772 *ENOENT*
    773     A file or directory does not exist.
    774 
    775 *ENOSPC*
    776     No space left on disk.
    777 
    778 *ENOTDIR*
    779     A component of the specified pathname was not a directory when a directory
    780     was expected.
    781 
    782 *EPERM*
    783     Operation is not permitted. Process does not have the appropriate priviledges
    784     or permissions to perform the requested operations.
    785 
    786 *EROFS*
    787     Read-only file system.
     770        const char *topath,
     771        const char *frompath
     772    );
     773
     774**STATUS CODES:**
     775
     776.. list-table::
     777 :class: rtems-table
     778
     779 * - ``EACCES``
     780   - Search permission is denied for a directory in a file's path prefix
     781 * - ``EEXIST``
     782   - The named file already exists.
     783 * - ``ENAMETOOLONG``
     784   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     785     is in effect.
     786 * - ``ENOENT``
     787   - A file or directory does not exist.
     788 * - ``ENOSPC``
     789   - No space left on disk.
     790 * - ``ENOTDIR``
     791   - A component of the specified pathname was not a directory when a directory
     792     was expected.
     793 * - ``EPERM``
     794   - Operation is not permitted. Process does not have the appropriate
     795     priviledges or permissions to perform the requested operations.
     796 * - ``EROFS``
     797   - Read-only file system.
    788798
    789799**DESCRIPTION:**
     
    799809
    800810NONE
     811
     812.. _readlink:
    801813
    802814readlink - Obtain the name of a symbolic link destination
     
    807819**CALLING SEQUENCE:**
    808820
    809 .. code:: c
     821.. code-block:: c
    810822
    811823    #include <unistd.h>
    812824    int readlink(
    813     const char \*path,
    814     char       \*buf,
    815     size_t      bufsize
    816     );
    817 
    818 **STATUS CODES:**
    819 
    820 *EACCES*
    821     Search permission is denied for a directory in a file's path prefix
    822 
    823 *ENAMETOOLONG*
    824     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    825     effect.
    826 
    827 *ENOENT*
    828     A file or directory does not exist.
    829 
    830 *ENOTDIR*
    831     A component of the prefix pathname was not a directory when a directory
    832     was expected.
    833 
    834 *ELOOP*
    835     Too many symbolic links were encountered in the pathname.
    836 
    837 *EINVAL*
    838     The pathname does not refer to a symbolic link
    839 
    840 *EFAULT*
    841     An invalid pointer was passed into the ``readlink()`` routine.
    842 
    843 **DESCRIPTION:**
    844 
    845 The ``readlink()`` function places the symbolic link destination into``buf`` argument and returns the number of characters copied.
    846 
    847 If the symbolic link destination is longer than bufsize characters the
    848 name will be truncated.
    849 
    850 **NOTES:**
    851 
    852 NONE
     825        const char *path,
     826        char       *buf,
     827        size_t      bufsize
     828    );
     829
     830**STATUS CODES:**
     831
     832.. list-table::
     833 :class: rtems-table
     834
     835 * - ``EACCES``
     836   - Search permission is denied for a directory in a file's path prefix
     837 * - ``ENAMETOOLONG``
     838   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     839     is in effect.
     840 * - ``ENOENT``
     841   - A file or directory does not exist.
     842 * - ``ENOTDIR``
     843   - A component of the prefix pathname was not a directory when a directory
     844     was expected.
     845 * - ``ELOOP``
     846   - Too many symbolic links were encountered in the pathname.
     847 * - ``EINVAL``
     848   - The pathname does not refer to a symbolic link
     849 * - ``EFAULT``
     850   - An invalid pointer was passed into the ``readlink()`` routine.
     851
     852**DESCRIPTION:**
     853
     854The ``readlink()`` function places the symbolic link destination into ``buf``
     855argument and returns the number of characters copied.
     856
     857If the symbolic link destination is longer than bufsize characters the name
     858will be truncated.
     859
     860**NOTES:**
     861
     862NONE
     863
     864.. _mkdir:
    853865
    854866mkdir - Makes a directory
     
    859871**CALLING SEQUENCE:**
    860872
    861 .. code:: c
     873.. code-block:: c
    862874
    863875    #include <sys/types.h>
    864876    #include <sys/stat.h>
    865877    int mkdir(
    866     const char \*path,
    867     mode_t      mode
    868     );
    869 
    870 **STATUS CODES:**
    871 
    872 *EACCES*
    873     Search permission is denied for a directory in a file's path prefix
    874 
    875 *EEXIST*
    876     The name file already exist.
    877 
    878 *EMLINK*
    879     The number of links would exceed LINK_MAX
    880 
    881 *ENAMETOOLONG*
    882     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    883     effect.
    884 
    885 *ENOENT*
    886     A file or directory does not exist.
    887 
    888 *ENOSPC*
    889     No space left on disk.
    890 
    891 *ENOTDIR*
    892     A component of the specified pathname was not a directory when a directory
    893     was expected.
    894 
    895 *EROFS*
    896     Read-only file system.
    897 
    898 **DESCRIPTION:**
    899 
    900 The ``mkdir()`` function creates a new diectory named ``path``. The
    901 permission bits (modified by the file creation mask) are set from ``mode``.
    902 The owner and group IDs for the directory are set from the effective user ID
    903 and group ID.
    904 
    905 The new directory may (or may not) contain entries for.. and .. but is otherwise
    906 empty.
    907 
    908 **NOTES:**
    909 
    910 NONE
     878        const char *path,
     879        mode_t      mode
     880    );
     881
     882**STATUS CODES:**
     883
     884.. list-table::
     885 :class: rtems-table
     886
     887 * - ``EACCES``
     888   - Search permission is denied for a directory in a file's path prefix
     889 * - ``EEXIST``
     890   - The name file already exist.
     891 * - ``EMLINK``
     892   - The number of links would exceed ``LINK_MAX``
     893 * - ``ENAMETOOLONG``
     894   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     895     is in effect.
     896 * - ``ENOENT``
     897   - A file or directory does not exist.
     898 * - ``ENOSPC``
     899   - No space left on disk.
     900 * - ``ENOTDIR``
     901   - A component of the specified pathname was not a directory when a directory
     902     was expected.
     903 * - ``EROFS``
     904   - Read-only file system.
     905
     906**DESCRIPTION:**
     907
     908The ``mkdir()`` function creates a new diectory named ``path``. The permission
     909bits (modified by the file creation mask) are set from ``mode``.  The owner and
     910group IDs for the directory are set from the effective user ID and group ID.
     911
     912The new directory may (or may not) contain entries for ``.`` and ``..`` but is
     913otherwise empty.
     914
     915**NOTES:**
     916
     917NONE
     918
     919.. _mkfifo:
    911920
    912921mkfifo - Makes a FIFO special file
     
    917926**CALLING SEQUENCE:**
    918927
    919 .. code:: c
     928.. code-block:: c
    920929
    921930    #include <sys/types.h>
    922931    #include <sys/stat.h>
    923932    int mkfifo(
    924     const char \*path,
    925     mode_t      mode
    926     );
    927 
    928 **STATUS CODES:**
    929 
    930 *EACCES*
    931     Search permission is denied for a directory in a file's path prefix
    932 
    933 *EEXIST*
    934     The named file already exists.
    935 
    936 *ENOENT*
    937     A file or directory does not exist.
    938 
    939 *ENOSPC*
    940     No space left on disk.
    941 
    942 *ENOTDIR*
    943     A component of the specified ``path`` was not a directory when a directory
    944     was expected.
    945 
    946 *EROFS*
    947     Read-only file system.
    948 
    949 **DESCRIPTION:**
    950 
    951 The ``mkfifo()`` function creates a new FIFO special file named ``path``.
    952 The permission bits (modified by the file creation mask) are set from``mode``. The owner and group IDs for the FIFO are set from the efective
    953 user ID and group ID.
    954 
    955 **NOTES:**
    956 
    957 NONE
     933        const char *path,
     934        mode_t      mode
     935    );
     936
     937**STATUS CODES:**
     938
     939.. list-table::
     940 :class: rtems-table
     941
     942 * - ``EACCES``
     943   - Search permission is denied for a directory in a file's path prefix
     944 * - ``EEXIST``
     945   - The named file already exists.
     946 * - ``ENOENT``
     947   - A file or directory does not exist.
     948 * - ``ENOSPC``
     949   - No space left on disk.
     950 * - ``ENOTDIR``
     951   - A component of the specified ``path`` was not a directory when a directory
     952     was expected.
     953 * - ``EROFS``
     954   - Read-only file system.
     955
     956**DESCRIPTION:**
     957
     958The ``mkfifo()`` function creates a new FIFO special file named ``path``.  The
     959permission bits (modified by the file creation mask) are set from ``mode``. The
     960owner and group IDs for the FIFO are set from the efective user ID and
     961group ID.
     962
     963**NOTES:**
     964
     965NONE
     966
     967.. _unlink:
    958968
    959969unlink - Removes a directory entry
     
    964974**CALLING SEQUENCE:**
    965975
    966 .. code:: c
     976.. code-block:: c
    967977
    968978    #include <unistd.h>
    969979    int unlink(
    970     const char path
    971     );
    972 
    973 **STATUS CODES:**
    974 
    975 *EACCES*
    976     Search permission is denied for a directory in a file's path prefix
    977 
    978 *EBUSY*
    979     The directory is in use.
    980 
    981 *ENAMETOOLONG*
    982     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    983     effect.
    984 
    985 *ENOENT*
    986     A file or directory does not exist.
    987 
    988 *ENOTDIR*
    989     A component of the specified ``path`` was not a directory when a directory
    990     was expected.
    991 
    992 *EPERM*
    993     Operation is not permitted. Process does not have the appropriate priviledges
    994     or permissions to perform the requested operations.
    995 
    996 *EROFS*
    997     Read-only file system.
     980        const char path
     981    );
     982
     983**STATUS CODES:**
     984
     985.. list-table::
     986 :class: rtems-table
     987
     988 * - ``EACCES``
     989   - Search permission is denied for a directory in a file's path prefix
     990 * - ``EBUSY``
     991   - The directory is in use.
     992 * - ``ENAMETOOLONG``
     993   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     994     is in effect.
     995 * - ``ENOENT``
     996   - A file or directory does not exist.
     997 * - ``ENOTDIR``
     998   - A component of the specified ``path`` was not a directory when a directory
     999     was expected.
     1000 * - ``EPERM``
     1001   - Operation is not permitted. Process does not have the appropriate
     1002     priviledges or permissions to perform the requested operations.
     1003 * - ``EROFS``
     1004   - Read-only file system.
    9981005
    9991006**DESCRIPTION:**
     
    10011008The ``unlink`` function removes the link named by ``path`` and decrements the
    10021009link count of the file referenced by the link. When the link count goes to zero
    1003 and no process has the file open, the space occupied by the file is freed and the
    1004 file is no longer accessible.
    1005 
    1006 **NOTES:**
    1007 
    1008 NONE
     1010and no process has the file open, the space occupied by the file is freed and
     1011the file is no longer accessible.
     1012
     1013**NOTES:**
     1014
     1015NONE
     1016
     1017.. _rmdir:
    10091018
    10101019rmdir - Delete a directory
     
    10151024**CALLING SEQUENCE:**
    10161025
    1017 .. code:: c
     1026.. code-block:: c
    10181027
    10191028    #include <unistd.h>
    10201029    int rmdir(
    1021     const char \*pathname
    1022     );
    1023 
    1024 **STATUS CODES:**
    1025 
    1026 *EPERM*
    1027     The filesystem containing ``pathname`` does not support the removal
    1028     of directories.
    1029 
    1030 *EFAULT*
    1031     ``pathname`` points ouside your accessible address space.
    1032 
    1033 *EACCES*
    1034     Write access to the directory containing ``pathname`` was not
    1035     allowed for the process's effective uid, or one of the directories in``pathname`` did not allow search (execute) permission.
    1036 
    1037 *EPERM*
    1038     The directory containing ``pathname`` has the stickybit (S_ISVTX)
    1039     set and the process's effective uid is neither the uid of the file to
    1040     be delected nor that of the director containing it.
    1041 
    1042 *ENAMETOOLONG*
    1043     ``pathname`` was too long.
    1044 
    1045 *ENOENT*
    1046     A dirctory component in ``pathname`` does not exist or is a
    1047     dangling symbolic link.
    1048 
    1049 *ENOTDIR*
    1050     ``pathname``, or a component used as a directory in ``pathname``,
    1051     is not, in fact, a directory.
    1052 
    1053 *ENOTEMPTY*
    1054     ``pathname`` contains entries other than . and .. .
    1055 
    1056 *EBUSY*
    1057     ``pathname`` is the current working directory or root directory of
    1058     some process
    1059 
    1060 *EBUSY*
    1061     ``pathname`` is the current directory or root directory of some
    1062     process.
    1063 
    1064 *ENOMEM*
    1065     Insufficient kernel memory was available
    1066 
    1067 *EROGS*
    1068     ``pathname`` refers to a file on a read-only filesystem.
    1069 
    1070 *ELOOP*
    1071     ``pathname`` contains a reference to a circular symbolic link
     1030        const char *pathname
     1031    );
     1032
     1033**STATUS CODES:**
     1034
     1035.. list-table::
     1036 :class: rtems-table
     1037
     1038 * - ``EPERM``
     1039   - The filesystem containing ``pathname`` does not support the removal of
     1040     directories.
     1041 * - ``EFAULT``
     1042   - ``pathname`` points ouside your accessible address space.
     1043 * - ``EACCES``
     1044   - Write access to the directory containing ``pathname`` was not allowed for
     1045     the process's effective uid, or one of the directories in``pathname`` did
     1046     not allow search (execute) permission.
     1047 * - ``EPERM``
     1048   - The directory containing ``pathname`` has the stickybit (S_ISVTX) set and
     1049     the process's effective uid is neither the uid of the file to be delected
     1050     nor that of the director containing it.
     1051 * - ``ENAMETOOLONG``
     1052   - ``pathname`` was too long.
     1053 * - ``ENOENT``
     1054   - A dirctory component in ``pathname`` does not exist or is a dangling
     1055     symbolic link.
     1056 * - ``ENOTDIR``
     1057   - ``pathname``, or a component used as a directory in ``pathname``, is not,
     1058     in fact, a directory.
     1059 * - ``ENOTEMPTY``
     1060   - ``pathname`` contains entries other than . and .. .
     1061 * - ``EBUSY``
     1062   - ``pathname`` is the current working directory or root directory of some
     1063     process
     1064 * - ``EBUSY``
     1065   - ``pathname`` is the current directory or root directory of some process.
     1066 * - ``ENOMEM``
     1067   - Insufficient kernel memory was available
     1068 * - ``EROGS``
     1069   - ``pathname`` refers to a file on a read-only filesystem.
     1070 * - ``ELOOP``
     1071   - ``pathname`` contains a reference to a circular symbolic link
    10721072
    10731073**DESCRIPTION:**
     
    10781078
    10791079NONE
     1080
     1081.. _rename:
    10801082
    10811083rename - Renames a file
     
    10861088**CALLING SEQUENCE:**
    10871089
    1088 .. code:: c
     1090.. code-block:: c
    10891091
    10901092    #include <unistd.h>
    10911093    int rename(
    1092     const char \*old,
    1093     const char \*new
    1094     );
    1095 
    1096 **STATUS CODES:**
    1097 
    1098 *EACCES*
    1099     Search permission is denied for a directory in a file's path prefix.
    1100 
    1101 *EBUSY*
    1102     The directory is in use.
    1103 
    1104 *EEXIST*
    1105     The named file already exists.
    1106 
    1107 *EINVAL*
    1108     Invalid argument.
    1109 
    1110 *EISDIR*
    1111     Attempt to open a directory for writing or to rename a file to be a
    1112     directory.
    1113 
    1114 *EMLINK*
    1115     The number of links would exceed LINK_MAX.
    1116 
    1117 *ENAMETOOLONG*
    1118     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
    1119     in effect.
    1120 
    1121 *ENOENT*
    1122     A file or directory does no exist.
    1123 
    1124 *ENOSPC*
    1125     No space left on disk.
    1126 
    1127 *ENOTDIR*
    1128     A component of the specified pathname was not a directory when a
    1129     directory was expected.
    1130 
    1131 *ENOTEMPTY*
    1132     Attempt to delete or rename a non-empty directory.
    1133 
    1134 *EROFS*
    1135     Read-only file system
    1136 
    1137 *EXDEV*
    1138     Attempt to link a file to another file system.
    1139 
    1140 **DESCRIPTION:**
    1141 
    1142 The ``rename()`` function causes the file known bo ``old`` to
    1143 now be known as ``new``.
    1144 
    1145 Ordinary files may be renamed to ordinary files, and directories may be
    1146 renamed to directories; however, files cannot be converted using``rename()``. The ``new`` pathname may not contain a path prefix
    1147 of ``old``.
    1148 
    1149 **NOTES:**
    1150 
    1151 If a file already exists by the name ``new``, it is removed. The``rename()`` function is atomic. If the ``rename()`` detects an
    1152 error, no files are removed. This guarantees that the``rename("x", "x")`` does not remove ``x``.
     1094        const char *old,
     1095        const char *new
     1096    );
     1097
     1098**STATUS CODES:**
     1099
     1100.. list-table::
     1101 :class: rtems-table
     1102
     1103 * - ``EACCES``
     1104   - Search permission is denied for a directory in a file's path prefix.
     1105 * - ``EBUSY``
     1106   - The directory is in use.
     1107 * - ``EEXIST``
     1108   - The named file already exists.
     1109 * - ``EINVAL``
     1110   - Invalid argument.
     1111 * - ``EISDIR``
     1112   - Attempt to open a directory for writing or to rename a file to be a
     1113     directory.
     1114 * - ``EMLINK``
     1115   - The number of links would exceed ``LINK_MAX``.
     1116 * - ``ENAMETOOLONG``
     1117   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     1118     is in effect.
     1119 * - ``ENOENT``
     1120   - A file or directory does no exist.
     1121 * - ``ENOSPC``
     1122   - No space left on disk.
     1123 * - ``ENOTDIR``
     1124   - A component of the specified pathname was not a directory when a directory
     1125     was expected.
     1126 * - ``ENOTEMPTY``
     1127   - Attempt to delete or rename a non-empty directory.
     1128 * - ``EROFS``
     1129   - Read-only file system
     1130 * - ``EXDEV``
     1131   - Attempt to link a file to another file system.
     1132
     1133**DESCRIPTION:**
     1134
     1135The ``rename()`` function causes the file known bo ``old`` to now be known as
     1136``new``.
     1137
     1138Ordinary files may be renamed to ordinary files, and directories may be renamed
     1139to directories; however, files cannot be converted using ``rename()``. The
     1140``new`` pathname may not contain a path prefix of ``old``.
     1141
     1142**NOTES:**
     1143
     1144If a file already exists by the name ``new``, it is removed. The ``rename()``
     1145function is atomic. If the ``rename()`` detects an error, no files are
     1146removed. This guarantees that the ``rename("x", "x")`` does not remove ``x``.
    11531147
    11541148You may not rename dot or dot-dot.
    11551149
    1156 The routine is implemented in Cygnus newlib using ``link()`` and``unlink()``.
     1150The routine is implemented in Cygnus newlib using ``link()`` and ``unlink()``.
     1151
     1152.. _stat:
    11571153
    11581154stat - Gets information about a file
     
    11631159**CALLING SEQUENCE:**
    11641160
    1165 .. code:: c
     1161.. code-block:: c
    11661162
    11671163    #include <sys/types.h>
    11681164    #include <sys/stat.h>
    11691165    int stat(
    1170     const char  \*path,
    1171     struct stat \*buf
    1172     );
    1173 
    1174 **STATUS CODES:**
    1175 
    1176 *EACCES*
    1177     Search permission is denied for a directory in a file's path prefix.
    1178 
    1179 *EBADF*
    1180     Invalid file descriptor.
    1181 
    1182 *ENAMETOOLONG*
    1183     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
    1184     in effect.
    1185 
    1186 *ENOENT*
    1187     A file or directory does not exist.
    1188 
    1189 *ENOTDIR*
    1190     A component of the specified pathname was not a directory when a
    1191     directory was expected.
    1192 
    1193 **DESCRIPTION:**
    1194 
    1195 The ``path`` argument points to a pathname for a file. Read, write, or
    1196 execute permission for the file is not required, but all directories listed
    1197 in ``path`` must be searchable. The ``stat()`` function obtains
    1198 information about the named file and writes it to the area pointed to by``buf``.
    1199 
    1200 **NOTES:**
    1201 
    1202 NONE
     1166        const char  *path,
     1167        struct stat *buf
     1168    );
     1169
     1170**STATUS CODES:**
     1171
     1172.. list-table::
     1173 :class: rtems-table
     1174
     1175 * - ``EACCES``
     1176   - Search permission is denied for a directory in a file's path prefix.
     1177 * - ``EBADF``
     1178   - Invalid file descriptor.
     1179 * - ``ENAMETOOLONG``
     1180   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     1181     is in effect.
     1182 * - ``ENOENT``
     1183   - A file or directory does not exist.
     1184 * - ``ENOTDIR``
     1185   - A component of the specified pathname was not a directory when a directory
     1186     was expected.
     1187
     1188**DESCRIPTION:**
     1189
     1190The ``path`` argument points to a pathname for a file. Read, write, or execute
     1191permission for the file is not required, but all directories listed in ``path``
     1192must be searchable. The ``stat()`` function obtains information about the named
     1193file and writes it to the area pointed to by ``buf``.
     1194
     1195**NOTES:**
     1196
     1197NONE
     1198
     1199.. _fstat:
    12031200
    12041201fstat - Gets file status
     
    12091206**CALLING SEQUENCE:**
    12101207
    1211 .. code:: c
     1208.. code-block:: c
    12121209
    12131210    #include <sys/types.h>
    12141211    #include <sys/stat.h>
    12151212    int fstat(
    1216     int          fildes,
    1217     struct stat \*buf
    1218     );
    1219 
    1220 **STATUS CODES:**
    1221 
    1222 *EBADF*
    1223     Invalid file descriptor
    1224 
    1225 **DESCRIPTION:**
    1226 
    1227 The ``fstat()`` function obtains information about the file
    1228 associated with ``fildes`` and writes it to the area pointed
    1229 to by the ``buf`` argument.
    1230 
    1231 **NOTES:**
    1232 
    1233 If the filesystem object referred to by ``fildes`` is a
    1234 link, then the information returned in ``buf`` refers
    1235 to the destination of that link.  This is in contrast to``lstat()`` which does not follow the link.
     1213        int          fildes,
     1214        struct stat *buf
     1215    );
     1216
     1217**STATUS CODES:**
     1218
     1219.. list-table::
     1220 :class: rtems-table
     1221
     1222 * - ``EBADF``
     1223   - Invalid file descriptor
     1224
     1225**DESCRIPTION:**
     1226
     1227The ``fstat()`` function obtains information about the file associated with
     1228``fildes`` and writes it to the area pointed to by the ``buf`` argument.
     1229
     1230**NOTES:**
     1231
     1232If the filesystem object referred to by ``fildes`` is a link, then the
     1233information returned in ``buf`` refers to the destination of that link.  This
     1234is in contrast to ``lstat()`` which does not follow the link.
     1235
     1236.. _lstat:
    12361237
    12371238lstat - Gets file status
     
    12421243**CALLING SEQUENCE:**
    12431244
    1244 .. code:: c
     1245.. code-block:: c
    12451246
    12461247    #include <sys/types.h>
    12471248    #include <sys/stat.h>
    12481249    int lstat(
    1249     int          fildes,
    1250     struct stat \*buf
    1251     );
    1252 
    1253 **STATUS CODES:**
    1254 
    1255 *EBADF*
    1256     Invalid file descriptor
    1257 
    1258 **DESCRIPTION:**
    1259 
    1260 The ``lstat()`` function obtains information about the file
    1261 associated with ``fildes`` and writes it to the area pointed
    1262 to by the ``buf`` argument.
    1263 
    1264 **NOTES:**
    1265 
    1266 If the filesystem object referred to by ``fildes`` is a
    1267 link, then the information returned in ``buf`` refers
    1268 to the link itself.  This is in contrast to ``fstat()``
    1269 which follows the link.
    1270 
    1271 The ``lstat()`` routine is defined by BSD 4.3 and SVR4
    1272 and not included in POSIX 1003.1b-1996.
     1250        int          fildes,
     1251        struct stat *buf
     1252    );
     1253
     1254**STATUS CODES:**
     1255
     1256.. list-table::
     1257 :class: rtems-table
     1258
     1259 * - ``EBADF``
     1260   - Invalid file descriptor
     1261
     1262**DESCRIPTION:**
     1263
     1264The ``lstat()`` function obtains information about the file associated with
     1265``fildes`` and writes it to the area pointed to by the ``buf`` argument.
     1266
     1267**NOTES:**
     1268
     1269If the filesystem object referred to by ``fildes`` is a link, then the
     1270information returned in ``buf`` refers to the link itself.  This is in contrast
     1271to ``fstat()`` which follows the link.
     1272
     1273The ``lstat()`` routine is defined by BSD 4.3 and SVR4 and not included in
     1274POSIX 1003.1b-1996.
     1275
     1276.. _access:
    12731277
    12741278access - Check permissions for a file
     
    12791283**CALLING SEQUENCE:**
    12801284
    1281 .. code:: c
     1285.. code-block:: c
    12821286
    12831287    #include <unistd.h>
    12841288    int access(
    1285     const char \*pathname,
    1286     int         mode
    1287     );
    1288 
    1289 **STATUS CODES:**
    1290 
    1291 *EACCES*
    1292     The requested access would be denied, either to the file itself or
    1293     one of the directories in ``pathname``.
    1294 
    1295 *EFAULT*
    1296     ``pathname`` points outside your accessible address space.
    1297 
    1298 *EINVAL*
    1299     ``Mode`` was incorrectly specified.
    1300 
    1301 *ENAMETOOLONG*
    1302     ``pathname`` is too long.
    1303 
    1304 *ENOENT*
    1305     A directory component in ``pathname`` would have been accessible but
    1306     does not exist or was a dangling symbolic link.
    1307 
    1308 *ENOTDIR*
    1309     A component used as a directory in ``pathname`` is not, in fact,
    1310     a directory.
    1311 
    1312 *ENOMEM*
    1313     Insufficient kernel memory was available.
    1314 
    1315 **DESCRIPTION:**
    1316 
    1317 ``Access`` checks whether the process would be allowed to read, write or
    1318 test for existence of the file (or other file system object) whose name is``pathname``. If ``pathname`` is a symbolic link permissions of the
    1319 file referred by this symbolic link are tested.
    1320 
    1321 ``Mode`` is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
    1322 
    1323 **NOTES:**
    1324 
    1325 NONE
     1289        const char *pathname,
     1290        int         mode
     1291    );
     1292
     1293**STATUS CODES:**
     1294
     1295.. list-table::
     1296 :class: rtems-table
     1297
     1298 * - ``EACCES``
     1299   - The requested access would be denied, either to the file itself or one of
     1300     the directories in ``pathname``.
     1301 * - ``EFAULT``
     1302   - ``pathname`` points outside your accessible address space.
     1303 * - ``EINVAL``
     1304   - ``Mode`` was incorrectly specified.
     1305 * - ``ENAMETOOLONG``
     1306   - ``pathname`` is too long.
     1307 * - ``ENOENT``
     1308   - A directory component in ``pathname`` would have been accessible but does
     1309     not exist or was a dangling symbolic link.
     1310 * - ``ENOTDIR``
     1311   - A component used as a directory in ``pathname`` is not, in fact, a
     1312     directory.
     1313 * - ``ENOMEM``
     1314   - Insufficient kernel memory was available.
     1315
     1316**DESCRIPTION:**
     1317
     1318``Access`` checks whether the process would be allowed to read, write or test
     1319for existence of the file (or other file system object) whose name is
     1320``pathname``. If ``pathname`` is a symbolic link permissions of the file
     1321referred by this symbolic link are tested.
     1322
     1323``Mode`` is a mask consisting of one or more of ``R_OK``, ``W_OK``, ``X_OK``
     1324and ``F_OK``.
     1325
     1326**NOTES:**
     1327
     1328NONE
     1329
     1330.. _chmod:
    13261331
    13271332chmod - Changes file mode.
     
    13321337**CALLING SEQUENCE:**
    13331338
    1334 .. code:: c
     1339.. code-block:: c
    13351340
    13361341    #include <sys/types.h>
    13371342    #include <sys/stat.h>
    13381343    int chmod(
    1339     const char \*path,
    1340     mode_t      mode
    1341     );
    1342 
    1343 **STATUS CODES:**
    1344 
    1345 *EACCES*
    1346     Search permission is denied for a directory in a file's path prefix
    1347 
    1348 *ENAMETOOLONG*
    1349     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    1350     effect.
    1351 
    1352 *ENOENT*
    1353     A file or directory does not exist.
    1354 
    1355 *ENOTDIR*
    1356     A component of the specified pathname was not a directory when a directory
    1357     was expected.
    1358 
    1359 *EPERM*
    1360     Operation is not permitted. Process does not have the appropriate priviledges
    1361     or permissions to perform the requested operations.
    1362 
    1363 *EROFS*
    1364     Read-only file system.
    1365 
    1366 **DESCRIPTION:**
    1367 
    1368 Set the file permission bits, the set user ID bit, and the set group ID bit
    1369 for the file named by ``path`` to ``mode``. If the effective user ID
    1370 does not match the owner of the file and the calling process does not have
    1371 the appropriate privileges, ``chmod()`` returns -1 and sets ``errno`` to``EPERM``.
    1372 
    1373 **NOTES:**
    1374 
    1375 NONE
     1344        const char *path,
     1345        mode_t      mode
     1346    );
     1347
     1348**STATUS CODES:**
     1349
     1350.. list-table::
     1351 :class: rtems-table
     1352
     1353 * - ``EACCES``
     1354   - Search permission is denied for a directory in a file's path prefix
     1355 * - ``ENAMETOOLONG``
     1356   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     1357     is in effect.
     1358 * - ``ENOENT``
     1359   - A file or directory does not exist.
     1360 * - ``ENOTDIR``
     1361   - A component of the specified pathname was not a directory when a directory
     1362     was expected.
     1363 * - ``EPERM``
     1364   - Operation is not permitted. Process does not have the appropriate
     1365     priviledges or permissions to perform the requested operations.
     1366 * - ``EROFS``
     1367   - Read-only file system.
     1368
     1369**DESCRIPTION:**
     1370
     1371Set the file permission bits, the set user ID bit, and the set group ID bit for
     1372the file named by ``path`` to ``mode``. If the effective user ID does not match
     1373the owner of the file and the calling process does not have the appropriate
     1374privileges, ``chmod()`` returns -1 and sets ``errno`` to ``EPERM``.
     1375
     1376**NOTES:**
     1377
     1378NONE
     1379
     1380.. _fchmod:
    13761381
    13771382fchmod - Changes permissions of a file
     
    13821387**CALLING SEQUENCE:**
    13831388
    1384 .. code:: c
     1389.. code-block:: c
    13851390
    13861391    #include <sys/types.h>
    13871392    #include <sys/stat.h>
    13881393    int fchmod(
    1389     int    fildes,
    1390     mode_t mode
    1391     );
    1392 
    1393 **STATUS CODES:**
    1394 
    1395 *EACCES*
    1396     Search permission is denied for a directory in a file's path prefix.
    1397 
    1398 *EBADF*
    1399     The descriptor is not valid.
    1400 
    1401 *EFAULT*
    1402     ``path`` points outside your accessible address space.
    1403 
    1404 *EIO*
    1405     A low-level I/o error occurred while modifying the inode.
    1406 
    1407 *ELOOP*
    1408     ``path`` contains a circular reference
    1409 
    1410 *ENAMETOOLONG*
    1411     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is
    1412     in effect.
    1413 
    1414 *ENOENT*
    1415     A file or directory does no exist.
    1416 
    1417 *ENOMEM*
    1418     Insufficient kernel memory was avaliable.
    1419 
    1420 *ENOTDIR*
    1421     A component of the specified pathname was not a directory when a
    1422     directory was expected.
    1423 
    1424 *EPERM*
    1425     The effective UID does not match the owner of the file, and is not
    1426     zero
    1427 
    1428 *EROFS*
    1429     Read-only file system
    1430 
    1431 **DESCRIPTION:**
    1432 
    1433 The mode of the file given by ``path`` or referenced by``filedes`` is changed.
    1434 
    1435 **NOTES:**
    1436 
    1437 NONE
     1394        int    fildes,
     1395        mode_t mode
     1396    );
     1397
     1398**STATUS CODES:**
     1399
     1400.. list-table::
     1401 :class: rtems-table
     1402
     1403 * - ``EACCES``
     1404   - Search permission is denied for a directory in a file's path prefix.
     1405 * - ``EBADF``
     1406   - The descriptor is not valid.
     1407 * - ``EFAULT``
     1408   - ``path`` points outside your accessible address space.
     1409 * - ``EIO``
     1410   - A low-level I/o error occurred while modifying the inode.
     1411 * - ``ELOOP``
     1412   - ``path`` contains a circular reference
     1413 * - ``ENAMETOOLONG``
     1414   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     1415     is in effect.
     1416 * - ``ENOENT``
     1417   - A file or directory does no exist.
     1418 * - ``ENOMEM``
     1419   - Insufficient kernel memory was avaliable.
     1420 * - ``ENOTDIR``
     1421   - A component of the specified pathname was not a directory when a directory
     1422     was expected.
     1423 * - ``EPERM``
     1424   - The effective UID does not match the owner of the file, and is not zero
     1425 * - ``EROFS``
     1426   - Read-only file system
     1427
     1428**DESCRIPTION:**
     1429
     1430The mode of the file given by ``path`` or referenced by ``filedes`` is changed.
     1431
     1432**NOTES:**
     1433
     1434NONE
     1435
     1436.. _getdents:
    14381437
    14391438getdents - Get directory entries
     
    14441443**CALLING SEQUENCE:**
    14451444
    1446 .. code:: c
     1445.. code-block:: c
    14471446
    14481447    #include <unistd.h>
     
    14501449    #include <linux/unistd.h>
    14511450    long getdents(
    1452     int   dd_fd,
    1453     char \*dd_buf,
    1454     int   dd_len
    1455     );
    1456 
    1457 **STATUS CODES:**
    1458 
    1459 A successful call to ``getdents`` returns th the number of bytes read.
    1460 On end of directory, 0 is returned. When an error occurs, -1 is returned,
    1461 and ``errno`` is set appropriately.
    1462 
    1463 *EBADF*
    1464     Invalid file descriptor ``fd``.
    1465 
    1466 *EFAULT*
    1467     Argument points outside the calling process's address space.
    1468 
    1469 *EINVAL*
    1470     Result buffer is too small.
    1471 
    1472 *ENOENT*
    1473     No such directory.
    1474 
    1475 *ENOTDIR*
    1476     File descriptor does not refer to a directory.
    1477 
    1478 **DESCRIPTION:**
    1479 
    1480 ``getdents`` reads several ``dirent`` structures from the directory
    1481 pointed by ``fd`` into the memory area pointed to by ``dirp``. The
    1482 parameter ``count`` is the size of the memory area.
    1483 
    1484 **NOTES:**
    1485 
    1486 NONE
     1451        int   dd_fd,
     1452        char *dd_buf,
     1453        int   dd_len
     1454    );
     1455
     1456**STATUS CODES:**
     1457
     1458A successful call to ``getdents`` returns th the number of bytes read.  On end
     1459of directory, 0 is returned. When an error occurs, -1 is returned, and
     1460``errno`` is set appropriately.
     1461
     1462.. list-table::
     1463 :class: rtems-table
     1464
     1465 * - ``EBADF``
     1466   - Invalid file descriptor ``fd``.
     1467 * - ``EFAULT``
     1468   - Argument points outside the calling process's address space.
     1469 * - ``EINVAL``
     1470   - Result buffer is too small.
     1471 * - ``ENOENT``
     1472   - No such directory.
     1473 * - ``ENOTDIR``
     1474   - File descriptor does not refer to a directory.
     1475
     1476**DESCRIPTION:**
     1477
     1478``getdents`` reads several ``dirent`` structures from the directory pointed by
     1479``fd`` into the memory area pointed to by ``dirp``. The parameter ``count`` is
     1480the size of the memory area.
     1481
     1482**NOTES:**
     1483
     1484NONE
     1485
     1486.. _chown:
    14871487
    14881488chown - Changes the owner and/or group of a file.
     
    14931493**CALLING SEQUENCE:**
    14941494
    1495 .. code:: c
     1495.. code-block:: c
    14961496
    14971497    #include <sys/types.h>
    14981498    #include <unistd.h>
    14991499    int chown(
    1500     const char \*path,
    1501     uid_t       owner,
    1502     gid_t       group
    1503     );
    1504 
    1505 **STATUS CODES:**
    1506 
    1507 *EACCES*
    1508     Search permission is denied for a directory in a file's path prefix
    1509 
    1510 *EINVAL*
    1511     Invalid argument
    1512 
    1513 *ENAMETOOLONG*
    1514     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
    1515     effect.
    1516 
    1517 *ENOENT*
    1518     A file or directory does not exist.
    1519 
    1520 *ENOTDIR*
    1521     A component of the specified pathname was not a directory when a directory
    1522     was expected.
    1523 
    1524 *EPERM*
    1525     Operation is not permitted. Process does not have the appropriate priviledges
    1526     or permissions to perform the requested operations.
    1527 
    1528 *EROFS*
    1529     Read-only file system.
    1530 
    1531 **DESCRIPTION:**
    1532 
    1533 The user ID and group ID of the file named by ``path`` are set to``owner`` and ``path``, respectively.
    1534 
    1535 For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
     1500        const char *path,
     1501        uid_t       owner,
     1502        gid_t       group
     1503    );
     1504
     1505**STATUS CODES:**
     1506
     1507.. list-table::
     1508 :class: rtems-table
     1509
     1510 * - ``EACCES``
     1511   - Search permission is denied for a directory in a file's path prefix
     1512 * - ``EINVAL``
     1513   - Invalid argument
     1514 * - ``ENAMETOOLONG``
     1515   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     1516     is in effect.
     1517 * - ``ENOENT``
     1518   - A file or directory does not exist.
     1519 * - ``ENOTDIR``
     1520   - A component of the specified pathname was not a directory when a directory
     1521     was expected.
     1522 * - ``EPERM``
     1523   - Operation is not permitted. Process does not have the appropriate
     1524     priviledges or permissions to perform the requested operations.
     1525 * - ``EROFS``
     1526   - Read-only file system.
     1527
     1528**DESCRIPTION:**
     1529
     1530The user ID and group ID of the file named by ``path`` are set to ``owner`` and
     1531``path``, respectively.
     1532
     1533For regular files, the set group ID (``S_ISGID``) and set user ID (``S_ISUID``)
    15361534bits are cleared.
    15371535
    15381536Some systems consider it a security violation to allow the owner of a file to
    1539 be changed, If users are billed for disk space usage, loaning a file to
    1540 another user could result in incorrect billing. The ``chown()`` function
    1541 may be restricted to privileged users for some or all files. The group ID can
    1542 still be changed to one of the supplementary group IDs.
    1543 
    1544 **NOTES:**
    1545 
    1546 This function may be restricted for some file. The ``pathconf`` function
    1547 can be used to test the ``_PC_CHOWN_RESTRICTED`` flag.
     1537be changed, If users are billed for disk space usage, loaning a file to another
     1538user could result in incorrect billing. The ``chown()`` function may be
     1539restricted to privileged users for some or all files. The group ID can still be
     1540changed to one of the supplementary group IDs.
     1541
     1542**NOTES:**
     1543
     1544This function may be restricted for some file. The ``pathconf`` function can be
     1545used to test the ``_PC_CHOWN_RESTRICTED`` flag.
     1546
     1547.. _utime:
    15481548
    15491549utime - Change access and/or modification times of an inode
     
    15541554**CALLING SEQUENCE:**
    15551555
    1556 .. code:: c
     1556.. code-block:: c
    15571557
    15581558    #include <sys/types.h>
    15591559    int utime(
    1560     const char     \*filename,
    1561     struct utimbuf \*buf
    1562     );
    1563 
    1564 **STATUS CODES:**
    1565 
    1566 *EACCES*
    1567     Permission to write the file is denied
    1568 
    1569 *ENOENT*
    1570     ``Filename`` does not exist
    1571 
    1572 **DESCRIPTION:**
    1573 
    1574 ``Utime`` changes the access and modification times of the inode
    1575 specified by ``filename`` to the ``actime`` and ``modtime``
    1576 fields of ``buf`` respectively. If ``buf`` is NULL, then the
    1577 access and modification times of the file are set to the current time.
    1578 
    1579 **NOTES:**
    1580 
    1581 NONE
     1560        const char     *filename,
     1561        struct utimbuf *buf
     1562    );
     1563
     1564**STATUS CODES:**
     1565
     1566.. list-table::
     1567 :class: rtems-table
     1568
     1569 * - ``EACCES``
     1570   - Permission to write the file is denied
     1571 * - ``ENOENT``
     1572   - ``Filename`` does not exist
     1573
     1574**DESCRIPTION:**
     1575
     1576``Utime`` changes the access and modification times of the inode specified by
     1577``filename`` to the ``actime`` and ``modtime`` fields of ``buf``
     1578respectively. If ``buf`` is ``NULL``, then the access and modification times of the
     1579file are set to the current time.
     1580
     1581**NOTES:**
     1582
     1583NONE
     1584
     1585.. _ftruncate:
    15821586
    15831587ftruncate - truncate a file to a specified length
     
    15881592**CALLING SEQUENCE:**
    15891593
    1590 .. code:: c
     1594.. code-block:: c
    15911595
    15921596    #include <unistd.h>
    15931597    int ftrunctate(
    1594     int    fd,
    1595     size_t length
    1596     );
    1597 
    1598 **STATUS CODES:**
    1599 
    1600 *ENOTDIR*
    1601     A component of the path prefix is not a directory.
    1602 
    1603 *EINVAL*
    1604     The pathname contains a character with the high-order bit set.
    1605 
    1606 *ENAMETOOLONG*
    1607     A component of a pathname exceeded 255 characters, or an entire
    1608     path name exceeded 1023 characters.
    1609 
    1610 *ENOENT*
    1611     The named file does not exist.
    1612 
    1613 *EACCES*
    1614     The named file is not writable by the user.
    1615 
    1616 *EACCES*
    1617     Search permission is denied for a component of the path prefix.
    1618 
    1619 *ELOOP*
    1620     Too many symbolic links were encountered in translating the
    1621     pathname
    1622 
    1623 *EISDIR*
    1624     The named file is a directory.
    1625 
    1626 *EROFS*
    1627     The named file resides on a read-only file system
    1628 
    1629 *ETXTBSY*
    1630     The file is a pure procedure (shared text) file that is being
    1631     executed
    1632 
    1633 *EIO*
    1634     An I/O error occurred updating the inode.
    1635 
    1636 *EFAULT*
    1637     ``Path`` points outside the process's allocated address space.
    1638 
    1639 *EBADF*
    1640     The ``fd`` is not a valid descriptor.
    1641 
    1642 **DESCRIPTION:**
    1643 
    1644 ``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
    1645 file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
    1646 
    1647 **NOTES:**
    1648 
    1649 NONE
     1598        int    fd,
     1599        size_t length
     1600    );
     1601
     1602**STATUS CODES:**
     1603
     1604.. list-table::
     1605 :class: rtems-table
     1606
     1607 * - ``ENOTDIR``
     1608   - A component of the path prefix is not a directory.
     1609 * - ``EINVAL``
     1610   - The pathname contains a character with the high-order bit set.
     1611 * - ``ENAMETOOLONG``
     1612   - The length of the specified pathname exceeds ``PATH_MAX`` bytes, or the length
     1613     of a component of the pathname exceeds ``NAME_MAX`` bytes.
     1614 * - ``ENOENT``
     1615   - The named file does not exist.
     1616 * - ``EACCES``
     1617   - The named file is not writable by the user.
     1618 * - ``EACCES``
     1619   - Search permission is denied for a component of the path prefix.
     1620 * - ``ELOOP``
     1621   - Too many symbolic links were encountered in translating the pathname
     1622 * - ``EISDIR``
     1623   - The named file is a directory.
     1624 * - ``EROFS``
     1625   - The named file resides on a read-only file system
     1626 * - ``ETXTBSY``
     1627   - The file is a pure procedure (shared text) file that is being executed
     1628 * - ``EIO``
     1629   - An I/O error occurred updating the inode.
     1630 * - ``EFAULT``
     1631   - ``Path`` points outside the process's allocated address space.
     1632 * - ``EBADF``
     1633   - The ``fd`` is not a valid descriptor.
     1634
     1635**DESCRIPTION:**
     1636
     1637``truncate()`` causes the file named by ``path`` or referenced by ``fd`` to be
     1638truncated to at most ``length`` bytes in size. If the file previously was
     1639larger than this size, the extra data is lost. With ``ftruncate()``, the file
     1640must be open for writing.
     1641
     1642**NOTES:**
     1643
     1644NONE
     1645
     1646.. _truncate:
    16501647
    16511648truncate - truncate a file to a specified length
     
    16561653**CALLING SEQUENCE:**
    16571654
    1658 .. code:: c
     1655.. code-block:: c
    16591656
    16601657    #include <unistd.h>
    16611658    int trunctate(
    1662     const char \*path,
    1663     size_t      length
    1664     );
    1665 
    1666 **STATUS CODES:**
    1667 
    1668 *ENOTDIR*
    1669     A component of the path prefix is not a directory.
    1670 
    1671 *EINVAL*
    1672     The pathname contains a character with the high-order bit set.
    1673 
    1674 *ENAMETOOLONG*
    1675     A component of a pathname exceeded 255 characters, or an entire
    1676     path name exceeded 1023 characters.
    1677 
    1678 *ENOENT*
    1679     The named file does not exist.
    1680 
    1681 *EACCES*
    1682     The named file is not writable by the user.
    1683 
    1684 *EACCES*
    1685     Search permission is denied for a component of the path prefix.
    1686 
    1687 *ELOOP*
    1688     Too many symbolic links were encountered in translating the
    1689     pathname
    1690 
    1691 *EISDIR*
    1692     The named file is a directory.
    1693 
    1694 *EROFS*
    1695     The named file resides on a read-only file system
    1696 
    1697 *ETXTBSY*
    1698     The file is a pure procedure (shared text) file that is being
    1699     executed
    1700 
    1701 *EIO*
    1702     An I/O error occurred updating the inode.
    1703 
    1704 *EFAULT*
    1705     ``Path`` points outside the process's allocated address space.
    1706 
    1707 *EBADF*
    1708     The ``fd`` is not a valid descriptor.
    1709 
    1710 **DESCRIPTION:**
    1711 
    1712 ``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the
    1713 file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing.
    1714 
    1715 **NOTES:**
    1716 
    1717 NONE
     1659        const char *path,
     1660        size_t      length
     1661    );
     1662
     1663**STATUS CODES:**
     1664
     1665.. list-table::
     1666 :class: rtems-table
     1667
     1668 * - ``ENOTDIR``
     1669   - A component of the path prefix is not a directory.
     1670 * - ``EINVAL``
     1671   - The pathname contains a character with the high-order bit set.
     1672 * - ``ENAMETOOLONG``
     1673   - The length of the specified pathname exceeds ``PATH_MAX`` bytes, or the length
     1674     of a component of the pathname exceeds ``NAME_MAX`` bytes.
     1675 * - ``ENOENT``
     1676   - The named file does not exist.
     1677 * - ``EACCES``
     1678   - The named file is not writable by the user.
     1679 * - ``EACCES``
     1680   - Search permission is denied for a component of the path prefix.
     1681 * - ``ELOOP``
     1682   - Too many symbolic links were encountered in translating the pathname
     1683 * - ``EISDIR``
     1684   - The named file is a directory.
     1685 * - ``EROFS``
     1686   - The named file resides on a read-only file system
     1687 * - ``ETXTBSY``
     1688   - The file is a pure procedure (shared text) file that is being executed
     1689 * - ``EIO``
     1690   - An I/O error occurred updating the inode.
     1691 * - ``EFAULT``
     1692   - ``Path`` points outside the process's allocated address space.
     1693 * - ``EBADF``
     1694   - The ``fd`` is not a valid descriptor.
     1695
     1696**DESCRIPTION:**
     1697
     1698``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be
     1699truncated to at most ``length`` bytes in size. If the file previously was
     1700larger than this size, the extra data is lost. With ``ftruncate()``, the file
     1701must be open for writing.
     1702
     1703**NOTES:**
     1704
     1705NONE
     1706
     1707.. _pathconf:
    17181708
    17191709pathconf - Gets configuration values for files
     
    17241714**CALLING SEQUENCE:**
    17251715
    1726 .. code:: c
     1716.. code-block:: c
    17271717
    17281718    #include <unistd.h>
    17291719    int pathconf(
    1730     const char \*path,
    1731     int         name
    1732     );
    1733 
    1734 **STATUS CODES:**
    1735 
    1736 *EINVAL*
    1737     Invalid argument
    1738 
    1739 *EACCES*
    1740     Permission to write the file is denied
    1741 
    1742 *ENAMETOOLONG*
    1743     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
    1744     is in effect.
    1745 
    1746 *ENOENT*
    1747     A file or directory does not exist
    1748 
    1749 *ENOTDIR*
    1750     A component of the specified ``path`` was not a directory whan a
    1751     directory was expected.
    1752 
    1753 **DESCRIPTION:**
    1754 
    1755 ``pathconf()`` gets a value for the configuration option ``name``
    1756 for the open file descriptor ``filedes``.
     1720        const char *path,
     1721        int         name
     1722    );
     1723
     1724**STATUS CODES:**
     1725
     1726.. list-table::
     1727 :class: rtems-table
     1728
     1729 * - ``EINVAL``
     1730   - Invalid argument
     1731 * - ``EACCES``
     1732   - Permission to write the file is denied
     1733 * - ``ENAMETOOLONG``
     1734   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     1735     is in effect.
     1736 * - ``ENOENT``
     1737   - A file or directory does not exist
     1738 * - ``ENOTDIR``
     1739   - A component of the specified ``path`` was not a directory whan a directory
     1740     was expected.
     1741
     1742**DESCRIPTION:**
     1743
     1744``pathconf()`` gets a value for the configuration option ``name`` for the open
     1745file descriptor ``filedes``.
    17571746
    17581747The possible values for ``name`` are:
    17591748
    1760 *_PC_LINK_MAX*
    1761     returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
    1762     directory. The corresponding macro is ``_POSIX_LINK_MAX``.
    1763 
    1764 *_PC_MAX_CANON*
    1765     returns the maximum length of a formatted input line, where ``filedes``
    1766     or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
    1767 
    1768 *_PC_MAX_INPUT*
    1769     returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
    1770 
    1771 *_PC_NAME_MAX*
    1772     returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
    1773     is ``_POSIX_NAME_MAX``.
    1774 
    1775 *_PC_PATH_MAX*
    1776     returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
    1777     is ``_POSIX_PATH_MAX``.
    1778 
    1779 *_PC_PIPE_BUF*
    1780     returns the size of the pipe buffer, where ``filedes`` must refer to a
    1781     pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
    1782     is ``_POSIX_PIPE_BUF``.
    1783 
    1784 *_PC_CHOWN_RESTRICTED*
    1785     returns nonzero if the chown(2) call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
    1786     files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
    1787 
    1788 **NOTES:**
    1789 
    1790 Files with name lengths longer than the value returned for ``name`` equal``_PC_NAME_MAX`` may exist in the given directory.
     1749.. list-table::
     1750 :class: rtems-table
     1751
     1752 * - ``_PC_LINK_MAX``
     1753   - Returns the maximum number of links to the file. If ``filedes`` or``path``
     1754     refer to a directory, then the value applies to the whole directory. The
     1755     corresponding macro is ``_POSIX_LINK_MAX``.
     1756 * - ``_PC_MAX_CANON``
     1757   - Returns the maximum length of a formatted input line, where ``filedes`` or
     1758     ``path`` must refer to a terminal. The corresponding macro is
     1759     ``_POSIX_MAX_CANON``.
     1760 * - ``_PC_MAX_INPUT``
     1761   - Returns the maximum length of an input line, where ``filedes`` or ``path``
     1762     must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
     1763 * - ``_PC_NAME_MAX``
     1764   - Returns the maximum length of a filename in the directory ``path`` or
     1765     ``filedes``. The process is allowed to create. The corresponding macro is
     1766     ``_POSIX_NAME_MAX``.
     1767 * - ``_PC_PATH_MAX``
     1768   - returns the maximum length of a relative pathname when ``path``
     1769     or``filedes`` is the current working directory. The corresponding macro is
     1770     ``_POSIX_PATH_MAX``.
     1771 * - ``_PC_PIPE_BUF``
     1772   - returns the size of the pipe buffer, where ``filedes`` must refer to a
     1773     pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro is
     1774     ``_POSIX_PIPE_BUF``.
     1775 * - ``_PC_CHOWN_RESTRICTED``
     1776   - Returns nonzero if the ``chown(2)`` call may not be used on this
     1777     file. If``filedes`` or ``path`` refer to a directory, then this applies to
     1778     all files in that directory. The corresponding macro is
     1779     ``_POSIX_CHOWN_RESTRICTED``.
     1780
     1781**NOTES:**
     1782
     1783Files with name lengths longer than the value returned for ``name`` equal
     1784``_PC_NAME_MAX`` may exist in the given directory.
     1785
     1786.. _fpathconf:
    17911787
    17921788fpathconf - Gets configuration values for files
     
    17971793**CALLING SEQUENCE:**
    17981794
    1799 .. code:: c
     1795.. code-block:: c
    18001796
    18011797    #include <unistd.h>
    18021798    int fpathconf(
    1803     int filedes,
    1804     int name
    1805     );
    1806 
    1807 **STATUS CODES:**
    1808 
    1809 *EINVAL*
    1810     Invalid argument
    1811 
    1812 *EACCES*
    1813     Permission to write the file is denied
    1814 
    1815 *ENAMETOOLONG*
    1816     Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC
    1817     is in effect.
    1818 
    1819 *ENOENT*
    1820     A file or directory does not exist
    1821 
    1822 *ENOTDIR*
    1823     A component of the specified ``path`` was not a directory whan a
    1824     directory was expected.
    1825 
    1826 **DESCRIPTION:**
    1827 
    1828 ``pathconf()`` gets a value for the configuration option ``name``
    1829 for the open file descriptor ``filedes``.
     1799        int filedes,
     1800        int name
     1801    );
     1802
     1803**STATUS CODES:**
     1804
     1805.. list-table::
     1806 :class: rtems-table
     1807
     1808 * - ``EINVAL``
     1809   - Invalid argument
     1810 * - ``EACCES``
     1811   - Permission to write the file is denied
     1812 * - ``ENAMETOOLONG``
     1813   - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC``
     1814     is in effect.
     1815 * - ``ENOENT``
     1816   - A file or directory does not exist
     1817 * - ``ENOTDIR``
     1818   - A component of the specified ``path`` was not a directory whan a directory
     1819     was expected.
     1820
     1821**DESCRIPTION:**
     1822
     1823``pathconf()`` gets a value for the configuration option ``name`` for the open
     1824file descriptor ``filedes``.
    18301825
    18311826The possible values for name are:
    18321827
    1833 *_PC_LINK_MAX*
    1834     returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole
    1835     directory. The corresponding macro is _POSIX_LINK_MAX.
    1836 
    1837 *_PC_MAX_CANON*
    1838     returns the maximum length of a formatted input line, where ``filedes``
    1839     or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``.
    1840 
    1841 *_PC_MAX_INPUT*
    1842     returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``.
    1843 
    1844 *_PC_NAME_MAX*
    1845     returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro
    1846     is ``_POSIX_NAME_MAX``.
    1847 
    1848 *_PC_PATH_MAX*
    1849     returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro
    1850     is ``_POSIX_PATH_MAX``.
    1851 
    1852 *_PC_PIPE_BUF*
    1853     returns the size of the pipe buffer, where ``filedes`` must refer to a
    1854     pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro
    1855     is ``_POSIX_PIPE_BUF``.
    1856 
    1857 *_PC_CHOWN_RESTRICTED*
    1858     returns nonzero if the ``chown()`` call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all
    1859     files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``.
    1860 
    1861 **NOTES:**
    1862 
    1863 NONE
     1828.. list-table::
     1829 :class: rtems-table
     1830
     1831 * - ``_PC_LINK_MAX``
     1832   - Returns the maximum number of links to the file. If ``filedes`` or
     1833     ``path`` refer to a directory, then the value applies to the whole
     1834     directory. The corresponding macro is ``_POSIX_LINK_MAX``.
     1835 * - ``_PC_MAX_CANON``
     1836   - returns the maximum length of a formatted input line, where ``filedes`` or
     1837     ``path`` must refer to a terminal. The corresponding macro is
     1838     ``_POSIX_MAX_CANON``.
     1839 * - ``_PC_MAX_INPUT``
     1840   - Returns the maximum length of an input line, where ``filedes`` or ``path``
     1841     must refer to a terminal. The corresponding macro is ``_POSIX_MAX_INPUT``.
     1842 * - ``_PC_NAME_MAX``
     1843   - Returns the maximum length of a filename in the directory ``path`` or
     1844     ``filedes``. The process is allowed to create. The corresponding macro is
     1845     ``_POSIX_NAME_MAX``.
     1846 * - ``_PC_PATH_MAX``
     1847   - Returns the maximum length of a relative pathname when ``path`` or
     1848     ``filedes`` is the current working directory. The corresponding macro is
     1849     ``_POSIX_PATH_MAX``.
     1850 * - ``_PC_PIPE_BUF``
     1851   - Returns the size of the pipe buffer, where ``filedes`` must refer to a
     1852     pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro is
     1853     ``_POSIX_PIPE_BUF``.
     1854 * - ``_PC_CHOWN_RESTRICTED``
     1855   - Returns nonzero if the ``chown()`` call may not be used on this file. If
     1856     ``filedes`` or ``path`` refer to a directory, then this applies to all
     1857     files in that directory. The corresponding macro is
     1858     ``_POSIX_CHOWN_RESTRICTED``.
     1859
     1860**NOTES:**
     1861
     1862NONE
     1863
     1864.. _mknod:
    18641865
    18651866mknod - create a directory
     
    18701871**CALLING SEQUENCE:**
    18711872
    1872 .. code:: c
     1873.. code-block:: c
    18731874
    18741875    #include <unistd.h>
     
    18771878    #include <sys/stat.h>
    18781879    long mknod(
    1879     const char \*pathname,
    1880     mode_t      mode,
    1881     dev_t       dev
     1880        const char *pathname,
     1881        mode_t      mode,
     1882        dev_t       dev
    18821883    );
    18831884
     
    18871888errno is set appropriately).
    18881889
    1889 *ENAMETOOLONG*
    1890     ``pathname`` was too long.
    1891 
    1892 *ENOENT*
    1893     A directory component in ``pathname`` does not exist or is a dangling symbolic
    1894     link.
    1895 
    1896 *ENOTDIR*
    1897     A component used in the directory ``pathname`` is not, in fact, a directory.
    1898 
    1899 *ENOMEM*
    1900     Insufficient kernel memory was available
    1901 
    1902 *EROFS*
    1903     ``pathname`` refers to a file on a read-only filesystem.
    1904 
    1905 *ELOOP*
    1906     ``pathname`` contains a reference to a circular symbolic link, ie a symbolic
    1907     link whose expansion contains a reference to itself.
    1908 
    1909 *ENOSPC*
    1910     The device containing ``pathname`` has no room for the new node.
     1890.. list-table::
     1891 :class: rtems-table
     1892
     1893 * - ``ENAMETOOLONG``
     1894   - ``pathname`` was too long.
     1895 * - ``ENOENT``
     1896   - A directory component in ``pathname`` does not exist or is a dangling
     1897     symbolic link.
     1898 * - ``ENOTDIR``
     1899   - A component used in the directory ``pathname`` is not, in fact, a
     1900     directory.
     1901 * - ``ENOMEM``
     1902   - Insufficient kernel memory was available
     1903 * - ``EROFS``
     1904   - ``pathname`` refers to a file on a read-only filesystem.
     1905 * - ``ELOOP``
     1906   - ``pathname`` contains a reference to a circular symbolic link, ie a
     1907     symbolic link whose expansion contains a reference to itself.
     1908 * - ``ENOSPC``
     1909   - The device containing ``pathname`` has no room for the new node.
    19111910
    19121911**DESCRIPTION:**
     
    19231922permissions of the created node are ``(mode & ~umask)``.
    19241923
    1925 The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and``S_IFIFO`` to specify a normal file (which will be created empty), character
    1926 special file, block special file or FIFO (named pipe), respectively, or zero, which
    1927 will create a normal file.
     1924The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and
     1925``S_IFIFO`` to specify a normal file (which will be created empty), character
     1926special file, block special file or FIFO (named pipe), respectively, or zero,
     1927which will create a normal file.
    19281928
    19291929If the file type is ``S_IFCHR`` or ``S_IFBLK`` then ``dev`` specifies the major
    1930 and minor numbers of the newly created device special file; otherwise it is ignored.
    1931 
    1932 The newly created node will be owned by the effective uid of the process. If the
    1933 directory containing the node has the set group id bit set, or if the filesystem
    1934 is mounted with BSD group semantics, the new node will inherit the group ownership
    1935 from its parent directory; otherwise it will be owned by the effective gid of the
    1936 process.
    1937 
    1938 **NOTES:**
    1939 
    1940 NONE
    1941 
    1942 .. COMMENT: COPYRIGHT (c) 1988-2002.
    1943 
    1944 .. COMMENT: On-Line Applications Research Corporation (OAR).
    1945 
    1946 .. COMMENT: All rights reserved.
    1947 
     1930and minor numbers of the newly created device special file; otherwise it is
     1931ignored.
     1932
     1933The newly created node will be owned by the effective uid of the process. If
     1934the directory containing the node has the set group id bit set, or if the
     1935filesystem is mounted with BSD group semantics, the new node will inherit the
     1936group ownership from its parent directory; otherwise it will be owned by the
     1937effective gid of the process.
     1938
     1939**NOTES:**
     1940
     1941NONE
  • posix_users/index.rst

    r238bf99 rfa70fd2  
    33============================
    44
    5 COPYRIGHT (c) 1988 - 2015.
     5RTEMS POSIX API User's Guide
     6----------------------------
    67
    7 On-Line Applications Research Corporation (OAR).
     8 | COPYRIGHT (c) 1988 - 2015.
     9 | On-Line Applications Research Corporation (OAR).
    810
    9 The authors have used their best efforts in preparing
    10 this material.  These efforts include the development, research,
    11 and testing of the theories and programs to determine their
    12 effectiveness.  No warranty of any kind, expressed or implied,
    13 with regard to the software or the material contained in this
    14 document is provided.  No liability arising out of the
    15 application or use of any product described in this document is
    16 assumed.  The authors reserve the right to revise this material
    17 and to make changes from time to time in the content hereof
    18 without obligation to notify anyone of such revision or changes.
     11The authors have used their best efforts in preparing this material.  These
     12efforts include the development, research, and testing of the theories and
     13programs to determine their effectiveness.  No warranty of any kind, expressed
     14or implied, with regard to the software or the material contained in this
     15document is provided.  No liability arising out of the application or use of
     16any product described in this document is assumed.  The authors reserve the
     17right to revise this material and to make changes from time to time in the
     18content hereof without obligation to notify anyone of such revision or changes.
    1919
    20 The RTEMS Project is hosted at http://www.rtems.org.  Any
    21 inquiries concerning RTEMS, its related support components, or its
    22 documentation should be directed to the Community Project hosted athttp://www.rtems.org.
     20The RTEMS Project is hosted at http://www.rtems.org/.  Any inquiries concerning
     21RTEMS, its related support components, or its documentation should be directed
     22to the Community Project hosted at http://www.rtems.org/.
    2323
    24 Any inquiries for commercial services including training, support, custom
    25 development, application development assistance should be directed tohttp://www.rtems.com.
     24.. topic:: RTEMS Online Resources
    2625
    27 .. COMMENT: This prevents a black box from being printed on "overflow" lines.
    28 
    29 .. COMMENT: The alternative is to rework a sentence to avoid this problem.
    30 
    31 
    32 Table of Contents
    33 -----------------
    34 
    35 .. toctree::
    36 
    37         preface
    38 
     26  ================  =============================
     27  Home              https://www.rtems.org/
     28  Developers        https://devel.rtems.org/
     29  Documentation     https://docs.rtems.org/
     30  Bug Reporting     https://devel.rtems.org/query
     31  Mailing Lists     https://lists.rtems.org/
     32  Git Repositories  https://git.rtems.org/
     33  ================  =============================
    3934
    4035.. toctree::
     
    4237        :numbered:
    4338
     39        preface
    4440        process_creation_and_execution
    4541        signal
     
    6662        command
    6763
    68 
    6964*       :ref:`genindex`
    7065*       :ref:`search`
  • posix_users/input_and_output.rst

    r238bf99 rfa70fd2  
     1.. COMMENT: COPYRIGHT (c) 1988-2002.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Input and Output Primitives Manager
    26###################################
     
    913The directives provided by the input and output primitives manager are:
    1014
    11 - ``pipe`` - Create an Inter-Process Channel
    12 
    13 - ``dup`` - Duplicates an open file descriptor
    14 
    15 - ``dup2`` - Duplicates an open file descriptor
    16 
    17 - ``close`` - Closes a file
    18 
    19 - ``read`` - Reads from a file
    20 
    21 - ``write`` - Writes to a file
    22 
    23 - ``fcntl`` - Manipulates an open file descriptor
    24 
    25 - ``lseek`` - Reposition read/write file offset
    26 
    27 - ``fsync`` - Synchronize file complete in-core state with that on disk
    28 
    29 - ``fdatasync`` - Synchronize file in-core data with that on disk
    30 
    31 - ``sync`` - Schedule file system updates
    32 
    33 - ``mount`` - Mount a file system
    34 
    35 - ``unmount`` - Unmount file systems
    36 
    37 - ``readv`` - Vectored read from a file
    38 
    39 - ``writev`` - Vectored write to a file
    40 
    41 - ``aio_read`` - Asynchronous Read
    42 
    43 - ``aio_write`` - Asynchronous Write
    44 
    45 - ``lio_listio`` - List Directed I/O
    46 
    47 - ``aio_error`` - Retrieve Error Status of Asynchronous I/O Operation
    48 
    49 - ``aio_return`` - Retrieve Return Status Asynchronous I/O Operation
    50 
    51 - ``aio_cancel`` - Cancel Asynchronous I/O Request
    52 
    53 - ``aio_suspend`` - Wait for Asynchronous I/O Request
    54 
    55 - ``aio_fsync`` - Asynchronous File Synchronization
     15- pipe_ - Create an Inter-Process Channel
     16
     17- dup_ - Duplicates an open file descriptor
     18
     19- dup2_ - Duplicates an open file descriptor
     20
     21- close_ - Closes a file
     22
     23- read_ - Reads from a file
     24
     25- write_ - Writes to a file
     26
     27- fcntl_ - Manipulates an open file descriptor
     28
     29- lseek_ - Reposition read/write file offset
     30
     31- fsync_ - Synchronize file complete in-core state with that on disk
     32
     33- fdatasync_ - Synchronize file in-core data with that on disk
     34
     35- sync_ - Schedule file system updates
     36
     37- mount_ - Mount a file system
     38
     39- unmount_ - Unmount file systems
     40
     41- readv_ - Vectored read from a file
     42
     43- writev_ - Vectored write to a file
     44
     45- aio_read_ - Asynchronous Read
     46
     47- aio_write_ - Asynchronous Write
     48
     49- lio_listio_ - List Directed I/O
     50
     51- aio_error_ - Retrieve Error Status of Asynchronous I/O Operation
     52
     53- aio_return_ - Retrieve Return Status Asynchronous I/O Operation
     54
     55- aio_cancel_ - Cancel Asynchronous I/O Request
     56
     57- aio_suspend_ - Wait for Asynchronous I/O Request
     58
     59- aio_fsync_ - Asynchronous File Synchronization
    5660
    5761Background
     
    6872==========
    6973
    70 This section details the input and output primitives manager's directives.
    71 A subsection is dedicated to each of this manager's directives
    72 and describes the calling sequence, related constants, usage,
    73 and status codes.
     74This section details the input and output primitives manager's directives.  A
     75subsection is dedicated to each of this manager's directives and describes the
     76calling sequence, related constants, usage, and status codes.
     77
     78.. _pipe:
    7479
    7580pipe - Create an Inter-Process Channel
     
    8085**CALLING SEQUENCE:**
    8186
    82 .. code:: c
     87.. code-block:: c
    8388
    8489    int pipe(
     
    8792**STATUS CODES:**
    8893
    89 *E*
    90     The
     94.. list-table::
     95 :class: rtems-table
     96
     97 * - ``E``
     98   - The
    9199
    92100**DESCRIPTION:**
     
    96104This routine is not currently supported by RTEMS but could be
    97105in a future version.
     106
     107.. _dup:
    98108
    99109dup - Duplicates an open file descriptor
     
    104114**CALLING SEQUENCE:**
    105115
    106 .. code:: c
     116.. code-block:: c
    107117
    108118    #include <unistd.h>
    109119    int dup(
    110     int fildes
    111     );
    112 
    113 **STATUS CODES:**
    114 
    115 *EBADF*
    116     Invalid file descriptor.
    117 
    118 *EINTR*
    119     Function was interrupted by a signal.
    120 
    121 *EMFILE*
    122     The process already has the maximum number of file descriptors open
    123     and tried to open a new one.
     120        int fildes
     121    );
     122
     123**STATUS CODES:**
     124
     125.. list-table::
     126 :class: rtems-table
     127
     128 * - ``EBADF``
     129   - Invalid file descriptor.
     130 * - ``EINTR``
     131   - Function was interrupted by a signal.
     132 * - ``EMFILE``
     133   - The process already has the maximum number of file descriptors open and
     134     tried to open a new one.
    124135
    125136**DESCRIPTION:**
    126137
    127138The ``dup`` function returns the lowest numbered available file
    128 descriptor. This new desciptor refers to the same open file as the
    129 original descriptor and shares any locks.
    130 
    131 **NOTES:**
    132 
    133 NONE
     139descriptor. This new desciptor refers to the same open file as the original
     140descriptor and shares any locks.
     141
     142**NOTES:**
     143
     144NONE
     145
     146.. _dup2:
    134147
    135148dup2 - Duplicates an open file descriptor
     
    140153**CALLING SEQUENCE:**
    141154
    142 .. code:: c
     155.. code-block:: c
    143156
    144157    #include <unistd.h>
    145158    int dup2(
    146     int fildes,
    147     int fildes2
    148     );
    149 
    150 **STATUS CODES:**
    151 
    152 *EBADF*
    153     Invalid file descriptor.
    154 
    155 *EINTR*
    156     Function was interrupted by a signal.
    157 
    158 *EMFILE*
    159     The process already has the maximum number of file descriptors open
    160     and tried to open a new one.
     159        int fildes,
     160        int fildes2
     161    );
     162
     163**STATUS CODES:**
     164
     165.. list-table::
     166 :class: rtems-table
     167
     168 * - ``EBADF``
     169   - Invalid file descriptor.
     170 * - ``EINTR``
     171   - Function was interrupted by a signal.
     172 * - ``EMFILE``
     173   - The process already has the maximum number of file descriptors open and
     174     tried to open a new one.
    161175
    162176**DESCRIPTION:**
     
    165179
    166180The old and new descriptors may be used interchangeably. They share locks, file
    167 position pointers and flags; for example, if the file position is modified by using``lseek`` on one of the descriptors, the position is also changed for the other.
    168 
    169 **NOTES:**
    170 
    171 NONE
     181position pointers and flags; for example, if the file position is modified by
     182using ``lseek`` on one of the descriptors, the position is also changed for the
     183other.
     184
     185**NOTES:**
     186
     187NONE
     188
     189.. _close:
    172190
    173191close - Closes a file
     
    178196**CALLING SEQUENCE:**
    179197
    180 .. code:: c
     198.. code-block:: c
    181199
    182200    #include <unistd.h>
    183201    int close(
    184     int fildes
    185     );
    186 
    187 **STATUS CODES:**
    188 
    189 *EBADF*
    190     Invalid file descriptor
    191 
    192 *EINTR*
    193     Function was interrupted by a signal.
    194 
    195 **DESCRIPTION:**
    196 
    197 The ``close()`` function deallocates the file descriptor named by``fildes`` and makes it available for reuse. All outstanding
    198 record locks owned by this process for the file are unlocked.
    199 
    200 **NOTES:**
    201 
    202 A signal can interrupt the ``close()`` function. In that case,``close()`` returns -1 with ``errno`` set to EINTR. The file
    203 may or may not be closed.
     202        int fildes
     203    );
     204
     205**STATUS CODES:**
     206
     207.. list-table::
     208 :class: rtems-table
     209
     210 * - ``EBADF``
     211   - Invalid file descriptor
     212 * - ``EINTR``
     213   - Function was interrupted by a signal.
     214
     215**DESCRIPTION:**
     216
     217The ``close()`` function deallocates the file descriptor named by ``fildes``
     218and makes it available for reuse. All outstanding record locks owned by this
     219process for the file are unlocked.
     220
     221**NOTES:**
     222
     223A signal can interrupt the ``close()`` function. In that case, ``close()``
     224returns -1 with ``errno`` set to EINTR. The file may or may not be closed.
     225
     226.. _read:
    204227
    205228read - Reads from a file
     
    210233**CALLING SEQUENCE:**
    211234
    212 .. code:: c
     235.. code-block:: c
    213236
    214237    #include <unistd.h>
    215238    int read(
    216     int           fildes,
    217     void         \*buf,
    218     unsigned int  nbyte
    219     );
    220 
    221 **STATUS CODES:**
    222 
    223 On error, this routine returns -1 and sets ``errno`` to one of
    224 the following:
    225 
    226 *EAGAIN*
    227     The O_NONBLOCK flag is set for a file descriptor and the process
    228     would be delayed in the I/O operation.
    229 
    230 *EBADF*
    231     Invalid file descriptor
    232 
    233 *EINTR*
    234     Function was interrupted by a signal.
    235 
    236 *EIO*
    237     Input or output error
    238 
    239 *EINVAL*
    240     Bad buffer pointer
    241 
    242 **DESCRIPTION:**
    243 
    244 The ``read()`` function reads ``nbyte`` bytes from the file
    245 associated with ``fildes`` into the buffer pointed to by ``buf``.
    246 
    247 The ``read()`` function returns the number of bytes actually read
    248 and placed in the buffer. This will be less than ``nbyte`` if:
     239        int           fildes,
     240        void         *buf,
     241        unsigned int  nbyte
     242    );
     243
     244**STATUS CODES:**
     245
     246On error, this routine returns -1 and sets ``errno`` to one of the following:
     247
     248.. list-table::
     249 :class: rtems-table
     250
     251 * - ``EAGAIN``
     252   - The O_NONBLOCK flag is set for a file descriptor and the process would be
     253     delayed in the I/O operation.
     254 * - ``EBADF``
     255   - Invalid file descriptor
     256 * - ``EINTR``
     257   - Function was interrupted by a signal.
     258 * - ``EIO``
     259   - Input or output error
     260 * - ``EINVAL``
     261   - Bad buffer pointer
     262
     263**DESCRIPTION:**
     264
     265The ``read()`` function reads ``nbyte`` bytes from the file associated with
     266``fildes`` into the buffer pointed to by ``buf``.
     267
     268The ``read()`` function returns the number of bytes actually read and placed in
     269the buffer. This will be less than ``nbyte`` if:
    249270
    250271- The number of bytes left in the file is less than ``nbyte``.
     
    257278When attempting to read from any empty pipe or FIFO:
    258279
    259 - If no process has the pipe open for writing, zero is returned to
    260   indicate end-of-file.
     280- If no process has the pipe open for writing, zero is returned to indicate
     281  end-of-file.
    261282
    262283- If some process has the pipe open for writing and O_NONBLOCK is set,
    263284  -1 is returned and ``errno`` is set to EAGAIN.
    264285
    265 - If some process has the pipe open for writing and O_NONBLOCK is clear,``read()`` waits for some data to be written or the pipe to be closed.
    266 
    267 When attempting to read from a file other than a pipe or FIFO and no data
    268 is available.
     286- If some process has the pipe open for writing and O_NONBLOCK is clear,
     287  ``read()`` waits for some data to be written or the pipe to be closed.
     288
     289When attempting to read from a file other than a pipe or FIFO and no data is
     290available.
    269291
    270292- If O_NONBLOCK is set, -1 is returned and ``errno`` is set to EAGAIN.
    271293
    272 - If O_NONBLOCK is clear, ``read()`` waits for some data to become
    273   available.
     294- If O_NONBLOCK is clear, ``read()`` waits for some data to become available.
    274295
    275296- The O_NONBLOCK flag is ignored if data is available.
     
    278299
    279300NONE
     301
     302.. _write:
    280303
    281304write - Writes to a file
     
    286309**CALLING SEQUENCE:**
    287310
    288 .. code:: c
     311.. code-block:: c
    289312
    290313    #include <unistd.h>
    291314    int write(
    292315    int           fildes,
    293     const void   \*buf,
    294     unsigned int  nbytes
    295     );
    296 
    297 **STATUS CODES:**
    298 
    299 *EAGAIN*
    300     The O_NONBLOCK flag is set for a file descriptor and the process
    301     would be delayed in the I/O operation.
    302 
    303 *EBADF*
    304     Invalid file descriptor
    305 
    306 *EFBIG*
    307     An attempt was made to write to a file that exceeds the maximum file
    308     size
    309 
    310 *EINTR*
    311     The function was interrupted by a signal.
    312 
    313 *EIO*
    314     Input or output error.
    315 
    316 *ENOSPC*
    317     No space left on disk.
    318 
    319 *EPIPE*
    320     Attempt to write to a pope or FIFO with no reader.
    321 
    322 *EINVAL*
    323     Bad buffer pointer
    324 
    325 **DESCRIPTION:**
    326 
    327 The ``write()`` function writes ``nbyte`` from the array pointed
    328 to by ``buf`` into the file associated with ``fildes``.
    329 
    330 If ``nybte`` is zero and the file is a regular file, the ``write()``
    331 function returns zero and has no other effect. If ``nbyte`` is zero
    332 and the file is a special file, te results are not portable.
    333 
    334 The ``write()`` function returns the number of bytes written. This
    335 number will be less than ``nbytes`` if there is an error. It will never
    336 be greater than ``nbytes``.
    337 
    338 **NOTES:**
    339 
    340 NONE
     316        const void   *buf,
     317        unsigned int  nbytes
     318    );
     319
     320**STATUS CODES:**
     321
     322.. list-table::
     323 :class: rtems-table
     324
     325 * - ``EAGAIN``
     326   - The O_NONBLOCK flag is set for a file descriptor and the process would be
     327     delayed in the I/O operation.
     328 * - ``EBADF``
     329   - Invalid file descriptor
     330 * - ``EFBIG``
     331   - An attempt was made to write to a file that exceeds the maximum file size
     332 * - ``EINTR``
     333   - The function was interrupted by a signal.
     334 * - ``EIO``
     335   - Input or output error.
     336 * - ``ENOSPC``
     337   - No space left on disk.
     338 * - ``EPIPE``
     339   - Attempt to write to a pope or FIFO with no reader.
     340 * - ``EINVAL``
     341   - Bad buffer pointer
     342
     343**DESCRIPTION:**
     344
     345The ``write()`` function writes ``nbyte`` from the array pointed to by ``buf``
     346into the file associated with ``fildes``.
     347
     348If ``nybte`` is zero and the file is a regular file, the ``write()`` function
     349returns zero and has no other effect. If ``nbyte`` is zero and the file is a
     350special file, te results are not portable.
     351
     352The ``write()`` function returns the number of bytes written. This number will
     353be less than ``nbytes`` if there is an error. It will never be greater than
     354``nbytes``.
     355
     356**NOTES:**
     357
     358NONE
     359
     360.. _fcntl:
    341361
    342362fcntl - Manipulates an open file descriptor
     
    347367**CALLING SEQUENCE:**
    348368
    349 .. code:: c
     369.. code-block:: c
    350370
    351371    #include <sys/types.h>
     
    353373    #include <unistd.h>
    354374    int fcntl(
    355     int fildes,
    356     int cmd
    357     );
    358 
    359 **STATUS CODES:**
    360 
    361 *EACCESS*
    362     Search permission is denied for a direcotry in a file's path
    363     prefix.
    364 
    365 *EAGAIN*
    366     The O_NONBLOCK flag is set for a file descriptor and the process
    367     would be delayed in the I/O operation.
    368 
    369 *EBADF*
    370     Invalid file descriptor
    371 
    372 *EDEADLK*
    373     An ``fcntl`` with function F_SETLKW would cause a deadlock.
    374 
    375 *EINTR*
    376     The functioin was interrupted by a signal.
    377 
    378 *EINVAL*
    379     Invalid argument
    380 
    381 *EMFILE*
    382     Too many file descriptor or in use by the process.
    383 
    384 *ENOLCK*
    385     No locks available
    386 
    387 **DESCRIPTION:**
    388 
    389 ``fcntl()`` performs one of various miscellaneous operations on``fd``. The operation in question is determined by ``cmd``:
    390 
    391 *F_DUPFD*
    392     Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary.
    393     The same functionality can be more easily achieved by using ``dup2()``.
    394     The old and new descriptors may be used interchangeably. They share locks,
    395     file position pointers and flags; for example, if the file position is
    396     modified by using ``lseek()`` on one of the descriptors, the position is
    397     also changed for the other.
    398     The two descriptors do not share the close-on-exec flag, however. The
    399     close-on-exec flag of the copy is off, meaning that it will be closed on
    400     exec.
    401     On success, the new descriptor is returned.
    402 
    403 *F_GETFD*
    404     Read the close-on-exec flag. If the low-order bit is 0, the file will
    405     remain open across exec, otherwise it will be closed.
    406 
    407 *F_SETFD*
    408     Set the close-on-exec flag to the value specified by ``arg`` (only the least
    409     significant bit is used).
    410 
    411 *F_GETFL*
    412     Read the descriptor's flags (all flags (as set by open()) are returned).
    413 
    414 *F_SETFL*
    415     Set the descriptor's flags to the value specified by ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set.
    416     The flags are shared between copies (made with ``dup()`` etc.) of the same
    417     file descriptor.
    418     The flags and their semantics are described in ``open()``.
    419 
    420 *F_GETLK, F_SETLK and F_SETLKW*
    421     Manage discretionary file locks. The third argument ``arg`` is a pointer to a
    422     struct flock (that may be overwritten by this call).
    423 
    424 *F_GETLK*
    425     Return the flock structure that prevents us from obtaining the lock, or set the``l_type`` field of the lock to ``F_UNLCK`` if there is no obstruction.
    426 
    427 *F_SETLK*
    428     The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or
    429     cleared (when it is ``F_UNLCK``. If lock is held by someone else, this
    430     call returns -1 and sets ``errno`` to EACCES or EAGAIN.
    431 
    432 *F_SETLKW*
    433     Like ``F_SETLK``, but instead of returning an error we wait for the lock to
    434     be released.
    435 
    436 *F_GETOWN*
    437     Get the process ID (or process group) of the owner of a socket.
    438     Process groups are returned as negative values.
    439 
    440 *F_SETOWN*
    441     Set the process or process group that owns a socket.
    442     For these commands, ownership means receiving ``SIGIO`` or ``SIGURG``
    443     signals.
    444     Process groups are specified using negative values.
    445 
    446 **NOTES:**
    447 
    448 The errors returned by ``dup2`` are different from those returned by``F_DUPFD``.
     375        int fildes,
     376        int cmd
     377    );
     378
     379**STATUS CODES:**
     380
     381.. list-table::
     382 :class: rtems-table
     383
     384 * - ``EACCESS``
     385   - Search permission is denied for a direcotry in a file's path prefix.
     386 * - ``EAGAIN``
     387   - The O_NONBLOCK flag is set for a file descriptor and the process would be
     388     delayed in the I/O operation.
     389 * - ``EBADF``
     390   - Invalid file descriptor
     391 * - ``EDEADLK``
     392   - An ``fcntl`` with function ``F_SETLKW`` would cause a deadlock.
     393 * - ``EINTR``
     394   - The functioin was interrupted by a signal.
     395 * - ``EINVAL``
     396   - Invalid argument
     397 * - ``EMFILE``
     398   - Too many file descriptor or in use by the process.
     399 * - ``ENOLCK``
     400   - No locks available
     401
     402**DESCRIPTION:**
     403
     404``fcntl()`` performs one of various miscellaneous operations on``fd``. The
     405operation in question is determined by ``cmd``:
     406
     407.. list-table::
     408 :class: rtems-table
     409
     410 * - ``F_DUPFD``
     411   - Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary.  The
     412     same functionality can be more easily achieved by using ``dup2()``.  The
     413     old and new descriptors may be used interchangeably. They share locks,
     414     file position pointers and flags; for example, if the file position is
     415     modified by using ``lseek()`` on one of the descriptors, the position is
     416     also changed for the other.  The two descriptors do not share the
     417     close-on-exec flag, however. The close-on-exec flag of the copy is off,
     418     meaning that it will be closed on exec.  On success, the new descriptor is
     419     returned.
     420 * - ``F_GETFD``
     421   - Read the close-on-exec flag. If the low-order bit is 0, the file will
     422     remain open across exec, otherwise it will be closed.
     423 * - ``F_SETFD``
     424   - Set the close-on-exec flag to the value specified by ``arg`` (only the
     425     least significant bit is used).
     426 * - ``F_GETFL``
     427   - Read the descriptor's flags (all flags (as set by open()) are returned).
     428 * - ``F_SETFL``
     429   - Set the descriptor's flags to the value specified by
     430     ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set.  The flags are
     431     shared between copies (made with ``dup()`` etc.) of the same file
     432     descriptor.  The flags and their semantics are described in ``open()``.
     433 * - ``F_GETLK``, ``F_SETLK`` and ``F_SETLKW``
     434   - Manage discretionary file locks. The third argument ``arg`` is a pointer
     435     to a struct flock (that may be overwritten by this call).
     436 * - ``F_GETLK``
     437   - Return the flock structure that prevents us from obtaining the lock, or
     438     set the``l_type`` field of the lock to ``F_UNLCK`` if there is no
     439     obstruction.
     440 * - ``F_SETLK``
     441   - The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or cleared
     442     (when it is ``F_UNLCK``. If lock is held by someone else, this call
     443     returns -1 and sets ``errno`` to EACCES or EAGAIN.
     444 * - ``F_SETLKW``
     445   - Like ``F_SETLK``, but instead of returning an error we wait for the lock
     446     to be released.
     447 * - ``F_GETOWN``
     448   - Get the process ID (or process group) of the owner of a socket.  Process
     449     groups are returned as negative values.
     450 * - ``F_SETOWN``
     451   - Set the process or process group that owns a socket.  For these commands,
     452     ownership means receiving ``SIGIO`` or ``SIGURG`` signals.  Process groups
     453     are specified using negative values.
     454
     455**NOTES:**
     456
     457The errors returned by ``dup2`` are different from those returned by ``F_DUPFD``.
     458
     459.. _lseek:
    449460
    450461lseek - Reposition read/write file offset
     
    455466**CALLING SEQUENCE:**
    456467
    457 .. code:: c
     468.. code-block:: c
    458469
    459470    #include <sys/types.h>
    460471    #include <unistd.h>
    461472    int lseek(
    462     int    fildes,
    463     off_t  offset,
    464     int    whence
    465     );
    466 
    467 **STATUS CODES:**
    468 
    469 *EBADF*
    470     ``fildes`` is not an open file descriptor.
    471 
    472 *ESPIPE*
    473     ``fildes`` is associated with a pipe, socket or FIFO.
    474 
    475 *EINVAL*
    476     ``whence`` is not a proper value.
    477 
    478 **DESCRIPTION:**
    479 
    480 The ``lseek`` function repositions the offset of the file descriptor``fildes`` to the argument offset according to the directive whence.
    481 The argument ``fildes`` must be an open file descriptor. ``Lseek``
    482 repositions the file pointer fildes as follows:
     473        int    fildes,
     474        off_t  offset,
     475        int    whence
     476    );
     477
     478**STATUS CODES:**
     479
     480.. list-table::
     481 :class: rtems-table
     482
     483 * - ``EBADF``
     484   - ``fildes`` is not an open file descriptor.
     485 * - ``ESPIPE``
     486   - ``fildes`` is associated with a pipe, socket or FIFO.
     487 * - ``EINVAL``
     488   - ``whence`` is not a proper value.
     489
     490**DESCRIPTION:**
     491
     492The ``lseek`` function repositions the offset of the file descriptor ``fildes``
     493to the argument offset according to the directive whence.  The argument
     494``fildes`` must be an open file descriptor. ``Lseek`` repositions the file
     495pointer fildes as follows:
    483496
    484497- If ``whence`` is SEEK_SET, the offset is set to ``offset`` bytes.
     
    490503  file plus ``offset`` bytes.
    491504
    492 The ``lseek`` function allows the file offset to be set beyond the end
    493 of the existing end-of-file of the file. If data is later written at this
    494 point, subsequent reads of the data in the gap return bytes of zeros
    495 (until data is actually written into the gap).
    496 
    497 Some devices are incapable of seeking. The value of the pointer associated
    498 with such a device is undefined.
    499 
    500 **NOTES:**
    501 
    502 NONE
     505The ``lseek`` function allows the file offset to be set beyond the end of the
     506existing end-of-file of the file. If data is later written at this point,
     507subsequent reads of the data in the gap return bytes of zeros (until data is
     508actually written into the gap).
     509
     510Some devices are incapable of seeking. The value of the pointer associated with
     511such a device is undefined.
     512
     513**NOTES:**
     514
     515NONE
     516
     517.. _fsync:
    503518
    504519fsync - Synchronize file complete in-core state with that on disk
     
    509524**CALLING SEQUENCE:**
    510525
    511 .. code:: c
     526.. code-block:: c
    512527
    513528    int fsync(
    514     int fd
    515     );
    516 
    517 **STATUS CODES:**
    518 
    519 On success, zero is returned. On error, -1 is returned, and ``errno``
    520 is set appropriately.
    521 
    522 *EBADF*
    523     ``fd`` is not a valid descriptor open for writing
    524 
    525 *EINVAL*
    526     ``fd`` is bound to a special file which does not support support synchronization
    527 
    528 *EROFS*
    529     ``fd`` is bound to a special file which does not support support synchronization
    530 
    531 *EIO*
    532     An error occurred during synchronization
     529        int fd
     530    );
     531
     532**STATUS CODES:**
     533
     534On success, zero is returned. On error, -1 is returned, and ``errno`` is set
     535appropriately.
     536
     537.. list-table::
     538 :class: rtems-table
     539
     540 * - ``EBADF``
     541   - ``fd`` is not a valid descriptor open for writing
     542 * - ``EINVAL``
     543   - ``fd`` is bound to a special file which does not support support
     544      synchronization
     545 * - ``EROFS``
     546   - ``fd`` is bound to a special file which does not support support
     547      synchronization
     548 * - ``EIO``
     549   - An error occurred during synchronization
    533550
    534551**DESCRIPTION:**
     
    539556
    540557NONE
     558
     559.. _fdatasync:
    541560
    542561fdatasync - Synchronize file in-core data with that on disk
     
    547566**CALLING SEQUENCE:**
    548567
    549 .. code:: c
     568.. code-block:: c
    550569
    551570    int fdatasync(
    552     int fd
    553     );
    554 
    555 **STATUS CODES:**
    556 
    557 On success, zero is returned. On error, -1 is returned, and ``errno`` is
    558 set appropriately.
    559 
    560 *EBADF*
    561     ``fd`` is not a valid file descriptor open for writing.
    562 
    563 *EINVAL*
    564     ``fd`` is bound to a special file which does not support synchronization.
    565 
    566 *EIO*
    567     An error occurred during synchronization.
    568 
    569 *EROFS*
    570     ``fd`` is bound to a special file which dows not support synchronization.
    571 
    572 **DESCRIPTION:**
    573 
    574 ``fdatasync`` flushes all data buffers of a file to disk (before the system call
    575 returns). It resembles ``fsync`` but is not required to update the metadata such
    576 as access time.
    577 
    578 Applications that access databases or log files often write a tiny data fragment
    579 (e.g., one line in a log file) and then call ``fsync`` immediately in order to
    580 ensure that the written data is physically stored on the harddisk. Unfortunately,
    581 fsync will always initiate two write operations: one for the newly written data and
    582 another one in order to update the modification time stored in the inode. If the
    583 modification time is not a part of the transaction concept ``fdatasync`` can be
    584 used to avoid unnecessary inode disk write operations.
    585 
    586 **NOTES:**
    587 
    588 NONE
     571        int fd
     572    );
     573
     574**STATUS CODES:**
     575
     576On success, zero is returned. On error, -1 is returned, and ``errno`` is set
     577appropriately.
     578
     579.. list-table::
     580 :class: rtems-table
     581
     582 * - ``EBADF``
     583   - ``fd`` is not a valid file descriptor open for writing.
     584 * - ``EINVAL``
     585   - ``fd`` is bound to a special file which does not support synchronization.
     586 * - ``EIO``
     587   - An error occurred during synchronization.
     588 * - ``EROFS``
     589   - ``fd`` is bound to a special file which dows not support synchronization.
     590
     591**DESCRIPTION:**
     592
     593``fdatasync`` flushes all data buffers of a file to disk (before the system
     594call returns). It resembles ``fsync`` but is not required to update the
     595metadata such as access time.
     596
     597Applications that access databases or log files often write a tiny data
     598fragment (e.g., one line in a log file) and then call ``fsync`` immediately in
     599order to ensure that the written data is physically stored on the
     600harddisk. Unfortunately, fsync will always initiate two write operations: one
     601for the newly written data and another one in order to update the modification
     602time stored in the inode. If the modification time is not a part of the
     603transaction concept ``fdatasync`` can be used to avoid unnecessary inode disk
     604write operations.
     605
     606**NOTES:**
     607
     608NONE
     609
     610.. _sync:
    589611
    590612sync - Schedule file system updates
     
    595617**CALLING SEQUENCE:**
    596618
    597 .. code:: c
     619.. code-block:: c
    598620
    599621    void sync(void);
     
    605627**DESCRIPTION:**
    606628
    607 The ``sync`` service causes all information in memory that updates
    608 file systems to be scheduled for writing out to all file systems.
    609 
    610 **NOTES:**
    611 
    612 The writing of data to the file systems is only guaranteed to be
    613 scheduled upon return.  It is not necessarily complete upon return
    614 from ``sync``.
     629The ``sync`` service causes all information in memory that updates file systems
     630to be scheduled for writing out to all file systems.
     631
     632**NOTES:**
     633
     634The writing of data to the file systems is only guaranteed to be scheduled upon
     635return.  It is not necessarily complete upon return from ``sync``.
     636
     637.. _mount:
    615638
    616639mount - Mount a file system
     
    621644**CALLING SEQUENCE:**
    622645
    623 .. code:: c
     646.. code-block:: c
    624647
    625648    #include <libio.h>
    626649    int mount(
    627     rtems_filesystem_mount_table_entry_t \**mt_entry,
    628     rtems_filesystem_operations_table    \*fs_ops,
    629     rtems_filesystem_options_t            fsoptions,
    630     char                                 \*device,
    631     char                                 \*mount_point
     650        rtems_filesystem_mount_table_entry_t **mt_entry,
     651        rtems_filesystem_operations_table    *fs_ops,
     652        rtems_filesystem_options_t            fsoptions,
     653        char                                 *device,
     654        char                                 *mount_point
    632655    );
    633656
     
    638661**DESCRIPTION:**
    639662
    640 The ``mount`` routines mounts the filesystem class
    641 which uses the filesystem operations specified by ``fs_ops``
    642 and ``fsoptions``.  The filesystem is mounted at the directory``mount_point`` and the mode of the mounted filesystem is
    643 specified by ``fsoptions``.  If this filesystem class requires
    644 a device, then the name of the device must be specified by ``device``.
    645 
    646 If this operation succeeds, the mount table entry for the mounted
    647 filesystem is returned in ``mt_entry``.
    648 
    649 **NOTES:**
    650 
    651 NONE
     663The ``mount`` routines mounts the filesystem class which uses the filesystem
     664operations specified by ``fs_ops`` and ``fsoptions``.  The filesystem is
     665mounted at the directory ``mount_point`` and the mode of the mounted filesystem
     666is specified by ``fsoptions``.  If this filesystem class requires a device,
     667then the name of the device must be specified by ``device``.
     668
     669If this operation succeeds, the mount table entry for the mounted filesystem is
     670returned in ``mt_entry``.
     671
     672**NOTES:**
     673
     674NONE
     675
     676.. _unmount:
    652677
    653678unmount - Unmount file systems
     
    658683**CALLING SEQUENCE:**
    659684
    660 .. code:: c
     685.. code-block:: c
    661686
    662687    #include <libio.h>
    663688    int unmount(
    664     const char \*mount_path
     689        const char \*mount_path
    665690    );
    666691
     
    671696**DESCRIPTION:**
    672697
    673 The ``unmount`` routine removes the attachment of the filesystem specified
    674 by ``mount_path``.
    675 
    676 **NOTES:**
    677 
    678 NONE
     698The ``unmount`` routine removes the attachment of the filesystem specified by
     699``mount_path``.
     700
     701**NOTES:**
     702
     703NONE
     704
     705.. _readv:
    679706
    680707readv - Vectored read from a file
     
    685712**CALLING SEQUENCE:**
    686713
    687 .. code:: c
     714.. code-block:: c
    688715
    689716    #include <sys/uio.h>
    690717    ssize_t readv(
    691     int                 fd,
    692     const struct iovec \*iov,
    693     int                 iovcnt
    694     );
    695 
    696 **STATUS CODES:**
    697 
    698 In addition to the errors detected by``Input and Output Primitives Manager read - Reads from a file, read()``,
    699 this routine may return -1 and sets ``errno`` based upon the following
    700 errors:
    701 
    702 *EINVAL*
    703     The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
    704 
    705 *EINVAL*
    706     The ``iovcnt`` argument was less than or equal to 0, or greater
    707     than ``IOV_MAX``.
    708 
    709 **DESCRIPTION:**
    710 
    711 The ``readv()`` function is equivalent to ``read()``
    712 except as described here. The ``readv()`` function shall place
    713 the input data into the ``iovcnt`` buffers specified by the
    714 members of the ``iov`` array: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
    715 
    716 Each ``iovec`` entry specifies the base address and length of an area
    717 in memory where data should be placed. The ``readv()`` function
    718 always fills an area completely before proceeding to the next.
    719 
    720 **NOTES:**
    721 
    722 NONE
     718        int                 fd,
     719        const struct iovec *iov,
     720        int                 iovcnt
     721    );
     722
     723**STATUS CODES:**
     724
     725In addition to the errors detected by *Input and Output Primitives Manager
     726read - Reads from a file, read()*, this routine may return -1 and sets
     727``errno`` based upon the following errors:
     728
     729.. list-table::
     730 :class: rtems-table
     731
     732 * - ``EINVAL``
     733   - The sum of the ``iov_len`` values in the iov array overflowed
     734     an ``ssize_t``.
     735 * - ``EINVAL``
     736   - The ``iovcnt`` argument was less than or equal to 0, or greater than
     737     ``IOV_MAX``.
     738
     739**DESCRIPTION:**
     740
     741The ``readv()`` function is equivalent to ``read()`` except as described
     742here. The ``readv()`` function shall place the input data into the ``iovcnt``
     743buffers specified by the members of the ``iov`` array: ``iov[0], iov[1], ...,
     744iov[iovcnt-1]``.
     745
     746Each ``iovec`` entry specifies the base address and length of an area in memory
     747where data should be placed. The ``readv()`` function always fills an area
     748completely before proceeding to the next.
     749
     750**NOTES:**
     751
     752NONE
     753
     754.. _writev:
    723755
    724756writev - Vectored write to a file
     
    729761**CALLING SEQUENCE:**
    730762
    731 .. code:: c
     763.. code-block:: c
    732764
    733765    #include <sys/uio.h>
    734766    ssize_t writev(
    735     int                 fd,
    736     const struct iovec \*iov,
    737     int                 iovcnt
    738     );
    739 
    740 **STATUS CODES:**
    741 
    742 In addition to the errors detected by``Input and Output Primitives Manager write - Write to a file, write()``,
    743 this routine may return -1 and sets ``errno`` based upon the following
    744 errors:
    745 
    746 *EINVAL*
    747     The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
    748 
    749 *EINVAL*
    750     The ``iovcnt`` argument was less than or equal to 0, or greater
    751     than ``IOV_MAX``.
    752 
    753 **DESCRIPTION:**
    754 
    755 The ``writev()`` function is equivalent to ``write()``,
    756 except as noted here. The ``writev()`` function gathers output
    757 data from the ``iovcnt`` buffers specified by the members of
    758 the ``iov array``: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
    759 The ``iovcnt`` argument is valid if greater than 0 and less
     767        int                 fd,
     768        const struct iovec \*iov,
     769        int                 iovcnt
     770    );
     771
     772**STATUS CODES:**
     773
     774In addition to the errors detected by *Input and Output Primitives Manager
     775write - Write to a file, write()*, this routine may return -1 and sets
     776``errno`` based upon the following errors:
     777
     778.. list-table::
     779 :class: rtems-table
     780
     781 * - ``EINVAL``
     782   - The sum of the ``iov_len`` values in the iov array overflowed
     783     an ``ssize_t``.
     784 * - ``EINVAL``
     785   - The ``iovcnt`` argument was less than or equal to 0, or greater than
     786     ``IOV_MAX``.
     787
     788**DESCRIPTION:**
     789
     790The ``writev()`` function is equivalent to ``write()``, except as noted
     791here. The ``writev()`` function gathers output data from the ``iovcnt`` buffers
     792specified by the members of the ``iov array``: ``iov[0], iov[1], ...,
     793iov[iovcnt-1]``.  The ``iovcnt`` argument is valid if greater than 0 and less
    760794than or equal to ``IOV_MAX``.
    761795
    762 Each ``iovec`` entry specifies the base address and length of
    763 an area in memory from which data should be written. The ``writev()``
    764 function always writes a complete area before proceeding to the next.
    765 
    766 If ``fd`` refers to a regular file and all of the ``iov_len``
    767 members in the array pointed to by ``iov`` are 0, ``writev()``
    768 returns 0 and has no other effect. For other file types, the behavior
    769 is unspecified by POSIX.
    770 
    771 **NOTES:**
    772 
    773 NONE
     796Each ``iovec`` entry specifies the base address and length of an area in memory
     797from which data should be written. The ``writev()`` function always writes a
     798complete area before proceeding to the next.
     799
     800If ``fd`` refers to a regular file and all of the ``iov_len`` members in the
     801array pointed to by ``iov`` are 0, ``writev()`` returns 0 and has no other
     802effect. For other file types, the behavior is unspecified by POSIX.
     803
     804**NOTES:**
     805
     806NONE
     807
     808.. _aio_read:
    774809
    775810aio_read - Asynchronous Read
     
    780815**CALLING SEQUENCE:**
    781816
    782 .. code:: c
     817.. code-block:: c
    783818
    784819    int aio_read(
     
    787822**STATUS CODES:**
    788823
    789 *E*
    790     The
    791 
    792 **DESCRIPTION:**
    793 
    794 **NOTES:**
    795 
    796 This routine is not currently supported by RTEMS but could be
    797 in a future version.
     824.. list-table::
     825 :class: rtems-table
     826
     827 * - ``E``
     828   - The
     829
     830**DESCRIPTION:**
     831
     832**NOTES:**
     833
     834This routine is not currently supported by RTEMS but could be in a future
     835version.
     836
     837.. _aio_write:
    798838
    799839aio_write - Asynchronous Write
     
    804844**CALLING SEQUENCE:**
    805845
    806 .. code:: c
     846.. code-block:: c
    807847
    808848    int aio_write(
     
    811851**STATUS CODES:**
    812852
    813 *E*
    814     The
    815 
    816 **DESCRIPTION:**
    817 
    818 **NOTES:**
    819 
    820 This routine is not currently supported by RTEMS but could be
    821 in a future version.
     853.. list-table::
     854 :class: rtems-table
     855
     856 * - ``E``
     857   - The
     858
     859**DESCRIPTION:**
     860
     861**NOTES:**
     862
     863This routine is not currently supported by RTEMS but could be in a future
     864version.
     865
     866.. _lio_listio:
    822867
    823868lio_listio - List Directed I/O
     
    828873**CALLING SEQUENCE:**
    829874
    830 .. code:: c
     875.. code-block:: c
    831876
    832877    int lio_listio(
     
    835880**STATUS CODES:**
    836881
    837 *E*
    838     The
    839 
    840 **DESCRIPTION:**
    841 
    842 **NOTES:**
    843 
    844 This routine is not currently supported by RTEMS but could be
    845 in a future version.
     882.. list-table::
     883 :class: rtems-table
     884
     885 * - ``E``
     886   - The
     887
     888**DESCRIPTION:**
     889
     890**NOTES:**
     891
     892This routine is not currently supported by RTEMS but could be in a future
     893version.
     894
     895.. _aio_error:
    846896
    847897aio_error - Retrieve Error Status of Asynchronous I/O Operation
     
    852902**CALLING SEQUENCE:**
    853903
    854 .. code:: c
     904.. code-block:: c
    855905
    856906    int aio_error(
     
    859909**STATUS CODES:**
    860910
    861 *E*
    862     The
    863 
    864 **DESCRIPTION:**
    865 
    866 **NOTES:**
    867 
    868 This routine is not currently supported by RTEMS but could be
    869 in a future version.
     911.. list-table::
     912 :class: rtems-table
     913
     914 * - ``E``
     915   - The
     916
     917**DESCRIPTION:**
     918
     919**NOTES:**
     920
     921This routine is not currently supported by RTEMS but could be in a future
     922version.
     923
     924.. _aio_return:
    870925
    871926aio_return - Retrieve Return Status Asynchronous I/O Operation
     
    876931**CALLING SEQUENCE:**
    877932
    878 .. code:: c
     933.. code-block:: c
    879934
    880935    int aio_return(
     
    883938**STATUS CODES:**
    884939
    885 *E*
    886     The
    887 
    888 **DESCRIPTION:**
    889 
    890 **NOTES:**
    891 
    892 This routine is not currently supported by RTEMS but could be
    893 in a future version.
     940.. list-table::
     941 :class: rtems-table
     942
     943 * - ``E``
     944   - The
     945
     946**DESCRIPTION:**
     947
     948**NOTES:**
     949
     950This routine is not currently supported by RTEMS but could be in a future
     951version.
     952
     953.. _aio_cancel:
    894954
    895955aio_cancel - Cancel Asynchronous I/O Request
     
    900960**CALLING SEQUENCE:**
    901961
    902 .. code:: c
     962.. code-block:: c
    903963
    904964    int aio_cancel(
     
    907967**STATUS CODES:**
    908968
    909 *E*
    910     The
    911 
    912 **DESCRIPTION:**
    913 
    914 **NOTES:**
    915 
    916 This routine is not currently supported by RTEMS but could be
    917 in a future version.
     969.. list-table::
     970 :class: rtems-table
     971
     972 * - ``E``
     973   - The
     974
     975**DESCRIPTION:**
     976
     977**NOTES:**
     978
     979This routine is not currently supported by RTEMS but could be in a future
     980version.
     981
     982.. _aio_suspend:
    918983
    919984aio_suspend - Wait for Asynchronous I/O Request
     
    924989**CALLING SEQUENCE:**
    925990
    926 .. code:: c
     991.. code-block:: c
    927992
    928993    int aio_suspend(
     
    931996**STATUS CODES:**
    932997
    933 *E*
    934     The
    935 
    936 **DESCRIPTION:**
    937 
    938 **NOTES:**
    939 
    940 This routine is not currently supported by RTEMS but could be
    941 in a future version.
     998.. list-table::
     999 :class: rtems-table
     1000
     1001 * - ``E``
     1002   - The
     1003
     1004**DESCRIPTION:**
     1005
     1006**NOTES:**
     1007
     1008This routine is not currently supported by RTEMS but could be in a future
     1009version.
     1010
     1011.. _aio_fsync:
    9421012
    9431013aio_fsync - Asynchronous File Synchronization
     
    9481018**CALLING SEQUENCE:**
    9491019
    950 .. code:: c
     1020.. code-block:: c
    9511021
    9521022    int aio_fsync(
     
    9551025**STATUS CODES:**
    9561026
    957 *E*
    958     The
    959 
    960 **DESCRIPTION:**
    961 
    962 **NOTES:**
    963 
    964 This routine is not currently supported by RTEMS but could be
    965 in a future version.
    966 
    967 .. COMMENT: COPYRIGHT (c) 1988-2002.
    968 
    969 .. COMMENT: On-Line Applications Research Corporation (OAR).
    970 
    971 .. COMMENT: All rights reserved.
    972 
     1027.. list-table::
     1028 :class: rtems-table
     1029
     1030 * - ``E``
     1031   - The
     1032
     1033**DESCRIPTION:**
     1034
     1035**NOTES:**
     1036
     1037This routine is not currently supported by RTEMS but could be in a future
     1038version.
  • posix_users/key.rst

    r238bf99 rfa70fd2  
     1.. COMMENT: COPYRIGHT (c) 1988-2002.
     2.. COMMENT: On-Line Applications Research Corporation (OAR).
     3.. COMMENT: All rights reserved.
     4
    15Key Manager
    26###########
     
    1014The directives provided by the key manager are:
    1115
    12 - ``pthread_key_create`` - Create Thread Specific Data Key
    13 
    14 - ``pthread_key_delete`` - Delete Thread Specific Data Key
    15 
    16 - ``pthread_setspecific`` - Set Thread Specific Key Value
    17 
    18 - ``pthread_getspecific`` - Get Thread Specific Key Value
     16- pthread_key_create_ - Create Thread Specific Data Key
     17
     18- pthread_key_delete_ - Delete Thread Specific Data Key
     19
     20- pthread_setspecific_ - Set Thread Specific Key Value
     21
     22- pthread_getspecific_ - Get Thread Specific Key Value
    1923
    2024Background
     
    3135==========
    3236
    33 This section details the key manager's directives.
    34 A subsection is dedicated to each of this manager's directives
    35 and describes the calling sequence, related constants, usage,
    36 and status codes.
     37This section details the key manager's directives.  A subsection is dedicated
     38to each of this manager's directives and describes the calling sequence,
     39related constants, usage, and status codes.
     40
     41.. _pthread_key_create:
    3742
    3843pthread_key_create - Create Thread Specific Data Key
     
    4146**CALLING SEQUENCE:**
    4247
    43 .. code:: c
     48.. code-block:: c
    4449
    4550    #include <pthread.h>
    4651    int pthread_key_create(
    47     pthread_key_t \*key,
    48     void (\*destructor)( void )
    49     );
    50 
    51 **STATUS CODES:**
    52 
    53 *EAGAIN*
    54     There were not enough resources available to create another key.
    55 
    56 *ENOMEM*
    57     Insufficient memory exists to create the key.
     52        pthread_key_t *key,
     53        void (*destructor)( void )
     54    );
     55
     56**STATUS CODES:**
     57
     58.. list-table::
     59 :class: rtems-table
     60
     61 * - ``EAGAIN``
     62   - There were not enough resources available to create another key.
     63 * - ``ENOMEM``
     64   - Insufficient memory exists to create the key.
    5865
    5966**DESCRIPTION**
    6067
    61 The pthread_key_create() function shall create a thread-specific data
    62 key visible to all threads in the process. Key values provided by
    63 pthread_key_create() are opaque objects used to locate thread-specific
    64 data. Although the same key value may be used by different threads, the
    65 values bound to the key by pthread_setspecific() are maintained on a
    66 per-thread basis and persist for the life of the calling thread.
    67 
    68 Upon key creation, the value NULL shall be associated with the new key
    69 in all active threads. Upon thread creation, the value NULL shall be
     68The ``pthread_key_create()`` function shall create a thread-specific data key
     69visible to all threads in the process. Key values provided by
     70``pthread_key_create()`` are opaque objects used to locate thread-specific
     71data. Although the same key value may be used by different threads, the values
     72bound to the key by ``pthread_setspecific()`` are maintained on a per-thread
     73basis and persist for the life of the calling thread.
     74
     75Upon key creation, the value ``NULL`` shall be associated with the new key in
     76all active threads. Upon thread creation, the value ``NULL`` shall be
    7077associated with all defined keys in the new thread.
    7178
    7279**NOTES**
    7380
    74 An optional destructor function may be associated with each key value.
    75 At thread exit, if a key value has a non-NULL destructor pointer, and
    76 the thread has a non-NULL value associated with that key, the value of
    77 the key is set to NULL, and then the function pointed to is called with
    78 the previously associated value as its sole argument. The order of
    79 destructor calls is unspecified if more than one destructor exists for
    80 a thread when it exits.
     81An optional destructor function may be associated with each key value.  At
     82thread exit, if a key value has a non-``NULL`` destructor pointer, and the
     83thread has a non-``NULL`` value associated with that key, the value of the key
     84is set to NULL, and then the function pointed to is called with the previously
     85associated value as its sole argument. The order of destructor calls is
     86unspecified if more than one destructor exists for a thread when it exits.
     87
     88.. _pthread_key_delete:
    8189
    8290pthread_key_delete - Delete Thread Specific Data Key
     
    8593**CALLING SEQUENCE:**
    8694
    87 .. code:: c
     95.. code-block:: c
    8896
    8997    #include <pthread.h>
    9098    int pthread_key_delete(
    91     pthread_key_t key);
    92 
    93 **STATUS CODES:**
    94 
    95 *EINVAL*
    96     The key was invalid
     99        pthread_key_t key
     100    );
     101
     102**STATUS CODES:**
     103
     104.. list-table::
     105 :class: rtems-table
     106
     107 * - ``EINVAL``
     108   - The key was invalid
    97109
    98110**DESCRIPTION:**
    99111
    100 The pthread_key_delete() function shall delete a thread-specific data key
    101 previously returned by pthread_key_create(). The thread-specific data
    102 values associated with key need not be NULL at the time pthread_key_delete()
    103 is called. It is the responsibility of the application to free any
    104 application storage or perform any cleanup actions for data structures related
    105 to the deleted key or associated thread-specific data in any
     112The ``pthread_key_delete()`` function shall delete a thread-specific data key
     113previously returned by ``pthread_key_create()``. The thread-specific data
     114values associated with key need not be NULL at the time
     115``pthread_key_delete()`` is called. It is the responsibility of the application
     116to free any application storage or perform any cleanup actions for data
     117structures related to the deleted key or associated thread-specific data in any
    106118threads; this cleanup can be done either before or after
    107 pthread_key_delete() is called. Any attempt to use key following the call to
    108 pthread_key_delete() results in undefined behavior.
     119``pthread_key_delete()`` is called. Any attempt to use key following the call
     120to ``pthread_key_delete()`` results in undefined behavior.
    109121
    110122**NOTES:**
    111123
    112 The pthread_key_delete() function shall be callable from within
    113 destructor functions. No destructor functions shall be invoked by
    114 pthread_key_delete(). Any destructor function that may have been
    115 associated with key shall no longer be called upon thread exit.
     124The ``pthread_key_delete()`` function shall be callable from within destructor
     125functions. No destructor functions shall be invoked by
     126``pthread_key_delete()``. Any destructor function that may have been associated
     127with key shall no longer be called upon thread exit.
     128
     129.. _pthread_setspecific:
    116130
    117131pthread_setspecific - Set Thread Specific Key Value
     
    120134**CALLING SEQUENCE:**
    121135
    122 .. code:: c
     136.. code-block:: c
    123137
    124138    #include <pthread.h>
    125139    int pthread_setspecific(
    126     pthread_key_t key,
    127     const void \*value
    128     );
    129 
    130 **STATUS CODES:**
    131 
    132 *EINVAL*
    133     The specified key is invalid.
     140        pthread_key_t  key,
     141        const void    *value
     142    );
     143
     144**STATUS CODES:**
     145
     146.. list-table::
     147 :class: rtems-table
     148
     149 * - ``EINVAL``
     150   - The specified key is invalid.
    134151
    135152**DESCRIPTION:**
    136153
    137 The pthread_setspecific() function shall associate a thread-specific value
    138 with a key obtained via a previous call to pthread_key_create().
    139 Different threads may bind different values to the same key. These values
    140 are typically pointers to blocks of dynamically allocated memory that
    141 have been reserved for use by the calling thread.
     154The ``pthread_setspecific()`` function shall associate a thread-specific value
     155with a key obtained via a previous call to ``pthread_key_create()``.  Different
     156threads may bind different values to the same key. These values are typically
     157pointers to blocks of dynamically allocated memory that have been reserved for
     158use by the calling thread.
    142159
    143160**NOTES:**
    144161
    145 The effect of calling pthread_setspecific() with a key value not obtained
    146 from pthread_key_create() or after key has
    147 been deleted with pthread_key_delete() is undefined.
    148 
    149 pthread_setspecific() may be called from a thread-specific data
    150 destructor function. Calling pthread_setspecific() from a thread-specific
    151 data destructor routine may result either in lost storage (after at least
    152 PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop.
     162The effect of calling ``pthread_setspecific()`` with a key value not obtained
     163from ``pthread_key_create()`` or after key has been deleted with
     164``pthread_key_delete()`` is undefined.
     165
     166``pthread_setspecific()`` may be called from a thread-specific data destructor
     167function. Calling ``pthread_setspecific()`` from a thread-specific data
     168destructor routine may result either in lost storage (after at least
     169``PTHREAD_DESTRUCTOR_ITERATIONS`` attempts at destruction) or in an infinite
     170loop.
     171
     172.. _pthread_getspecific:
    153173
    154174pthread_getspecific - Get Thread Specific Key Value
     
    157177**CALLING SEQUENCE:**
    158178
    159 .. code:: c
    160 
    161     #include <pthread.h>
    162     void \*pthread_getspecific(
    163     pthread_key_t key
    164     );
    165 
    166 **STATUS CODES:**
    167 
    168 *NULL*
    169