Changeset 80189ac2 in rtems
- Timestamp:
- 09/29/98 21:51:52 (24 years ago)
- Branches:
- 4.10, 4.11, 4.8, 4.9, 5, master
- Children:
- 6e62b72e
- Parents:
- f1ccfde
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
doc/new_chapters/io.t
rf1ccfde r80189ac2 24 24 @item @code{fcntl} - Manipulates an open file descriptor 25 25 @item @code{lseek} - Reposition read/write file offset 26 @item @code{fsync h} - XXX27 @item @code{fdatasync h} - XXX26 @item @code{fsync} - XXX 27 @item @code{fdatasync} - XXX 28 28 @item @code{mount} - Mount a file system 29 29 @item @code{umount} - Unmount file systems … … 40 40 @section Background 41 41 42 There is currently no text in this section. 43 42 44 @section Operations 45 46 There is currently no text in this section. 43 47 44 48 @section Directives … … 101 105 @item EBADF 102 106 Invalid file descriptor. 107 103 108 @item EINTR 104 109 Function was interrupted by a signal. 110 105 111 @item EMFILE 106 112 The process already has the maximum number of file descriptors open … … 114 120 original descriptor and shares any locks. 115 121 116 @subheading NOTES: None 122 @subheading NOTES: 123 124 NONE 117 125 118 126 @page … … 125 133 #include <unistd.h> 126 134 127 int dup2(int fildes, 128 int fildes2 135 int dup2( 136 int fildes, 137 int fildes2 129 138 ); 130 139 @end example … … 139 148 @item EBADF 140 149 Invalid file descriptor. 150 141 151 @item EINTR 142 152 Function was interrupted by a signal. 153 143 154 @item EMFILE 144 155 The process already has the maximum number of file descriptors open … … 154 165 @code{lseek} on one of the descriptors, the position is also changed for the other. 155 166 156 @subheading NOTES: None 167 @subheading NOTES: 168 169 NONE 157 170 158 171 @page … … 178 191 @item EBADF 179 192 Invalid file descriptor 193 180 194 @item EINTR 181 195 Function was interrupted by a signal. … … 203 217 #include <unistd.h> 204 218 205 int read(int f ildes, 206 void *buf, 207 unsigned int nbyte 208 ); 209 @end example 210 @end ifset 211 212 @ifset is-Ada 213 @end ifset 214 215 @subheading STATUS CODES: 216 219 int read( 220 int fildes, 221 void *buf, 222 unsigned int nbyte 223 ); 224 @end example 225 @end ifset 226 227 @ifset is-Ada 228 @end ifset 229 230 @subheading STATUS CODES: 231 232 On error, this routine returns -1 and sets @code{errno} to one of 233 the following: 234 217 235 @table @b 218 236 @item EAGAIN 219 237 The 238 220 239 @item EBADF 221 240 Invalid file descriptor 241 222 242 @item EINTR 223 243 Function was interrupted by a signal. 244 224 245 @item EIO 225 246 Input or output error … … 234 255 The @code{read()} function returns the number of bytes actually read 235 256 and placed in the buffer. This will be less than @code{nbyte} if: 236 - The number of bytes left in the file is less than @code{nbyte} 237 - The @code{read()} request was interrupted by a signal 238 - The file is a pipe or FIFO or special file with less than @code{nbytes} 239 immediately available for reading. 257 258 @itemize @bullet 259 260 @item The number of bytes left in the file is less than @code{nbyte}. 261 262 @item The @code{read()} request was interrupted by a signal. 263 264 @item The file is a pipe or FIFO or special file with less than @code{nbytes} 265 immediately available for reading. 266 267 @end itemize 240 268 241 269 When attempting to read from any empty pipe or FIFO: 242 - If no process has the pipe open for writing, zero is returned to 243 indicate end-of-file. 244 - If some process has the pipe open for writing and O_NONBLOCK is set, 245 -1 is returned and @code{errno} is set to EAGAIN. 246 - If some process has the pipe open for writing and O_NONBLOCK is clear, 247 @code{read()} waits for some data to be written or the pipe to be closed. 270 271 272 @itemize @bullet 273 274 @item If no process has the pipe open for writing, zero is returned to 275 indicate end-of-file. 276 277 @item If some process has the pipe open for writing and O_NONBLOCK is set, 278 -1 is returned and @code{errno} is set to EAGAIN. 279 280 @item If some process has the pipe open for writing and O_NONBLOCK is clear, 281 @code{read()} waits for some data to be written or the pipe to be closed. 282 283 @end itemize 284 248 285 249 286 When attempting to read from a file other than a pipe or FIFO and no data 250 is available 251 - If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN. 252 - If O_NONBLOCK is clear, @code{read()} waits for some data to become 253 available. 254 - The O_NONBLOCK flag is ignored if data is available. 255 256 @subheading NOTES: None 287 is available. 288 289 @itemize @bullet 290 291 @item If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN. 292 293 @item If O_NONBLOCK is clear, @code{read()} waits for some data to become 294 available. 295 296 @item The O_NONBLOCK flag is ignored if data is available. 297 298 @end itemize 299 300 @subheading NOTES: 301 302 NONE 257 303 258 304 @page … … 281 327 The O_NONBLOCK flag is set for a file descriptor and the process 282 328 would be delayed in the I/O operation. 329 283 330 @item EBADF 284 331 Invalid file descriptor 332 285 333 @item EFBIG 286 334 The 335 287 336 @item EINTR 288 337 The function was interrupted by a signal. 338 289 339 @item EIO 290 340 Input or output error. 341 291 342 @item ENOSPC 292 343 No space left on disk. 344 293 345 @item EPIPE 294 346 Attempt to write to a pope or FIFO with no reader. … … 309 361 be greater than @code{nbytes}. 310 362 311 @subheading NOTES: None 363 @subheading NOTES: 364 365 NONE 312 366 313 367 @page … … 322 376 #include <unistd.h> 323 377 324 int fcntl(int fildes, 325 int cmd 378 int fcntl( 379 int fildes, 380 int cmd 326 381 ); 327 382 @end example … … 337 392 Search permission is denied for a direcotry in a file's path 338 393 prefix. 394 339 395 @item EAGAIN 340 396 The O_NONBLOCK flag is set for a file descriptor and the process 341 397 would be delayed in the I/O operation. 398 342 399 @item EBADF 343 400 Invalid file descriptor 401 344 402 @item EDEADLK 345 403 An @code{fcntl} with function F_SETLKW would cause a deadlock. 404 346 405 @item EINTR 347 406 The functioin was interrupted by a signal. 407 348 408 @item EINVAL 349 409 Invalid argument 410 350 411 @item EMFILE 351 412 Too many file descriptor or in use by the process. 413 352 414 @item ENOLCK 353 415 No locks available … … 357 419 @subheading DESCRIPTION: 358 420 359 @subheading NOTES: 421 @code{fcntl()} performs one of various miscellaneous operations on 422 @code{fd}. The operation in question is determined by @code{cmd}: 423 424 @table @b 425 426 @item F_DUPFD 427 Makes @code{arg} be a copy of @code{fd}, closing @code{fd} first if necessary. 428 429 The same functionality can be more easily achieved by using @code{dup2()}. 430 431 The old and new descriptors may be used interchangeably. They share locks, 432 file position pointers and flags; for example, if the file position is 433 modified by using @code{lseek()} on one of the descriptors, the position is 434 also changed for the other. 435 436 The two descriptors do not share the close-on-exec flag, however. The 437 close-on-exec flag of the copy is off, meaning that it will be closed on 438 exec. 439 440 On success, the new descriptor is returned. 441 442 @item F_GETFD 443 Read the close-on-exec flag. If the low-order bit is 0, the file will 444 remain open across exec, otherwise it will be closed. 445 446 @item F_SETFD 447 Set the close-on-exec flag to the value specified by @code{arg} (only the least 448 significant bit is used). 449 450 @item F_GETFL 451 Read the descriptor's flags (all flags (as set by open()) are returned). 452 453 @item F_SETFL 454 Set the descriptor's flags to the value specified by @code{arg}. Only 455 @code{O_APPEND} and @code{O_NONBLOCK} may be set. 456 457 The flags are shared between copies (made with @code{dup()} etc.) of the same 458 file descriptor. 459 460 The flags and their semantics are described in @code{open()}. 461 462 @item F_GETLK, F_SETLK and F_SETLKW 463 Manage discretionary file locks. The third argument @code{arg} is a pointer to a 464 struct flock (that may be overwritten by this call). 465 466 @item F_GETLK 467 Return the flock structure that prevents us from obtaining the lock, or set the 468 @code{l_type} field of the lock to @code{F_UNLCK} if there is no obstruction. 469 470 @item F_SETLK 471 The lock is set (when @code{l_type} is @code{F_RDLCK} or @code{F_WRLCK}) or 472 cleared (when it is @code{F_UNLCK}. If lock is held by someone else, this 473 call returns -1 and sets @code{errno} to EACCES or EAGAIN. 474 475 @item F_SETLKW 476 Like @code{F_SETLK}, but instead of returning an error we wait for the lock to 477 be released. 478 479 @item F_GETOWN 480 Get the process ID (or process group) of the owner of a socket. 481 482 Process groups are returned as negative values. 483 484 @item F_SETOWN 485 Set the process or process group that owns a socket. 486 487 For these commands, ownership means receiving @code{SIGIO} or @code{SIGURG} 488 signals. 489 490 Process groups are specified using negative values. 491 492 @end table 493 494 @subheading NOTES: 495 496 The errors returned by @code{dup2} are different from those returned by 497 @code{F_DUPFD}. 360 498 361 499 @page … … 366 504 @ifset is-C 367 505 @example 506 #include <sys/types.h> 507 #include <unistd.h> 508 368 509 int lseek( 369 510 int fildes, … … 398 539 repositions the file pointer fildes as follows: 399 540 400 If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes. 401 402 If @code{whence} is SEEK_CUR, the offset is set to its current location 403 plus offset bytes. 404 405 If @cdoe{whence} is SEEK_END, the offset is set to the size of the 406 file plus @cdoe{offset} bytes. 407 408 The @cdoe{lseek} function allows the file offset to be set beyond the end 541 @itemize @bullet 542 543 @item 544 If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes. 545 546 @item 547 If @code{whence} is SEEK_CUR, the offset is set to its current location 548 plus offset bytes. 549 550 @item 551 If @code{whence} is SEEK_END, the offset is set to the size of the 552 file plus @code{offset} bytes. 553 554 @end itemize 555 556 The @code{lseek} function allows the file offset to be set beyond the end 409 557 of the existing end-of-file of the file. If data is later written at this 410 558 point, subsequent reads of the data in the gap return bytes of zeros … … 414 562 ciated with such a device is undefined. 415 563 416 @subheading NOTES: None 417 418 @page 419 @subsection fsynch - 420 421 @subheading CALLING SEQUENCE: 422 423 @ifset is-C 424 @example 425 int fsynch( 564 @subheading NOTES: 565 566 NONE 567 568 @page 569 @subsection fsync - 570 571 @subheading CALLING SEQUENCE: 572 573 @ifset is-C 574 @example 575 int fsync( 426 576 ); 427 577 @end example … … 444 594 445 595 @page 446 @subsection fdatasync h-447 448 @subheading CALLING SEQUENCE: 449 450 @ifset is-C 451 @example 452 int fdatasync h(596 @subsection fdatasync - 597 598 @subheading CALLING SEQUENCE: 599 600 @ifset is-C 601 @example 602 int fdatasync( 453 603 ); 454 604 @end example … … 500 650 501 651 @item ENODEV 652 @code{filesystemtype} not configured in the kernel. 653 654 @item ENOTBLK 655 @code{specialfile} is not a block device (if a device was required). 656 657 @item EBUSY 658 @code{specialfile} is already mounted. Or, it cannot be remounted 659 read-only, because it still holds files open for writing. Or, it 660 cannot be mounted on @code{dir} because @code{dir} is still busy 661 (it is the working directory of some task, the mount point of another 662 device, has open files, etc.). 663 664 @item EINVAL 665 @code{specialfile} had an invalid superblock. Or, a remount was 666 attempted, while @code{specialfile} was not already mounted on @code{dir}. 667 Or, an umount was attempted, while @code{dir} was not a mount point. 668 669 @item EFAULT 670 One of the pointer arguments points outside the user address space. 671 672 @item ENOMEM 673 The kernel could not allocate a free page to copy filenames or data into. 674 675 @item ENAMETOOLONG 676 A pathname was longer than MAXPATHLEN. 677 678 @item ENOTDIR 679 A pathname was empty or had a nonexistent component. 680 681 @item EACCES 682 A component of a path was not searchable. Or, mounting a read-only 683 filesystem was attempted without giving the MS_RDONLY flag. Or, the 684 block device @code{specialfile} is located on a filesystem mounted with 685 the MS_NODEV option. 686 687 @item ENXIO 688 The major number of the block device @code{specialfile} is out of 689 range. 690 691 @item EMFILE 692 (In case no block device is required:) Table of dummy devices is full. 693 694 @end table 695 696 @subheading DESCRIPTION: 697 698 @code{Mount} attaches the filesystem specified by @code{specialfile} 699 (which is often a device name) to the directory specified by @code{dir}. 700 701 Only the super-user may mount filesystems. 702 703 The @code{filesystemtype} argument may take one of the values listed in 704 /proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs", 705 "iso9660" etc.). 706 707 The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits, 708 and various mount flags in the low order 16 bits. If the magic number is 709 absent, then the last two arguments are not used. 710 711 The @code{data} argument is interpreted by the different file systems. 712 713 @subheading NOTES: 714 715 NONE 716 717 @page 718 @subsection umount - Umount file systems 719 720 @subheading CALLING SEQUENCE: 721 722 @ifset is-C 723 @example 724 #include <sys/mount.h> 725 #include <linux/fs.h> 726 727 int umount( 728 const char *specialfile 729 ); 730 @end example 731 @end ifset 732 733 @ifset is-Ada 734 @end ifset 735 736 @subheading STATUS CODES: 737 738 @table @b 739 @item EPERM 740 The user is not the super-user. 741 742 @item ENODEV 502 743 @code{Filesystemtype} not configured in the kernel. 503 744 … … 513 754 514 755 @item EINVAL 515 @code{ Specialfilehad an invalid superblock. Or, a remount was756 @code{specialfile} had an invalid superblock. Or, a remount was 516 757 attempted, while @code{specialfile} was not already mounted on @code{dir}. 517 758 Or, an umount was attempted, while @code{dir} was not a mount point. … … 532 773 A component of a path was not searchable. Or, mounting a read-only 533 774 filesystem was attempted without giving the MS_RDONLY flag. Or, the 534 block device Specialfileis located on a filesystem mounted with775 block device @code{specialfile} is located on a filesystem mounted with 535 776 the MS_NODEV option. 536 777 … … 541 782 @item EMFILE 542 783 (In case no block device is required:) Table of dummy devices is full. 543 544 @end table545 546 @subheading DESCRIPTION:547 548 @code{Mount} attaches the filesystem specified by @code{specialfile}549 (which is often a device name) to the directory specified by @code{dir}.550 551 Only the super-user may mount filesystems.552 553 The @code{filesystemtype} argument may take one of the values listed in554 /proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs",555 "iso9660" etc.).556 557 The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits,558 and various mount flags in the low order 16 bits. If the magic number is559 absent, then the last two arguments are not used.560 561 The @code{data} argument is interpreted by the different file systems.562 563 @subheading NOTES: None564 565 @page566 @subsection umount - Umount file systems567 568 @subheading CALLING SEQUENCE:569 570 @ifset is-C571 @example572 #include <sys/mount.h>573 #include <linux/fs.h>574 575 int umount(576 const char *specialfile577 );578 @end example579 @end ifset580 581 @ifset is-Ada582 @end ifset583 584 @subheading STATUS CODES:585 586 @table @b587 @item EPERM588 The user is not the super-user.589 590 @item ENODEV591 @code{Filesystemtype} not configured in the kernel.592 593 @item ENOTBLK594 @code{Specialfile} is not a block device (if a device was required).595 596 @item EBUSY597 @code{Specialfile} is already mounted. Or, it cannot be remounted598 read-only, because it still holds files open for writing. Or, it599 cannot be mounted on @code{dir} because @code{dir} is still busy600 (it is the working directory of some task, the mount point of another601 device, has open files, etc.).602 603 @item EINVAL604 @code{Specialfile had an invalid superblock. Or, a remount was605 attempted, while @code{specialfile} was not already mounted on @code{dir}.606 Or, an umount was attempted, while @code{dir} was not a mount point.607 608 @item EFAULT609 One of the pointer arguments points outside the user address space.610 611 @item ENOMEM612 The kernel could not allocate a free page to copy filenames or data into.613 614 @item ENAMETOOLONG615 A pathname was longer than MAXPATHLEN.616 617 @item ENOTDIR618 A pathname was empty or had a nonexistent component.619 620 @item EACCES621 A component of a path was not searchable. Or, mounting a read-only622 filesystem was attempted without giving the MS_RDONLY flag. Or, the623 block device Specialfile is located on a filesystem mounted with624 the MS_NODEV option.625 626 @item ENXIO627 The major number of the block device @code{specialfile} is out of628 range.629 630 @item EMFILE631 (In case no block device is required:) Table of dummy devices is full.632 784 633 785 @end table … … 640 792 Only the super-user may umount filesystems. 641 793 642 @subheading NOTES: None 794 @subheading NOTES: 795 796 NONE 643 797 644 798 @page
Note: See TracChangeset
for help on using the changeset viewer.