Changeset e21f7d8 in rtems


Ignore:
Timestamp:
Sep 27, 1998, 4:00:18 PM (21 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
cb646cb9
Parents:
389c3e9
Message:

Documented the following routines: dup, dup2, close, read, write, and fcntl.f

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/io.t

    r389c3e9 re21f7d8  
    1111@section Introduction
    1212
    13 The
    14 input and output primitives manager is ...
     13The input and output primitives manager is ...
    1514
    1615The directives provided by the input and output primitives manager are:
    1716
    1817@itemize @bullet
    19 @item @code{pipe} -
    20 @item @code{dup} -
    21 @item @code{dup2} -
    22 @item @code{close} -
    23 @item @code{read} -
    24 @item @code{write} -
    25 @item @code{fcntl} -
    26 @item @code{lseek} -
    27 @item @code{fsynch} -
    28 @item @code{fdatasynch} -
    29 @item @code{aio_read} -
    30 @item @code{aio_write} -
    31 @item @code{lio_listio} -
    32 @item @code{aio_error} -
    33 @item @code{aio_return} -
    34 @item @code{aio_cancel} -
    35 @item @code{aio_suspend} -
    36 @item @code{aio_fsync} -
     18@item @code{pipe} - YYY
     19@item @code{dup} - Duplicates an open file descriptor
     20@item @code{dup2} - Duplicates an open file descriptor
     21@item @code{close} - Closes a file
     22@item @code{read} - Reads from a file
     23@item @code{write} - Writes to a file
     24@item @code{fcntl} - Manipulates an open file descriptor
     25@item @code{lseek} - XXX
     26@item @code{fsynch} - XXX
     27@item @code{fdatasynch} - XXX
     28@item @code{aio_read} - YYY
     29@item @code{aio_write} - YYY
     30@item @code{lio_listio} - YYY
     31@item @code{aio_error} - YYY
     32@item @code{aio_return} - YYY
     33@item @code{aio_cancel} - YYY
     34@item @code{aio_suspend} - YYY
     35@item @code{aio_fsync} - YYY
    3736@end itemize
    3837
     
    7675
    7776@page
    78 @subsection dup -
    79 
    80 @subheading CALLING SEQUENCE:
    81 
    82 @ifset is-C
    83 @example
    84 int dup(
    85 );
    86 @end example
    87 @end ifset
    88 
    89 @ifset is-Ada
    90 @end ifset
    91 
    92 @subheading STATUS CODES:
    93 
    94 @table @b
    95 @item E
    96 The
    97 
    98 @end table
    99 
    100 @subheading DESCRIPTION:
    101 
    102 @subheading NOTES:
    103 
    104 @page
    105 @subsection dup2 -
    106 
    107 @subheading CALLING SEQUENCE:
    108 
    109 @ifset is-C
    110 @example
    111 int dup2(
    112 );
    113 @end example
    114 @end ifset
    115 
    116 @ifset is-Ada
    117 @end ifset
    118 
    119 @subheading STATUS CODES:
    120 
    121 @table @b
    122 @item E
    123 The
    124 
    125 @end table
    126 
    127 @subheading DESCRIPTION:
    128 
    129 @subheading NOTES:
    130 
    131 @page
    132 @subsection close -
    133 
    134 @subheading CALLING SEQUENCE:
    135 
    136 @ifset is-C
    137 @example
    138 int close(
    139 );
    140 @end example
    141 @end ifset
    142 
    143 @ifset is-Ada
    144 @end ifset
    145 
    146 @subheading STATUS CODES:
    147 
    148 @table @b
    149 @item E
    150 The
    151 
    152 @end table
    153 
    154 @subheading DESCRIPTION:
    155 
    156 @subheading NOTES:
    157 
    158 @page
    159 @subsection read -
    160 
    161 @subheading CALLING SEQUENCE:
    162 
    163 @ifset is-C
    164 @example
    165 int read(
    166 );
    167 @end example
    168 @end ifset
    169 
    170 @ifset is-Ada
    171 @end ifset
    172 
    173 @subheading STATUS CODES:
    174 
    175 @table @b
    176 @item E
    177 The
    178 
    179 @end table
    180 
    181 @subheading DESCRIPTION:
    182 
    183 @subheading NOTES:
    184 
    185 @page
    186 @subsection write -
    187 
    188 @subheading CALLING SEQUENCE:
    189 
    190 @ifset is-C
    191 @example
    192 int write(
    193 );
    194 @end example
    195 @end ifset
    196 
    197 @ifset is-Ada
    198 @end ifset
    199 
    200 @subheading STATUS CODES:
    201 
    202 @table @b
    203 @item E
    204 The
    205 
    206 @end table
    207 
    208 @subheading DESCRIPTION:
    209 
    210 @subheading NOTES:
    211 
    212 @page
    213 @subsection fcntl -
    214 
    215 @subheading CALLING SEQUENCE:
    216 
    217 @ifset is-C
    218 @example
    219 int fcntl(
    220 );
    221 @end example
    222 @end ifset
    223 
    224 @ifset is-Ada
    225 @end ifset
    226 
    227 @subheading STATUS CODES:
    228 
    229 @table @b
    230 @item E
    231 The
     77@subsection dup - Duplicates an open file descriptor
     78
     79@subheading CALLING SEQUENCE:
     80
     81@ifset is-C
     82@example
     83#include <unistd.h>
     84
     85int dup(int fildes
     86);
     87@end example
     88@end ifset
     89
     90@ifset is-Ada
     91@end ifset
     92
     93@subheading STATUS CODES:
     94
     95@table @b
     96@item EBADF
     97Invalid file descriptor.
     98@item EINTR
     99Function was interrupted by a signal.
     100@item EMFILE
     101The process already has the maximum number of file descriptors open
     102and tried to open a new one.
     103@end table
     104
     105@subheading DESCRIPTION:
     106
     107The @code{dup} function returns the lowest numbered available file
     108descriptor.  This new desciptor refers to the same open file as the
     109original descriptor and shares any locks.
     110
     111@subheading NOTES: None
     112
     113@page
     114@subsection dup2 - Duplicates an open file descriptor
     115
     116@subheading CALLING SEQUENCE:
     117
     118@ifset is-C
     119@example
     120#include <unistd.h>
     121
     122int dup2(int fildes,
     123         int fildes2
     124);
     125@end example
     126@end ifset
     127
     128@ifset is-Ada
     129@end ifset
     130
     131@subheading STATUS CODES:
     132
     133@table @b
     134@item EBADF
     135Invalid file descriptor.
     136@item EINTR
     137Function was interrupted by a signal.
     138@item EMFILE
     139The process already has the maximum number of file descriptors open
     140and tried to open a new one.
     141@end table
     142
     143@subheading DESCRIPTION:
     144
     145@code{Dup2} creates a copy of the file descriptor @code{oldfd}.
     146
     147The old and new descriptors may be used interchangeably.  They share locks, file
     148position pointers and flags; for example, if the file position is modified by using
     149@code{lseek} on one of the descriptors, the position is also changed for the other.
     150
     151@subheading NOTES: None
     152
     153@page
     154@subsection close - Closes a file.
     155
     156@subheading CALLING SEQUENCE:
     157
     158@ifset is-C
     159@example
     160#include <unistd.h>
     161
     162int close(int fildes
     163);
     164@end example
     165@end ifset
     166
     167@ifset is-Ada
     168@end ifset
     169
     170@subheading STATUS CODES:
     171
     172@table @b
     173@item EBADF
     174Invalid file descriptor
     175@item EINTR
     176Function was interrupted by a signal.
     177@end table
     178
     179@subheading DESCRIPTION:
     180
     181The @code{close()} function deallocates the file descriptor named by
     182@code{fildes} and makes it available for reuse.  All outstanding
     183record locks owned by this process for the file are unlocked.
     184
     185@subheading NOTES:
     186
     187A signal can interrupt the @code{close()} function.  In that case,
     188@code{close()} returns -1 with @code{errno} set to EINTR.  The file
     189may or may not be closed.
     190
     191@page
     192@subsection read - Reads from a file.
     193
     194@subheading CALLING SEQUENCE:
     195
     196@ifset is-C
     197@example
     198#include <unistd.h>
     199
     200int read(int f         ildes,
     201         void         *buf,
     202         unsigned int  nbyte
     203);
     204@end example
     205@end ifset
     206
     207@ifset is-Ada
     208@end ifset
     209
     210@subheading STATUS CODES:
     211
     212@table @b
     213@item EAGAIN
     214The
     215@item EBADF
     216Invalid file descriptor
     217@item EINTR
     218Function was interrupted by a signal.
     219@item EIO
     220Input or output error
     221
     222@end table
     223
     224@subheading DESCRIPTION:
     225
     226The @code{read()} function reads @code{nbyte} bytes from the file
     227associated with @code{fildes} into the buffer pointed to by @code{buf}.
     228
     229The @code{read()} function returns the number of bytes actually read
     230and placed in the buffer. This will be less than @code{nbyte} if:
     231  - The number of bytes left in the file is less than @code{nbyte}
     232  - The @code{read()} request was interrupted by a signal
     233  - The file is a pipe or FIFO or special file with less than @code{nbytes}
     234    immediately available for reading.
     235
     236When attempting to read from any empty pipe or FIFO:
     237  - If no process has the pipe open for writing, zero is returned to
     238    indicate end-of-file.
     239  - If some process has the pipe open for writing and O_NONBLOCK is set,
     240    -1 is returned and @code{errno} is set to EAGAIN.
     241  - If some process has the pipe open for writing and O_NONBLOCK is clear,
     242    @code{read()} waits for some data to be written or the pipe to be closed.
     243
     244When attempting to read from a file other than a pipe or FIFO and no data
     245is available
     246  - If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN.
     247  - If O_NONBLOCK is clear, @code{read()} waits for some data to become
     248    available.
     249  - The O_NONBLOCK flag is ignored if data is available.
     250
     251@subheading NOTES: None
     252
     253@page
     254@subsection write - Writes to a file
     255
     256@subheading CALLING SEQUENCE:
     257
     258@ifset is-C
     259@example
     260#include <unistd.h>
     261
     262int write(int         fildes,
     263          const void *buf,
     264          unsigned int nbytes
     265);
     266@end example
     267@end ifset
     268
     269@ifset is-Ada
     270@end ifset
     271
     272@subheading STATUS CODES:
     273
     274@table @b
     275@item EAGAIN
     276The O_NONBLOCK flag is set for a file descriptor and the process
     277would be delayed in the I/O operation.
     278@item EBADF
     279Invalid file descriptor
     280@item EFBIG
     281The
     282@item EINTR
     283The function was interrupted by a signal.
     284@item EIO
     285Input or output error.
     286@item ENOSPC
     287No space left on disk.
     288@item EPIPE
     289Attempt to write to a pope or FIFO with no reader.
     290
     291@end table
     292
     293@subheading DESCRIPTION:
     294
     295The @code{write()} function writes @code{nbyte} from the array pointed
     296to by @code{buf} into the file associated with @code{fildes}.
     297
     298If @code{nybte} is zero and the file is a regular file, the @code{write()}
     299function returns zero and has no other effect.  If @code{nbyte} is zero
     300and the file is a special file, te results are not portable.
     301
     302The @code{write()} function returns the number of bytes written.  This
     303number will be less than @code{nbytes} if there is an error.  It will never
     304be greater than @code{nbytes}.
     305
     306@subheading NOTES: None
     307
     308@page
     309@subsection fcntl - Manipulates an open file descriptor
     310
     311@subheading CALLING SEQUENCE:
     312
     313@ifset is-C
     314@example
     315#include <sys/types.h>
     316#include <fcntl.h>
     317#include <unistd.h>
     318
     319int fcntl(int fildes,
     320          int    cmd
     321);
     322@end example
     323@end ifset
     324
     325@ifset is-Ada
     326@end ifset
     327
     328@subheading STATUS CODES:
     329
     330@table @b
     331@item EACCESS
     332Search permission is denied for a direcotry in a file's path
     333prefix.
     334@item EAGAIN
     335The O_NONBLOCK flag is set for a file descriptor and the process
     336would be delayed in the I/O operation.
     337@item EBADF
     338Invalid file descriptor
     339@item EDEADLK
     340An @code{fcntl} with function F_SETLKW would cause a deadlock.
     341@item EINTR
     342The functioin was interrupted by a signal.
     343@item EINVAL
     344Invalid argument
     345@item EMFILE
     346Too many file descriptor or in use by the process.
     347@item ENOLCK
     348No locks available
    232349
    233350@end table
     
    534651@subheading NOTES:
    535652
     653This routine is not currently supported by RTEMS but could be
     654in a future version.
Note: See TracChangeset for help on using the changeset viewer.