[c4dddee] | 1 | @c |
---|
[0660b4f8] | 2 | @c COPYRIGHT (c) 1988-1999. |
---|
[7479042] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
[c4dddee] | 5 | @c |
---|
[7479042] | 6 | @c $Id$ |
---|
[c4dddee] | 7 | @c |
---|
| 8 | |
---|
| 9 | @chapter Input and Output Primitives Manager |
---|
| 10 | |
---|
| 11 | @section Introduction |
---|
| 12 | |
---|
| 13 | The input and output primitives manager is ... |
---|
| 14 | |
---|
| 15 | The directives provided by the input and output primitives manager are: |
---|
| 16 | |
---|
| 17 | @itemize @bullet |
---|
[a7a33cc3] | 18 | @item @code{pipe} - Create an Inter-Process Channel |
---|
[c4dddee] | 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} - Reposition read/write file offset |
---|
[ed11cadf] | 26 | @item @code{fsync} - Synchronize file complete in-core state with that on disk |
---|
| 27 | @item @code{fdatasync} - Synchronize file in-core data with that on disk |
---|
[c4dddee] | 28 | @item @code{mount} - Mount a file system |
---|
[421fae4] | 29 | @item @code{unmount} - Unmount file systems |
---|
[a7a33cc3] | 30 | @item @code{aio_read} - Asynchronous Read |
---|
| 31 | @item @code{aio_write} - Asynchronous Write |
---|
| 32 | @item @code{lio_listio} - List Directed I/O |
---|
| 33 | @item @code{aio_error} - Retrieve Error Status of Asynchronous I/O Operation |
---|
| 34 | @item @code{aio_return} - Retrieve Return Status Asynchronous I/O Operation |
---|
| 35 | @item @code{aio_cancel} - Cancel Asynchronous I/O Request |
---|
| 36 | @item @code{aio_suspend} - Wait for Asynchronous I/O Request |
---|
| 37 | @item @code{aio_fsync} - Asynchronous File Synchronization |
---|
[c4dddee] | 38 | @end itemize |
---|
| 39 | |
---|
| 40 | @section Background |
---|
| 41 | |
---|
| 42 | There is currently no text in this section. |
---|
| 43 | |
---|
| 44 | @section Operations |
---|
| 45 | |
---|
| 46 | There is currently no text in this section. |
---|
| 47 | |
---|
| 48 | @section Directives |
---|
| 49 | |
---|
| 50 | This section details the input and output primitives manager's directives. |
---|
| 51 | A subsection is dedicated to each of this manager's directives |
---|
| 52 | and describes the calling sequence, related constants, usage, |
---|
| 53 | and status codes. |
---|
| 54 | |
---|
[7479042] | 55 | @c |
---|
| 56 | @c |
---|
| 57 | @c |
---|
[c4dddee] | 58 | @page |
---|
[a7a33cc3] | 59 | @subsection pipe - Create an Inter-Process Channel |
---|
[c4dddee] | 60 | |
---|
[7479042] | 61 | @findex pipe |
---|
| 62 | @cindex create an inter |
---|
| 63 | |
---|
[c4dddee] | 64 | @subheading CALLING SEQUENCE: |
---|
| 65 | |
---|
| 66 | @ifset is-C |
---|
| 67 | @example |
---|
| 68 | int pipe( |
---|
| 69 | ); |
---|
| 70 | @end example |
---|
| 71 | @end ifset |
---|
| 72 | |
---|
| 73 | @ifset is-Ada |
---|
| 74 | @end ifset |
---|
| 75 | |
---|
| 76 | @subheading STATUS CODES: |
---|
| 77 | |
---|
| 78 | @table @b |
---|
| 79 | @item E |
---|
| 80 | The |
---|
| 81 | |
---|
| 82 | @end table |
---|
| 83 | |
---|
| 84 | @subheading DESCRIPTION: |
---|
| 85 | |
---|
| 86 | @subheading NOTES: |
---|
| 87 | |
---|
[7479042] | 88 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 89 | in a future version. |
---|
| 90 | |
---|
[7479042] | 91 | @c |
---|
| 92 | @c |
---|
| 93 | @c |
---|
[c4dddee] | 94 | @page |
---|
| 95 | @subsection dup - Duplicates an open file descriptor |
---|
| 96 | |
---|
[7479042] | 97 | @findex dup |
---|
| 98 | @cindex duplicates an open file descriptor |
---|
| 99 | |
---|
[c4dddee] | 100 | @subheading CALLING SEQUENCE: |
---|
| 101 | |
---|
| 102 | @ifset is-C |
---|
| 103 | @example |
---|
| 104 | #include <unistd.h> |
---|
| 105 | |
---|
| 106 | int dup( |
---|
[2b9f1f5d] | 107 | int fildes |
---|
[c4dddee] | 108 | ); |
---|
| 109 | @end example |
---|
| 110 | @end ifset |
---|
| 111 | |
---|
| 112 | @ifset is-Ada |
---|
| 113 | @end ifset |
---|
| 114 | |
---|
| 115 | @subheading STATUS CODES: |
---|
| 116 | |
---|
| 117 | @table @b |
---|
| 118 | @item EBADF |
---|
| 119 | Invalid file descriptor. |
---|
| 120 | |
---|
| 121 | @item EINTR |
---|
| 122 | Function was interrupted by a signal. |
---|
| 123 | |
---|
| 124 | @item EMFILE |
---|
[7479042] | 125 | The process already has the maximum number of file descriptors open |
---|
[c4dddee] | 126 | and tried to open a new one. |
---|
| 127 | @end table |
---|
| 128 | |
---|
| 129 | @subheading DESCRIPTION: |
---|
| 130 | |
---|
[7479042] | 131 | The @code{dup} function returns the lowest numbered available file |
---|
| 132 | descriptor. This new desciptor refers to the same open file as the |
---|
[c4dddee] | 133 | original descriptor and shares any locks. |
---|
| 134 | |
---|
[7479042] | 135 | @subheading NOTES: |
---|
[c4dddee] | 136 | |
---|
| 137 | NONE |
---|
| 138 | |
---|
[7479042] | 139 | @c |
---|
| 140 | @c |
---|
| 141 | @c |
---|
[c4dddee] | 142 | @page |
---|
| 143 | @subsection dup2 - Duplicates an open file descriptor |
---|
| 144 | |
---|
[7479042] | 145 | @findex dup2 |
---|
| 146 | @cindex duplicates an open file descriptor |
---|
| 147 | |
---|
[c4dddee] | 148 | @subheading CALLING SEQUENCE: |
---|
| 149 | |
---|
| 150 | @ifset is-C |
---|
| 151 | @example |
---|
| 152 | #include <unistd.h> |
---|
| 153 | |
---|
| 154 | int dup2( |
---|
[2b9f1f5d] | 155 | int fildes, |
---|
| 156 | int fildes2 |
---|
[c4dddee] | 157 | ); |
---|
| 158 | @end example |
---|
| 159 | @end ifset |
---|
| 160 | |
---|
| 161 | @ifset is-Ada |
---|
| 162 | @end ifset |
---|
| 163 | |
---|
| 164 | @subheading STATUS CODES: |
---|
| 165 | |
---|
| 166 | @table @b |
---|
| 167 | @item EBADF |
---|
| 168 | Invalid file descriptor. |
---|
| 169 | |
---|
| 170 | @item EINTR |
---|
| 171 | Function was interrupted by a signal. |
---|
| 172 | |
---|
| 173 | @item EMFILE |
---|
[7479042] | 174 | The process already has the maximum number of file descriptors open |
---|
[c4dddee] | 175 | and tried to open a new one. |
---|
| 176 | @end table |
---|
| 177 | |
---|
| 178 | @subheading DESCRIPTION: |
---|
| 179 | |
---|
| 180 | @code{Dup2} creates a copy of the file descriptor @code{oldfd}. |
---|
| 181 | |
---|
[7479042] | 182 | The old and new descriptors may be used interchangeably. They share locks, file |
---|
[c4dddee] | 183 | position pointers and flags; for example, if the file position is modified by using |
---|
| 184 | @code{lseek} on one of the descriptors, the position is also changed for the other. |
---|
| 185 | |
---|
[7479042] | 186 | @subheading NOTES: |
---|
[c4dddee] | 187 | |
---|
| 188 | NONE |
---|
| 189 | |
---|
[7479042] | 190 | @c |
---|
| 191 | @c |
---|
| 192 | @c |
---|
[c4dddee] | 193 | @page |
---|
[7479042] | 194 | @subsection close - Closes a file. |
---|
| 195 | |
---|
| 196 | @findex close |
---|
| 197 | @cindex closes a file. |
---|
[c4dddee] | 198 | |
---|
| 199 | @subheading CALLING SEQUENCE: |
---|
| 200 | |
---|
| 201 | @ifset is-C |
---|
| 202 | @example |
---|
| 203 | #include <unistd.h> |
---|
| 204 | |
---|
| 205 | int close( |
---|
[2b9f1f5d] | 206 | int fildes |
---|
[c4dddee] | 207 | ); |
---|
| 208 | @end example |
---|
| 209 | @end ifset |
---|
| 210 | |
---|
| 211 | @ifset is-Ada |
---|
| 212 | @end ifset |
---|
| 213 | |
---|
| 214 | @subheading STATUS CODES: |
---|
| 215 | |
---|
| 216 | @table @b |
---|
| 217 | @item EBADF |
---|
| 218 | Invalid file descriptor |
---|
| 219 | |
---|
| 220 | @item EINTR |
---|
| 221 | Function was interrupted by a signal. |
---|
| 222 | @end table |
---|
| 223 | |
---|
| 224 | @subheading DESCRIPTION: |
---|
| 225 | |
---|
| 226 | The @code{close()} function deallocates the file descriptor named by |
---|
[7479042] | 227 | @code{fildes} and makes it available for reuse. All outstanding |
---|
[c4dddee] | 228 | record locks owned by this process for the file are unlocked. |
---|
| 229 | |
---|
| 230 | @subheading NOTES: |
---|
| 231 | |
---|
[7479042] | 232 | A signal can interrupt the @code{close()} function. In that case, |
---|
| 233 | @code{close()} returns -1 with @code{errno} set to EINTR. The file |
---|
[c4dddee] | 234 | may or may not be closed. |
---|
| 235 | |
---|
[7479042] | 236 | @c |
---|
| 237 | @c |
---|
| 238 | @c |
---|
[c4dddee] | 239 | @page |
---|
| 240 | @subsection read - Reads from a file. |
---|
| 241 | |
---|
[7479042] | 242 | @findex read |
---|
| 243 | @cindex reads from a file. |
---|
| 244 | |
---|
[c4dddee] | 245 | @subheading CALLING SEQUENCE: |
---|
| 246 | |
---|
| 247 | @ifset is-C |
---|
| 248 | @example |
---|
| 249 | #include <unistd.h> |
---|
| 250 | |
---|
| 251 | int read( |
---|
[d2bfbaf] | 252 | int fildes, |
---|
| 253 | void *buf, |
---|
| 254 | unsigned int nbyte |
---|
[c4dddee] | 255 | ); |
---|
| 256 | @end example |
---|
| 257 | @end ifset |
---|
| 258 | |
---|
| 259 | @ifset is-Ada |
---|
| 260 | @end ifset |
---|
| 261 | |
---|
| 262 | @subheading STATUS CODES: |
---|
| 263 | |
---|
| 264 | On error, this routine returns -1 and sets @code{errno} to one of |
---|
| 265 | the following: |
---|
[7479042] | 266 | |
---|
[c4dddee] | 267 | @table @b |
---|
| 268 | @item EAGAIN |
---|
| 269 | The O_NONBLOCK flag is set for a file descriptor and the process |
---|
| 270 | would be delayed in the I/O operation. |
---|
| 271 | |
---|
| 272 | @item EBADF |
---|
| 273 | Invalid file descriptor |
---|
| 274 | |
---|
| 275 | @item EINTR |
---|
| 276 | Function was interrupted by a signal. |
---|
| 277 | |
---|
| 278 | @item EIO |
---|
| 279 | Input or output error |
---|
| 280 | |
---|
| 281 | @end table |
---|
| 282 | |
---|
| 283 | @subheading DESCRIPTION: |
---|
| 284 | |
---|
[7479042] | 285 | The @code{read()} function reads @code{nbyte} bytes from the file |
---|
[c4dddee] | 286 | associated with @code{fildes} into the buffer pointed to by @code{buf}. |
---|
| 287 | |
---|
| 288 | The @code{read()} function returns the number of bytes actually read |
---|
| 289 | and placed in the buffer. This will be less than @code{nbyte} if: |
---|
| 290 | |
---|
| 291 | @itemize @bullet |
---|
| 292 | |
---|
| 293 | @item The number of bytes left in the file is less than @code{nbyte}. |
---|
| 294 | |
---|
| 295 | @item The @code{read()} request was interrupted by a signal. |
---|
| 296 | |
---|
| 297 | @item The file is a pipe or FIFO or special file with less than @code{nbytes} |
---|
| 298 | immediately available for reading. |
---|
| 299 | |
---|
| 300 | @end itemize |
---|
| 301 | |
---|
| 302 | When attempting to read from any empty pipe or FIFO: |
---|
| 303 | |
---|
| 304 | |
---|
| 305 | @itemize @bullet |
---|
| 306 | |
---|
[7479042] | 307 | @item If no process has the pipe open for writing, zero is returned to |
---|
[c4dddee] | 308 | indicate end-of-file. |
---|
| 309 | |
---|
| 310 | @item If some process has the pipe open for writing and O_NONBLOCK is set, |
---|
| 311 | -1 is returned and @code{errno} is set to EAGAIN. |
---|
| 312 | |
---|
| 313 | @item If some process has the pipe open for writing and O_NONBLOCK is clear, |
---|
| 314 | @code{read()} waits for some data to be written or the pipe to be closed. |
---|
| 315 | |
---|
| 316 | @end itemize |
---|
| 317 | |
---|
| 318 | |
---|
| 319 | When attempting to read from a file other than a pipe or FIFO and no data |
---|
| 320 | is available. |
---|
| 321 | |
---|
| 322 | @itemize @bullet |
---|
| 323 | |
---|
| 324 | @item If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN. |
---|
| 325 | |
---|
[7479042] | 326 | @item If O_NONBLOCK is clear, @code{read()} waits for some data to become |
---|
[c4dddee] | 327 | available. |
---|
| 328 | |
---|
| 329 | @item The O_NONBLOCK flag is ignored if data is available. |
---|
| 330 | |
---|
| 331 | @end itemize |
---|
| 332 | |
---|
| 333 | @subheading NOTES: |
---|
| 334 | |
---|
| 335 | NONE |
---|
| 336 | |
---|
[7479042] | 337 | @c |
---|
| 338 | @c |
---|
| 339 | @c |
---|
[c4dddee] | 340 | @page |
---|
| 341 | @subsection write - Writes to a file |
---|
| 342 | |
---|
[7479042] | 343 | @findex write |
---|
| 344 | @cindex writes to a file |
---|
| 345 | |
---|
[c4dddee] | 346 | @subheading CALLING SEQUENCE: |
---|
| 347 | |
---|
| 348 | @ifset is-C |
---|
| 349 | @example |
---|
| 350 | #include <unistd.h> |
---|
| 351 | |
---|
| 352 | int write( |
---|
[d2bfbaf] | 353 | int fildes, |
---|
| 354 | const void *buf, |
---|
| 355 | unsigned int nbytes |
---|
[c4dddee] | 356 | ); |
---|
| 357 | @end example |
---|
| 358 | @end ifset |
---|
| 359 | |
---|
| 360 | @ifset is-Ada |
---|
| 361 | @end ifset |
---|
| 362 | |
---|
| 363 | @subheading STATUS CODES: |
---|
| 364 | |
---|
| 365 | @table @b |
---|
| 366 | @item EAGAIN |
---|
| 367 | The O_NONBLOCK flag is set for a file descriptor and the process |
---|
| 368 | would be delayed in the I/O operation. |
---|
| 369 | |
---|
| 370 | @item EBADF |
---|
| 371 | Invalid file descriptor |
---|
| 372 | |
---|
| 373 | @item EFBIG |
---|
[7479042] | 374 | An attempt was made to write to a file that exceeds the maximum file |
---|
[c4dddee] | 375 | size |
---|
| 376 | |
---|
| 377 | @item EINTR |
---|
| 378 | The function was interrupted by a signal. |
---|
| 379 | |
---|
| 380 | @item EIO |
---|
| 381 | Input or output error. |
---|
| 382 | |
---|
| 383 | @item ENOSPC |
---|
| 384 | No space left on disk. |
---|
| 385 | |
---|
| 386 | @item EPIPE |
---|
| 387 | Attempt to write to a pope or FIFO with no reader. |
---|
| 388 | |
---|
| 389 | @end table |
---|
| 390 | |
---|
| 391 | @subheading DESCRIPTION: |
---|
| 392 | |
---|
| 393 | The @code{write()} function writes @code{nbyte} from the array pointed |
---|
| 394 | to by @code{buf} into the file associated with @code{fildes}. |
---|
| 395 | |
---|
| 396 | If @code{nybte} is zero and the file is a regular file, the @code{write()} |
---|
[7479042] | 397 | function returns zero and has no other effect. If @code{nbyte} is zero |
---|
[c4dddee] | 398 | and the file is a special file, te results are not portable. |
---|
| 399 | |
---|
[7479042] | 400 | The @code{write()} function returns the number of bytes written. This |
---|
| 401 | number will be less than @code{nbytes} if there is an error. It will never |
---|
[c4dddee] | 402 | be greater than @code{nbytes}. |
---|
| 403 | |
---|
[7479042] | 404 | @subheading NOTES: |
---|
[c4dddee] | 405 | |
---|
| 406 | NONE |
---|
| 407 | |
---|
[7479042] | 408 | @c |
---|
| 409 | @c |
---|
| 410 | @c |
---|
[c4dddee] | 411 | @page |
---|
| 412 | @subsection fcntl - Manipulates an open file descriptor |
---|
| 413 | |
---|
[7479042] | 414 | @findex fcntl |
---|
| 415 | @cindex manipulates an open file descriptor |
---|
| 416 | |
---|
[c4dddee] | 417 | @subheading CALLING SEQUENCE: |
---|
| 418 | |
---|
| 419 | @ifset is-C |
---|
| 420 | @example |
---|
| 421 | #include <sys/types.h> |
---|
| 422 | #include <fcntl.h> |
---|
| 423 | #include <unistd.h> |
---|
| 424 | |
---|
| 425 | int fcntl( |
---|
[2b9f1f5d] | 426 | int fildes, |
---|
| 427 | int cmd |
---|
[c4dddee] | 428 | ); |
---|
| 429 | @end example |
---|
| 430 | @end ifset |
---|
| 431 | |
---|
| 432 | @ifset is-Ada |
---|
| 433 | @end ifset |
---|
| 434 | |
---|
| 435 | @subheading STATUS CODES: |
---|
| 436 | |
---|
| 437 | @table @b |
---|
| 438 | @item EACCESS |
---|
| 439 | Search permission is denied for a direcotry in a file's path |
---|
| 440 | prefix. |
---|
| 441 | |
---|
| 442 | @item EAGAIN |
---|
| 443 | The O_NONBLOCK flag is set for a file descriptor and the process |
---|
| 444 | would be delayed in the I/O operation. |
---|
| 445 | |
---|
| 446 | @item EBADF |
---|
| 447 | Invalid file descriptor |
---|
| 448 | |
---|
| 449 | @item EDEADLK |
---|
| 450 | An @code{fcntl} with function F_SETLKW would cause a deadlock. |
---|
| 451 | |
---|
| 452 | @item EINTR |
---|
| 453 | The functioin was interrupted by a signal. |
---|
| 454 | |
---|
| 455 | @item EINVAL |
---|
| 456 | Invalid argument |
---|
| 457 | |
---|
| 458 | @item EMFILE |
---|
| 459 | Too many file descriptor or in use by the process. |
---|
| 460 | |
---|
| 461 | @item ENOLCK |
---|
| 462 | No locks available |
---|
| 463 | |
---|
| 464 | @end table |
---|
| 465 | |
---|
| 466 | @subheading DESCRIPTION: |
---|
| 467 | |
---|
| 468 | @code{fcntl()} performs one of various miscellaneous operations on |
---|
[7479042] | 469 | @code{fd}. The operation in question is determined by @code{cmd}: |
---|
[c4dddee] | 470 | |
---|
[7479042] | 471 | @table @b |
---|
[c4dddee] | 472 | |
---|
[7479042] | 473 | @item F_DUPFD |
---|
[c4dddee] | 474 | Makes @code{arg} be a copy of @code{fd}, closing @code{fd} first if necessary. |
---|
| 475 | |
---|
| 476 | The same functionality can be more easily achieved by using @code{dup2()}. |
---|
| 477 | |
---|
[7479042] | 478 | The old and new descriptors may be used interchangeably. They share locks, |
---|
| 479 | file position pointers and flags; for example, if the file position is |
---|
| 480 | modified by using @code{lseek()} on one of the descriptors, the position is |
---|
[c4dddee] | 481 | also changed for the other. |
---|
| 482 | |
---|
[7479042] | 483 | The two descriptors do not share the close-on-exec flag, however. The |
---|
| 484 | close-on-exec flag of the copy is off, meaning that it will be closed on |
---|
[c4dddee] | 485 | exec. |
---|
| 486 | |
---|
| 487 | On success, the new descriptor is returned. |
---|
| 488 | |
---|
[7479042] | 489 | @item F_GETFD |
---|
| 490 | Read the close-on-exec flag. If the low-order bit is 0, the file will |
---|
[c4dddee] | 491 | remain open across exec, otherwise it will be closed. |
---|
| 492 | |
---|
[7479042] | 493 | @item F_SETFD |
---|
| 494 | Set the close-on-exec flag to the value specified by @code{arg} (only the least |
---|
[c4dddee] | 495 | significant bit is used). |
---|
| 496 | |
---|
[7479042] | 497 | @item F_GETFL |
---|
[c4dddee] | 498 | Read the descriptor's flags (all flags (as set by open()) are returned). |
---|
| 499 | |
---|
[7479042] | 500 | @item F_SETFL |
---|
| 501 | Set the descriptor's flags to the value specified by @code{arg}. Only |
---|
[c4dddee] | 502 | @code{O_APPEND} and @code{O_NONBLOCK} may be set. |
---|
| 503 | |
---|
[7479042] | 504 | The flags are shared between copies (made with @code{dup()} etc.) of the same |
---|
[c4dddee] | 505 | file descriptor. |
---|
| 506 | |
---|
| 507 | The flags and their semantics are described in @code{open()}. |
---|
| 508 | |
---|
| 509 | @item F_GETLK, F_SETLK and F_SETLKW |
---|
[7479042] | 510 | Manage discretionary file locks. The third argument @code{arg} is a pointer to a |
---|
[c4dddee] | 511 | struct flock (that may be overwritten by this call). |
---|
| 512 | |
---|
| 513 | @item F_GETLK |
---|
| 514 | Return the flock structure that prevents us from obtaining the lock, or set the |
---|
| 515 | @code{l_type} field of the lock to @code{F_UNLCK} if there is no obstruction. |
---|
| 516 | |
---|
| 517 | @item F_SETLK |
---|
[7479042] | 518 | The lock is set (when @code{l_type} is @code{F_RDLCK} or @code{F_WRLCK}) or |
---|
| 519 | cleared (when it is @code{F_UNLCK}. If lock is held by someone else, this |
---|
[c4dddee] | 520 | call returns -1 and sets @code{errno} to EACCES or EAGAIN. |
---|
| 521 | |
---|
[7479042] | 522 | @item F_SETLKW |
---|
| 523 | Like @code{F_SETLK}, but instead of returning an error we wait for the lock to |
---|
[c4dddee] | 524 | be released. |
---|
| 525 | |
---|
[7479042] | 526 | @item F_GETOWN |
---|
[c4dddee] | 527 | Get the process ID (or process group) of the owner of a socket. |
---|
| 528 | |
---|
| 529 | Process groups are returned as negative values. |
---|
| 530 | |
---|
[7479042] | 531 | @item F_SETOWN |
---|
[c4dddee] | 532 | Set the process or process group that owns a socket. |
---|
| 533 | |
---|
| 534 | For these commands, ownership means receiving @code{SIGIO} or @code{SIGURG} |
---|
| 535 | signals. |
---|
| 536 | |
---|
[7479042] | 537 | Process groups are specified using negative values. |
---|
[c4dddee] | 538 | |
---|
| 539 | @end table |
---|
| 540 | |
---|
| 541 | @subheading NOTES: |
---|
| 542 | |
---|
| 543 | The errors returned by @code{dup2} are different from those returned by |
---|
| 544 | @code{F_DUPFD}. |
---|
| 545 | |
---|
[7479042] | 546 | @c |
---|
| 547 | @c |
---|
| 548 | @c |
---|
[c4dddee] | 549 | @page |
---|
| 550 | @subsection lseek - Reposition read/write file offset |
---|
| 551 | |
---|
[7479042] | 552 | @findex lseek |
---|
| 553 | @cindex reposition read/write file offset |
---|
| 554 | |
---|
[c4dddee] | 555 | @subheading CALLING SEQUENCE: |
---|
| 556 | |
---|
| 557 | @ifset is-C |
---|
| 558 | @example |
---|
| 559 | #include <sys/types.h> |
---|
| 560 | #include <unistd.h> |
---|
| 561 | |
---|
| 562 | int lseek( |
---|
[d2bfbaf] | 563 | int fildes, |
---|
| 564 | off_t offset, |
---|
| 565 | int whence |
---|
[c4dddee] | 566 | ); |
---|
| 567 | @end example |
---|
| 568 | @end ifset |
---|
| 569 | |
---|
| 570 | @ifset is-Ada |
---|
| 571 | @end ifset |
---|
| 572 | |
---|
| 573 | @subheading STATUS CODES: |
---|
| 574 | |
---|
| 575 | @table @b |
---|
| 576 | @item EBADF |
---|
| 577 | @code{Fildes} is not an open file descriptor. |
---|
| 578 | |
---|
| 579 | @item ESPIPE |
---|
[7479042] | 580 | @code{Fildes} is associated with a pipe, socket or FIFO. |
---|
[c4dddee] | 581 | |
---|
| 582 | @item EINVAL |
---|
[7479042] | 583 | @code{Whence} is not a proper value. |
---|
[c4dddee] | 584 | |
---|
| 585 | @end table |
---|
| 586 | |
---|
| 587 | @subheading DESCRIPTION: |
---|
| 588 | |
---|
| 589 | The @code{lseek} function repositions the offset of the file descriptor |
---|
[7479042] | 590 | @code{fildes} to the argument offset according to the directive whence. |
---|
[c4dddee] | 591 | The argument @code{fildes} must be an open file descriptor. @code{Lseek} |
---|
| 592 | repositions the file pointer fildes as follows: |
---|
| 593 | |
---|
| 594 | @itemize @bullet |
---|
| 595 | |
---|
[7479042] | 596 | @item |
---|
[c4dddee] | 597 | If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes. |
---|
| 598 | |
---|
[7479042] | 599 | @item |
---|
[c4dddee] | 600 | If @code{whence} is SEEK_CUR, the offset is set to its current location |
---|
| 601 | plus offset bytes. |
---|
| 602 | |
---|
[7479042] | 603 | @item |
---|
[c4dddee] | 604 | If @code{whence} is SEEK_END, the offset is set to the size of the |
---|
| 605 | file plus @code{offset} bytes. |
---|
| 606 | |
---|
| 607 | @end itemize |
---|
| 608 | |
---|
| 609 | The @code{lseek} function allows the file offset to be set beyond the end |
---|
| 610 | of the existing end-of-file of the file. If data is later written at this |
---|
| 611 | point, subsequent reads of the data in the gap return bytes of zeros |
---|
| 612 | (until data is actually written into the gap). |
---|
| 613 | |
---|
[7479042] | 614 | Some devices are incapable of seeking. The value of the pointer associated |
---|
[c4dddee] | 615 | with such a device is undefined. |
---|
| 616 | |
---|
[7479042] | 617 | @subheading NOTES: |
---|
[c4dddee] | 618 | |
---|
| 619 | NONE |
---|
| 620 | |
---|
[7479042] | 621 | @c |
---|
| 622 | @c |
---|
| 623 | @c |
---|
[c4dddee] | 624 | @page |
---|
[ed11cadf] | 625 | @subsection fsync - Synchronize file complete in-core state with that on disk |
---|
[c4dddee] | 626 | |
---|
[7479042] | 627 | @findex fsync |
---|
| 628 | @cindex synchronize file complete in |
---|
| 629 | |
---|
[c4dddee] | 630 | @subheading CALLING SEQUENCE: |
---|
| 631 | |
---|
| 632 | @ifset is-C |
---|
| 633 | @example |
---|
| 634 | int fsync( |
---|
[2b9f1f5d] | 635 | int fd |
---|
[c4dddee] | 636 | ); |
---|
| 637 | @end example |
---|
| 638 | @end ifset |
---|
| 639 | |
---|
| 640 | @ifset is-Ada |
---|
| 641 | @end ifset |
---|
| 642 | |
---|
| 643 | @subheading STATUS CODES: |
---|
| 644 | |
---|
[7479042] | 645 | On success, zero is returned. On error, -1 is returned, and @code{errno} |
---|
[c4dddee] | 646 | is set appropriately. |
---|
| 647 | |
---|
| 648 | @table @b |
---|
| 649 | @item EBADF |
---|
| 650 | @code{fd} is not a valid descriptor open for writing |
---|
| 651 | |
---|
| 652 | @item EINVAL |
---|
| 653 | @code{fd} is bound to a special file which does not support support synchronization |
---|
| 654 | |
---|
| 655 | @item EROFS |
---|
| 656 | @code{fd} is bound to a special file which does not support support synchronization |
---|
| 657 | |
---|
| 658 | @item EIO |
---|
| 659 | An error occurred during synchronization |
---|
| 660 | |
---|
| 661 | @end table |
---|
| 662 | |
---|
| 663 | @subheading DESCRIPTION: |
---|
| 664 | |
---|
| 665 | @code{fsync} copies all in-core parts of a file to disk. |
---|
| 666 | |
---|
| 667 | @subheading NOTES: |
---|
| 668 | |
---|
| 669 | NONE |
---|
| 670 | |
---|
[7479042] | 671 | @c |
---|
| 672 | @c |
---|
| 673 | @c |
---|
[c4dddee] | 674 | @page |
---|
[7479042] | 675 | @subsection fdatasync - Synchronize file in-core data with that on disk. |
---|
| 676 | |
---|
| 677 | @findex fdatasync |
---|
| 678 | @cindex synchronize file in |
---|
[c4dddee] | 679 | |
---|
| 680 | @subheading CALLING SEQUENCE: |
---|
| 681 | |
---|
| 682 | @ifset is-C |
---|
| 683 | @example |
---|
| 684 | int fdatasync( |
---|
[2b9f1f5d] | 685 | int fd |
---|
[c4dddee] | 686 | ); |
---|
| 687 | @end example |
---|
| 688 | @end ifset |
---|
| 689 | |
---|
| 690 | @ifset is-Ada |
---|
| 691 | @end ifset |
---|
| 692 | |
---|
| 693 | @subheading STATUS CODES: |
---|
| 694 | |
---|
[7479042] | 695 | On success, zero is returned. On error, -1 is returned, and @code{errno} is |
---|
[c4dddee] | 696 | set appropriately. |
---|
| 697 | |
---|
| 698 | @table @b |
---|
| 699 | @item EBADF |
---|
| 700 | @code{fd} is not a valid file descriptor open for writing. |
---|
| 701 | |
---|
| 702 | @item EINVAL |
---|
| 703 | @code{fd} is bound to a special file which does not support synchronization. |
---|
| 704 | |
---|
| 705 | @item EIO |
---|
| 706 | An error occurred during synchronization. |
---|
| 707 | |
---|
| 708 | @item EROFS |
---|
| 709 | @code{fd} is bound to a special file which dows not support synchronization. |
---|
| 710 | |
---|
| 711 | @end table |
---|
| 712 | |
---|
| 713 | @subheading DESCRIPTION: |
---|
| 714 | |
---|
| 715 | @code{fdatasync} flushes all data buffers of a file to disk (before the system call |
---|
[7479042] | 716 | returns). It resembles @code{fsync} but is not required to update the metadata such |
---|
[c4dddee] | 717 | as access time. |
---|
| 718 | |
---|
| 719 | Applications that access databases or log files often write a tiny data fragment |
---|
[7479042] | 720 | (e.g., one line in a log file) and then call @code{fsync} immediately in order to |
---|
| 721 | ensure that the written data is physically stored on the harddisk. Unfortunately, |
---|
| 722 | fsync will always initiate two write operations: one for the newly written data and |
---|
| 723 | another one in order to update the modification time stored in the inode. If the |
---|
| 724 | modification time is not a part of the transaction concept @code{fdatasync} can be |
---|
[c4dddee] | 725 | used to avoid unnecessary inode disk write operations. |
---|
| 726 | |
---|
| 727 | @subheading NOTES: |
---|
| 728 | |
---|
| 729 | NONE |
---|
| 730 | |
---|
[7479042] | 731 | @c |
---|
| 732 | @c |
---|
| 733 | @c |
---|
[c4dddee] | 734 | @page |
---|
| 735 | @subsection mount - Mount a file system |
---|
| 736 | |
---|
[7479042] | 737 | @findex mount |
---|
| 738 | @cindex mount a file system |
---|
| 739 | |
---|
[c4dddee] | 740 | @subheading CALLING SEQUENCE: |
---|
| 741 | |
---|
| 742 | @ifset is-C |
---|
| 743 | @example |
---|
[421fae4] | 744 | #include <libio.h> |
---|
[c4dddee] | 745 | |
---|
| 746 | int mount( |
---|
[421fae4] | 747 | rtems_filesystem_mount_table_entry_t **mt_entry, |
---|
| 748 | rtems_filesystem_operations_table *fs_ops, |
---|
| 749 | rtems_filesystem_options_t fsoptions, |
---|
| 750 | char *device, |
---|
| 751 | char *mount_point |
---|
[c4dddee] | 752 | ); |
---|
| 753 | @end example |
---|
| 754 | @end ifset |
---|
| 755 | |
---|
| 756 | @ifset is-Ada |
---|
| 757 | @end ifset |
---|
| 758 | |
---|
| 759 | @subheading STATUS CODES: |
---|
| 760 | |
---|
| 761 | @table @b |
---|
[421fae4] | 762 | @item EXXX |
---|
[7479042] | 763 | |
---|
[c4dddee] | 764 | @end table |
---|
| 765 | |
---|
| 766 | @subheading DESCRIPTION: |
---|
| 767 | |
---|
[421fae4] | 768 | The @code{mount} routines mounts the filesystem class |
---|
| 769 | which uses the filesystem operations specified by @code{fs_ops} |
---|
| 770 | and @code{fsoptions}. The filesystem is mounted at the directory |
---|
| 771 | @code{mount_point} and the mode of the mounted filesystem is |
---|
| 772 | specified by @code{fsoptions}. If this filesystem class requires |
---|
| 773 | a device, then the name of the device must be specified by @code{device}. |
---|
[c4dddee] | 774 | |
---|
[421fae4] | 775 | If this operation succeeds, the mount table entry for the mounted |
---|
| 776 | filesystem is returned in @code{mt_entry}. |
---|
[c4dddee] | 777 | |
---|
| 778 | @subheading NOTES: |
---|
| 779 | |
---|
| 780 | NONE |
---|
| 781 | |
---|
[7479042] | 782 | @c |
---|
| 783 | @c |
---|
| 784 | @c |
---|
[c4dddee] | 785 | @page |
---|
[421fae4] | 786 | @subsection unmount - Unmount file systems |
---|
[c4dddee] | 787 | |
---|
[421fae4] | 788 | @findex unmount |
---|
| 789 | @cindex unmount file systems |
---|
[7479042] | 790 | |
---|
[c4dddee] | 791 | @subheading CALLING SEQUENCE: |
---|
| 792 | |
---|
| 793 | @ifset is-C |
---|
| 794 | @example |
---|
[421fae4] | 795 | #include <libio.h> |
---|
[c4dddee] | 796 | |
---|
[421fae4] | 797 | int unmount( |
---|
| 798 | const char *mount_path |
---|
[c4dddee] | 799 | ); |
---|
| 800 | @end example |
---|
| 801 | @end ifset |
---|
| 802 | |
---|
| 803 | @ifset is-Ada |
---|
| 804 | @end ifset |
---|
| 805 | |
---|
| 806 | @subheading STATUS CODES: |
---|
| 807 | |
---|
| 808 | @table @b |
---|
[421fae4] | 809 | @item EXXX |
---|
[0eded82] | 810 | @end table |
---|
[c4dddee] | 811 | |
---|
| 812 | @subheading DESCRIPTION: |
---|
| 813 | |
---|
[421fae4] | 814 | The @code{unmount} routine removes the attachment of the filesystem specified |
---|
| 815 | by @code{mount_path}. |
---|
[c4dddee] | 816 | |
---|
[7479042] | 817 | @subheading NOTES: |
---|
[c4dddee] | 818 | |
---|
| 819 | NONE |
---|
| 820 | |
---|
[7479042] | 821 | @c |
---|
| 822 | @c |
---|
| 823 | @c |
---|
[c4dddee] | 824 | @page |
---|
[a7a33cc3] | 825 | @subsection aio_read - Asynchronous Read |
---|
[c4dddee] | 826 | |
---|
[7479042] | 827 | @findex aio_read |
---|
| 828 | @cindex asynchronous read |
---|
| 829 | |
---|
[c4dddee] | 830 | @subheading CALLING SEQUENCE: |
---|
| 831 | |
---|
| 832 | @ifset is-C |
---|
| 833 | @example |
---|
| 834 | int aio_read( |
---|
| 835 | ); |
---|
| 836 | @end example |
---|
| 837 | @end ifset |
---|
| 838 | |
---|
| 839 | @ifset is-Ada |
---|
| 840 | @end ifset |
---|
| 841 | |
---|
| 842 | @subheading STATUS CODES: |
---|
| 843 | |
---|
| 844 | @table @b |
---|
| 845 | @item E |
---|
| 846 | The |
---|
| 847 | |
---|
| 848 | @end table |
---|
| 849 | |
---|
| 850 | @subheading DESCRIPTION: |
---|
| 851 | |
---|
| 852 | @subheading NOTES: |
---|
| 853 | |
---|
[7479042] | 854 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 855 | in a future version. |
---|
| 856 | |
---|
[7479042] | 857 | @c |
---|
| 858 | @c |
---|
| 859 | @c |
---|
[c4dddee] | 860 | @page |
---|
[a7a33cc3] | 861 | @subsection aio_write - Asynchronous Write |
---|
[c4dddee] | 862 | |
---|
[7479042] | 863 | @findex aio_write |
---|
| 864 | @cindex asynchronous write |
---|
| 865 | |
---|
[c4dddee] | 866 | @subheading CALLING SEQUENCE: |
---|
| 867 | |
---|
| 868 | @ifset is-C |
---|
| 869 | @example |
---|
| 870 | int aio_write( |
---|
| 871 | ); |
---|
| 872 | @end example |
---|
| 873 | @end ifset |
---|
| 874 | |
---|
| 875 | @ifset is-Ada |
---|
| 876 | @end ifset |
---|
| 877 | |
---|
| 878 | @subheading STATUS CODES: |
---|
| 879 | |
---|
| 880 | @table @b |
---|
| 881 | @item E |
---|
| 882 | The |
---|
| 883 | |
---|
| 884 | @end table |
---|
| 885 | |
---|
| 886 | @subheading DESCRIPTION: |
---|
| 887 | |
---|
| 888 | @subheading NOTES: |
---|
| 889 | |
---|
[7479042] | 890 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 891 | in a future version. |
---|
| 892 | |
---|
[7479042] | 893 | @c |
---|
| 894 | @c |
---|
| 895 | @c |
---|
[c4dddee] | 896 | @page |
---|
[a7a33cc3] | 897 | @subsection lio_listio - List Directed I/O |
---|
[c4dddee] | 898 | |
---|
[7479042] | 899 | @findex lio_listio |
---|
| 900 | @cindex list directed i/o |
---|
| 901 | |
---|
[c4dddee] | 902 | @subheading CALLING SEQUENCE: |
---|
| 903 | |
---|
| 904 | @ifset is-C |
---|
| 905 | @example |
---|
| 906 | int lio_listio( |
---|
| 907 | ); |
---|
| 908 | @end example |
---|
| 909 | @end ifset |
---|
| 910 | |
---|
| 911 | @ifset is-Ada |
---|
| 912 | @end ifset |
---|
| 913 | |
---|
| 914 | @subheading STATUS CODES: |
---|
| 915 | |
---|
| 916 | @table @b |
---|
| 917 | @item E |
---|
| 918 | The |
---|
| 919 | |
---|
| 920 | @end table |
---|
| 921 | |
---|
| 922 | @subheading DESCRIPTION: |
---|
| 923 | |
---|
| 924 | @subheading NOTES: |
---|
| 925 | |
---|
[7479042] | 926 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 927 | in a future version. |
---|
| 928 | |
---|
[7479042] | 929 | @c |
---|
| 930 | @c |
---|
| 931 | @c |
---|
[c4dddee] | 932 | @page |
---|
[a7a33cc3] | 933 | @subsection aio_error - Retrieve Error Status of Asynchronous I/O Operation |
---|
[c4dddee] | 934 | |
---|
[7479042] | 935 | @findex aio_error |
---|
| 936 | @cindex retrieve error status of asynchronous i/o operation |
---|
| 937 | |
---|
[c4dddee] | 938 | @subheading CALLING SEQUENCE: |
---|
| 939 | |
---|
| 940 | @ifset is-C |
---|
| 941 | @example |
---|
| 942 | int aio_error( |
---|
| 943 | ); |
---|
| 944 | @end example |
---|
| 945 | @end ifset |
---|
| 946 | |
---|
| 947 | @ifset is-Ada |
---|
| 948 | @end ifset |
---|
| 949 | |
---|
| 950 | @subheading STATUS CODES: |
---|
| 951 | |
---|
| 952 | @table @b |
---|
| 953 | @item E |
---|
| 954 | The |
---|
| 955 | |
---|
| 956 | @end table |
---|
| 957 | |
---|
| 958 | @subheading DESCRIPTION: |
---|
| 959 | |
---|
| 960 | @subheading NOTES: |
---|
| 961 | |
---|
[7479042] | 962 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 963 | in a future version. |
---|
| 964 | |
---|
[7479042] | 965 | @c |
---|
| 966 | @c |
---|
| 967 | @c |
---|
[c4dddee] | 968 | @page |
---|
[a7a33cc3] | 969 | @subsection aio_return - Retrieve Return Status Asynchronous I/O Operation |
---|
[c4dddee] | 970 | |
---|
[7479042] | 971 | @findex aio_return |
---|
| 972 | @cindex retrieve return status asynchronous i/o operation |
---|
| 973 | |
---|
[c4dddee] | 974 | @subheading CALLING SEQUENCE: |
---|
| 975 | |
---|
| 976 | @ifset is-C |
---|
| 977 | @example |
---|
| 978 | int aio_return( |
---|
| 979 | ); |
---|
| 980 | @end example |
---|
| 981 | @end ifset |
---|
| 982 | |
---|
| 983 | @ifset is-Ada |
---|
| 984 | @end ifset |
---|
| 985 | |
---|
| 986 | @subheading STATUS CODES: |
---|
| 987 | |
---|
| 988 | @table @b |
---|
| 989 | @item E |
---|
| 990 | The |
---|
| 991 | |
---|
| 992 | @end table |
---|
| 993 | |
---|
| 994 | @subheading DESCRIPTION: |
---|
| 995 | |
---|
| 996 | @subheading NOTES: |
---|
| 997 | |
---|
[7479042] | 998 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 999 | in a future version. |
---|
| 1000 | |
---|
[7479042] | 1001 | @c |
---|
| 1002 | @c |
---|
| 1003 | @c |
---|
[c4dddee] | 1004 | @page |
---|
[a7a33cc3] | 1005 | @subsection aio_cancel - Cancel Asynchronous I/O Request |
---|
[c4dddee] | 1006 | |
---|
[7479042] | 1007 | @findex aio_cancel |
---|
| 1008 | @cindex cancel asynchronous i/o request |
---|
| 1009 | |
---|
[c4dddee] | 1010 | @subheading CALLING SEQUENCE: |
---|
| 1011 | |
---|
| 1012 | @ifset is-C |
---|
| 1013 | @example |
---|
| 1014 | int aio_cancel( |
---|
| 1015 | ); |
---|
| 1016 | @end example |
---|
| 1017 | @end ifset |
---|
| 1018 | |
---|
| 1019 | @ifset is-Ada |
---|
| 1020 | @end ifset |
---|
| 1021 | |
---|
| 1022 | @subheading STATUS CODES: |
---|
| 1023 | |
---|
| 1024 | @table @b |
---|
| 1025 | @item E |
---|
| 1026 | The |
---|
| 1027 | |
---|
| 1028 | @end table |
---|
| 1029 | |
---|
| 1030 | @subheading DESCRIPTION: |
---|
| 1031 | |
---|
| 1032 | @subheading NOTES: |
---|
| 1033 | |
---|
[7479042] | 1034 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 1035 | in a future version. |
---|
| 1036 | |
---|
[7479042] | 1037 | @c |
---|
| 1038 | @c |
---|
| 1039 | @c |
---|
[c4dddee] | 1040 | @page |
---|
[a7a33cc3] | 1041 | @subsection aio_suspend - Wait for Asynchronous I/O Request |
---|
[c4dddee] | 1042 | |
---|
[7479042] | 1043 | @findex aio_suspend |
---|
| 1044 | @cindex wait for asynchronous i/o request |
---|
| 1045 | |
---|
[c4dddee] | 1046 | @subheading CALLING SEQUENCE: |
---|
| 1047 | |
---|
| 1048 | @ifset is-C |
---|
| 1049 | @example |
---|
| 1050 | int aio_suspend( |
---|
| 1051 | ); |
---|
| 1052 | @end example |
---|
| 1053 | @end ifset |
---|
| 1054 | |
---|
| 1055 | @ifset is-Ada |
---|
| 1056 | @end ifset |
---|
| 1057 | |
---|
| 1058 | @subheading STATUS CODES: |
---|
| 1059 | |
---|
| 1060 | @table @b |
---|
| 1061 | @item E |
---|
| 1062 | The |
---|
| 1063 | |
---|
| 1064 | @end table |
---|
| 1065 | |
---|
| 1066 | @subheading DESCRIPTION: |
---|
| 1067 | |
---|
| 1068 | @subheading NOTES: |
---|
| 1069 | |
---|
[7479042] | 1070 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 1071 | in a future version. |
---|
| 1072 | |
---|
[7479042] | 1073 | @c |
---|
| 1074 | @c |
---|
| 1075 | @c |
---|
[c4dddee] | 1076 | @page |
---|
[a7a33cc3] | 1077 | @subsection aio_fsync - Asynchronous File Synchronization |
---|
[c4dddee] | 1078 | |
---|
[7479042] | 1079 | @findex aio_fsync |
---|
| 1080 | @cindex asynchronous file synchronization |
---|
| 1081 | |
---|
[c4dddee] | 1082 | @subheading CALLING SEQUENCE: |
---|
| 1083 | |
---|
| 1084 | @ifset is-C |
---|
| 1085 | @example |
---|
| 1086 | int aio_fsync( |
---|
| 1087 | ); |
---|
| 1088 | @end example |
---|
| 1089 | @end ifset |
---|
| 1090 | |
---|
| 1091 | @ifset is-Ada |
---|
| 1092 | @end ifset |
---|
| 1093 | |
---|
| 1094 | @subheading STATUS CODES: |
---|
| 1095 | |
---|
| 1096 | @table @b |
---|
| 1097 | @item E |
---|
| 1098 | The |
---|
| 1099 | |
---|
| 1100 | @end table |
---|
| 1101 | |
---|
| 1102 | @subheading DESCRIPTION: |
---|
| 1103 | |
---|
| 1104 | @subheading NOTES: |
---|
| 1105 | |
---|
[7479042] | 1106 | This routine is not currently supported by RTEMS but could be |
---|
[c4dddee] | 1107 | in a future version. |
---|