[daf1622] | 1 | @c |
---|
| 2 | @c COPYRIGHT (c) 1988-1998. |
---|
| 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
| 6 | @c $Id$ |
---|
| 7 | @c |
---|
| 8 | |
---|
| 9 | @chapter System Call Development Notes |
---|
| 10 | |
---|
| 11 | This set of routines represents the application's interface to files and directories |
---|
| 12 | under the RTEMS file system. All routines are compliant with POSIX standards if a |
---|
| 13 | specific interface has been established. The list below represents the routines that have |
---|
| 14 | been included as part of the application's interface. |
---|
| 15 | |
---|
| 16 | @enumerate |
---|
| 17 | @item access() |
---|
| 18 | @item chdir() |
---|
| 19 | @item chmod() |
---|
| 20 | @item chown() |
---|
| 21 | @item close() |
---|
| 22 | @item closedir() |
---|
| 23 | @item dup() |
---|
| 24 | @item dup2() |
---|
| 25 | @item fchmod() |
---|
| 26 | @item fcntl() |
---|
| 27 | @item fdatasync() |
---|
| 28 | @item fpathconf() |
---|
| 29 | @item fstat() |
---|
| 30 | @item ioctl() |
---|
| 31 | @item link() |
---|
| 32 | @item lseek() |
---|
| 33 | @item mkdir() |
---|
| 34 | @item mkfifo() |
---|
| 35 | @item mknod() |
---|
| 36 | @item mount() |
---|
| 37 | @item open() |
---|
| 38 | @item opendir() |
---|
| 39 | @item pathconf() |
---|
| 40 | @item read() |
---|
| 41 | @item readdir() |
---|
| 42 | @item unmount() |
---|
| 43 | @end enumerate |
---|
| 44 | |
---|
| 45 | The sections that follow provide developmental information concerning each of these functions. |
---|
| 46 | |
---|
| 47 | |
---|
| 48 | @page |
---|
| 49 | @section access |
---|
| 50 | |
---|
| 51 | @subheading File: |
---|
| 52 | |
---|
| 53 | access.c |
---|
| 54 | |
---|
| 55 | @subheading Processing: |
---|
| 56 | |
---|
| 57 | This routine is layered on the stat() function. It acquires the current status |
---|
| 58 | information for the specified file and then determines if the caller has the ability |
---|
| 59 | to access the file for read, write or execute according to the mode argument to this |
---|
| 60 | function. |
---|
| 61 | |
---|
| 62 | @subheading Development Comments: |
---|
| 63 | |
---|
| 64 | This routine is layered on top of the stat() function. As long as the st_mode |
---|
| 65 | element in the returned structure follow the standard UNIX conventions, this |
---|
| 66 | function should support other file systems without alteration. |
---|
| 67 | |
---|
| 68 | @page |
---|
| 69 | @section chdir |
---|
| 70 | |
---|
| 71 | @subheading File: |
---|
| 72 | |
---|
| 73 | chdir.c |
---|
| 74 | |
---|
| 75 | |
---|
| 76 | @subheading Processing: |
---|
| 77 | |
---|
| 78 | This routine will determine if the pathname that we are attempting to make that |
---|
| 79 | current directory exists and is in fact a directory. If these conditions are met the |
---|
| 80 | global indication of the current directory (rtems_filesystem_current) is set to the |
---|
| 81 | rtems_filesystem_location_info_t structure that is returned by the |
---|
| 82 | rtems_filesystem_evaluate_path() routine. |
---|
| 83 | |
---|
| 84 | @subheading Development Comments: |
---|
| 85 | |
---|
| 86 | This routine is layered on the rtems_filesystem_evaluate_path() routine and the |
---|
| 87 | file system specific OP table function node_type(). |
---|
| 88 | |
---|
| 89 | The routine node_type() must be a routine provided for each file system since it |
---|
| 90 | must access the file systems node information to determine which of the |
---|
| 91 | following types the node is: |
---|
| 92 | |
---|
| 93 | @itemize @bullet |
---|
| 94 | @item RTEMS_FILESYSTEM_DIRECTORY |
---|
| 95 | @item RTEMS_FILESYSTEM_DEVICE |
---|
| 96 | @item RTEMS_FILESYSTEM_HARD_LINK |
---|
| 97 | @item RTEMS_FILESYSTEM_MEMORY_FILE |
---|
| 98 | @end itemize |
---|
| 99 | |
---|
| 100 | This acknowledges that the form of the node management information can vary |
---|
| 101 | from one file system implementation to another. |
---|
| 102 | |
---|
| 103 | RTEMS has a special global structure that maintains the current directory |
---|
| 104 | location. This global variable is of type rtems_filesystem_location_info_t and is |
---|
| 105 | called rtems_filesystem_current. This structure is not always valid. In order to |
---|
| 106 | determine if the structure is valid, you must first test the node_access element of |
---|
| 107 | this structure. If the pointer is NULL, then the structure does not contain a valid |
---|
| 108 | indication of what the current directory is. |
---|
| 109 | |
---|
| 110 | @page |
---|
| 111 | @section chmod |
---|
| 112 | |
---|
| 113 | @subheading File: |
---|
| 114 | |
---|
| 115 | chmod.c |
---|
| 116 | |
---|
| 117 | @subheading Processing: |
---|
| 118 | |
---|
| 119 | This routine is layered on the open(), fchmod () and close () functions. As long as |
---|
| 120 | the standard interpretation of the mode_t value is maintained, this routine should |
---|
| 121 | not need modification to support other file systems. |
---|
| 122 | |
---|
| 123 | @subheading Development Comments: |
---|
| 124 | |
---|
| 125 | The routine first determines if the selected file can be open with read/write access. |
---|
| 126 | This is required to allow modification of the mode associated with the selected |
---|
| 127 | path. |
---|
| 128 | |
---|
| 129 | The fchmod() function is used to actually change the mode of the path using the |
---|
| 130 | integer file descriptor returned by the open() function. |
---|
| 131 | |
---|
| 132 | After mode modification, the open file descriptor is closed. |
---|
| 133 | |
---|
| 134 | @page |
---|
| 135 | @section chown |
---|
| 136 | |
---|
| 137 | @subheading File: |
---|
| 138 | |
---|
| 139 | chown.c |
---|
| 140 | |
---|
| 141 | @subheading Processing: |
---|
| 142 | |
---|
| 143 | This routine is layered on the rtems_filesystem_evaluate_path() and the file |
---|
| 144 | system specific chown() routine that is specified in the OPS table for the file |
---|
| 145 | system. |
---|
| 146 | |
---|
| 147 | @subheading Development Comments: |
---|
| 148 | |
---|
| 149 | rtems_filesystem_evaluate_path() is used to determine if the path specified |
---|
| 150 | actually exists. If it does a rtems_filesystem_location_info_t structure will be |
---|
| 151 | obtained that allows the shell function to locate the OPS table that is to be used |
---|
| 152 | for this file system. |
---|
| 153 | |
---|
| 154 | It is possible that the chown() function that should be in the OPS table is not |
---|
| 155 | defined. A test for a non-NULL OPS table chown() entry is performed before the |
---|
| 156 | function is called. |
---|
| 157 | |
---|
| 158 | If the chown() function is defined in the indicated OPS table, the function is |
---|
| 159 | called with the rtems_filesystem_location_info_t structure returned from the path |
---|
| 160 | evaluation routine, the desired owner, and group information. |
---|
| 161 | |
---|
| 162 | @page |
---|
| 163 | @section close |
---|
| 164 | |
---|
| 165 | @subheading File: |
---|
| 166 | |
---|
| 167 | close.c |
---|
| 168 | |
---|
| 169 | @subheading Processing: |
---|
| 170 | |
---|
| 171 | This routine will allow for the closing of both network connections and file |
---|
| 172 | system devices. If the file descriptor is associated with a network device, the |
---|
| 173 | appropriate network function handler will be selected from a table of previously |
---|
| 174 | registered network functions (rtems_libio_handlers) and that function will be |
---|
| 175 | invoked. |
---|
| 176 | |
---|
| 177 | If the file descriptor refers to an entry in the file system, the appropriate handler |
---|
| 178 | will be selected using information that has been placed in the file control block for |
---|
| 179 | the device (rtems_libio_t structure). |
---|
| 180 | |
---|
| 181 | @subheading Development Comments: |
---|
| 182 | |
---|
| 183 | rtems_file_descriptor_type examines some of the upper bits of the file descriptor |
---|
| 184 | index. If it finds that the upper bits are set in the file descriptor index, the device |
---|
| 185 | referenced is a network device. |
---|
| 186 | |
---|
| 187 | Network device handlers are obtained from a special registration table |
---|
| 188 | (rtems_libio_handlers) that is set up during network initialization. The network |
---|
| 189 | handler invoked and the status of the network handler will be returned to the |
---|
| 190 | calling process. |
---|
| 191 | |
---|
| 192 | If none of the upper bits are set in the file descriptor index, the file descriptor |
---|
| 193 | refers to an element of the RTEMS file system. |
---|
| 194 | |
---|
| 195 | The following sequence will be performed for any file system file descriptor: |
---|
| 196 | |
---|
| 197 | @enumerate |
---|
| 198 | |
---|
| 199 | @item Use the rtems_libio_iop() function to obtain the rtems_libio_t structure for the |
---|
| 200 | file descriptor |
---|
| 201 | |
---|
| 202 | @item Range check the file descriptor using rtems_libio_check_fd() |
---|
| 203 | |
---|
| 204 | @item Determine if there is actually a function in the selected handler table that |
---|
| 205 | processes the close() operation for the file system and node type selected. |
---|
| 206 | This is generally done to avoid execution attempts on functions that have not |
---|
| 207 | been implemented. |
---|
| 208 | |
---|
| 209 | @item If the function has been defined it is invoked with the file control block |
---|
| 210 | pointer as its argument. |
---|
| 211 | |
---|
| 212 | @item The file control block that was associated with the open file descriptor is |
---|
| 213 | marked as free using rtems_libio_free(). |
---|
| 214 | |
---|
| 215 | @item The return code from the close handler is then passed back to the calling |
---|
| 216 | program. |
---|
| 217 | |
---|
| 218 | @end enumerate |
---|
| 219 | |
---|
| 220 | @page |
---|
| 221 | @section closedir |
---|
| 222 | |
---|
| 223 | @subheading File: |
---|
| 224 | |
---|
| 225 | closedir.c |
---|
| 226 | |
---|
| 227 | @subheading Processing: |
---|
| 228 | |
---|
| 229 | The code was obtained from the BSD group. This routine must clean up the |
---|
| 230 | memory resources that are required to track an open directory. The code is layered |
---|
| 231 | on the close() function and standard memory free () functions. It should not |
---|
| 232 | require alterations to support other file systems. |
---|
| 233 | |
---|
| 234 | @subheading Development Comments: |
---|
| 235 | |
---|
| 236 | The routine alters the file descriptor and the index into the DIR structure to make |
---|
| 237 | it an invalid file descriptor. Apparently the memory that is about to be freed may |
---|
| 238 | still be referenced before it is reallocated. |
---|
| 239 | |
---|
| 240 | The dd_buf structure's memory is reallocated before the control structure that |
---|
| 241 | contains the pointer to the dd_buf region. |
---|
| 242 | |
---|
| 243 | DIR control memory is reallocated. |
---|
| 244 | |
---|
| 245 | The close() function is used to free the file descriptor index. |
---|
| 246 | |
---|
| 247 | |
---|
| 248 | @page |
---|
| 249 | @section dup() Unimplemented |
---|
| 250 | |
---|
| 251 | @subheading File: |
---|
| 252 | |
---|
| 253 | dup.c |
---|
| 254 | |
---|
| 255 | @subheading Processing: |
---|
| 256 | |
---|
| 257 | |
---|
| 258 | @subheading Development Comments: |
---|
| 259 | |
---|
| 260 | |
---|
| 261 | |
---|
| 262 | |
---|
| 263 | |
---|
| 264 | @page |
---|
| 265 | @section dup2() Unimplemented |
---|
| 266 | |
---|
| 267 | @subheading File: |
---|
| 268 | |
---|
| 269 | dup2.c |
---|
| 270 | |
---|
| 271 | @subheading Processing: |
---|
| 272 | |
---|
| 273 | |
---|
| 274 | @subheading Development Comments: |
---|
| 275 | |
---|
| 276 | |
---|
| 277 | |
---|
| 278 | |
---|
| 279 | |
---|
| 280 | |
---|
| 281 | @page |
---|
| 282 | @section fchmod |
---|
| 283 | |
---|
| 284 | @subheading File: |
---|
| 285 | |
---|
| 286 | fchmod.c |
---|
| 287 | |
---|
| 288 | @subheading Processing: |
---|
| 289 | |
---|
| 290 | This routine will alter the permissions of a node in a file system. It is layered on |
---|
| 291 | the following functions and macros: |
---|
| 292 | |
---|
| 293 | @itemize @bullet |
---|
| 294 | @item rtems_file_descriptor_type() |
---|
| 295 | |
---|
| 296 | @item rtems_libio_iop() |
---|
| 297 | |
---|
| 298 | @item rtems_libio_check_fd() |
---|
| 299 | |
---|
| 300 | @item rtems_libio_check_permissions() |
---|
| 301 | |
---|
| 302 | @item fchmod() function that is referenced by the handler table in the file control block associated with this file descriptor |
---|
| 303 | |
---|
| 304 | @end itemize |
---|
| 305 | |
---|
| 306 | @subheading Development Comments: |
---|
| 307 | |
---|
| 308 | The routine will test to see if the file descriptor index is associated with a network |
---|
| 309 | connection. If it is, an error is returned from this routine. |
---|
| 310 | |
---|
| 311 | The file descriptor index is used to obtain the associated file control block. |
---|
| 312 | |
---|
| 313 | The file descriptor value is range checked. |
---|
| 314 | |
---|
| 315 | The file control block is examined to determine if it has write permissions to |
---|
| 316 | allow us to alter the mode of the file. |
---|
| 317 | |
---|
| 318 | A test is made to determine if the handler table that is referenced in the file |
---|
| 319 | control block contains an entry for the fchmod() handler function. If it does not, |
---|
| 320 | an error is returned to the calling routine. |
---|
| 321 | |
---|
| 322 | If the fchmod() handler function exists, it is called with the file control block and |
---|
| 323 | the desired mode as parameters. |
---|
| 324 | |
---|
| 325 | @page |
---|
| 326 | @section fcntl() |
---|
| 327 | |
---|
| 328 | @subheading File: |
---|
| 329 | |
---|
| 330 | fcntl.c |
---|
| 331 | |
---|
| 332 | @subheading Processing: |
---|
| 333 | |
---|
| 334 | This routine currently only interacts with the file control block. If the structure of |
---|
| 335 | the file control block and the associated meanings do not change, the partial |
---|
| 336 | implementation of fcntl() should remain unaltered for other file system |
---|
| 337 | implementations. |
---|
| 338 | |
---|
| 339 | @subheading Development Comments: |
---|
| 340 | |
---|
| 341 | The only commands that have been implemented are the F_GETFD and |
---|
| 342 | F_SETFD. The commands manipulate the LIBIO_FLAGS_CLOSE_ON_EXEC |
---|
| 343 | bit in the -flags- element of the file control block associated with the file |
---|
| 344 | descriptor index. |
---|
| 345 | |
---|
| 346 | The current implementation of the function performs the sequence of operations |
---|
| 347 | below: |
---|
| 348 | |
---|
| 349 | @enumerate |
---|
| 350 | |
---|
| 351 | @item Test to see if we are trying to operate on a file descriptor associated with a |
---|
| 352 | network connection |
---|
| 353 | |
---|
| 354 | @item Obtain the file control block that is associated with the file descriptor index |
---|
| 355 | |
---|
| 356 | @item Perform a range check on the file descriptor index. |
---|
| 357 | |
---|
| 358 | @end enumerate |
---|
| 359 | |
---|
| 360 | |
---|
| 361 | |
---|
| 362 | @page |
---|
| 363 | @section fdatasync |
---|
| 364 | |
---|
| 365 | @subheading File: |
---|
| 366 | |
---|
| 367 | fdatasync.c |
---|
| 368 | |
---|
| 369 | @subheading Processing: |
---|
| 370 | |
---|
| 371 | This routine is a template in the in memory file system that will route us to the |
---|
| 372 | appropriate handler function to carry out the fdatasync() processing. In the in |
---|
| 373 | memory file system this function is not necessary. Its function in a disk based file |
---|
| 374 | system that employs a memory cache is to flush all memory based data buffers to |
---|
| 375 | disk. It is layered on the following functions and macros: |
---|
| 376 | |
---|
| 377 | @itemize @bullet |
---|
| 378 | |
---|
| 379 | @item rtems_file_descriptor_type() |
---|
| 380 | |
---|
| 381 | @item rtems_libio_iop() |
---|
| 382 | |
---|
| 383 | @item rtems_libio_check_fd() |
---|
| 384 | |
---|
| 385 | @item rtems_libio_check_permissions() |
---|
| 386 | |
---|
| 387 | @item fdatasync() function that is referenced by the handler table in the file control block associated with this file descriptor |
---|
| 388 | |
---|
| 389 | @end itemize |
---|
| 390 | |
---|
| 391 | @subheading Development Comments: |
---|
| 392 | |
---|
| 393 | The routine will test to see if the file descriptor index is associated with a network |
---|
| 394 | connection. If it is, an error is returned from this routine. |
---|
| 395 | |
---|
| 396 | The file descriptor index is used to obtain the associated file control block. |
---|
| 397 | |
---|
| 398 | The file descriptor value is range checked. |
---|
| 399 | |
---|
| 400 | The file control block is examined to determine if it has write permissions to the |
---|
| 401 | file. |
---|
| 402 | |
---|
| 403 | A test is made to determine if the handler table that is referenced in the file |
---|
| 404 | control block contains an entry for the fdatasync() handler function. If it does not |
---|
| 405 | an error is returned to the calling routine. |
---|
| 406 | |
---|
| 407 | If the fdatasync() handler function exists, it is called with the file control block as |
---|
| 408 | its parameter. |
---|
| 409 | |
---|
| 410 | @page |
---|
| 411 | @section fpathconf |
---|
| 412 | |
---|
| 413 | @subheading File: |
---|
| 414 | |
---|
| 415 | fpathconf.c |
---|
| 416 | |
---|
| 417 | @subheading Processing: |
---|
| 418 | |
---|
| 419 | This routine is layered on the following functions and macros: |
---|
| 420 | |
---|
| 421 | @itemize @bullet |
---|
| 422 | |
---|
| 423 | @item rtems_file_descriptor_type() |
---|
| 424 | |
---|
| 425 | @item rtems_libio_iop() |
---|
| 426 | |
---|
| 427 | @item rtems_libio_check_fd() |
---|
| 428 | |
---|
| 429 | @item rtems_libio_check_permissions() |
---|
| 430 | |
---|
| 431 | @end itemize |
---|
| 432 | |
---|
| 433 | When a file system is mounted, a set of constants is specified for the file system. |
---|
| 434 | These constants are stored with the mount table entry for the file system. These |
---|
| 435 | constants appear in the POSIX standard and are listed below. |
---|
| 436 | |
---|
| 437 | @itemize @bullet |
---|
| 438 | |
---|
| 439 | @item PCLINKMAX |
---|
| 440 | |
---|
| 441 | @item PCMAXCANON |
---|
| 442 | |
---|
| 443 | @item PCMAXINPUT |
---|
| 444 | |
---|
| 445 | @item PCNAMEMAX |
---|
| 446 | |
---|
| 447 | @item PCPATHMAX |
---|
| 448 | |
---|
| 449 | @item PCPIPEBUF |
---|
| 450 | |
---|
| 451 | @item PCCHOWNRESTRICTED |
---|
| 452 | |
---|
| 453 | @item PCNOTRUNC |
---|
| 454 | |
---|
| 455 | @item PCVDISABLE |
---|
| 456 | |
---|
| 457 | @item PCASYNCIO |
---|
| 458 | |
---|
| 459 | @item PCPRIOIO |
---|
| 460 | |
---|
| 461 | @item PCSYNCIO |
---|
| 462 | |
---|
| 463 | |
---|
| 464 | @end itemize |
---|
| 465 | |
---|
| 466 | This routine will find the mount table information associated the file control block |
---|
| 467 | for the specified file descriptor parameter. The mount table entry structure |
---|
| 468 | contains a set of file system specific constants that can be accessed by individual |
---|
| 469 | identifiers. |
---|
| 470 | |
---|
| 471 | @subheading Development Comments: |
---|
| 472 | |
---|
| 473 | The routine will test to see if the file descriptor index is associated with a network |
---|
| 474 | connection. If it is, an error is returned from this routine. |
---|
| 475 | |
---|
| 476 | The file descriptor index is used to obtain the associated file control block. |
---|
| 477 | |
---|
| 478 | The file descriptor value is range checked. |
---|
| 479 | |
---|
| 480 | The file control block is examined to determine if it has read permissions to the |
---|
| 481 | file. |
---|
| 482 | |
---|
| 483 | Pathinfo in the file control block is used to locate the mount table entry for the |
---|
| 484 | file system associated with the file descriptor. |
---|
| 485 | |
---|
| 486 | The mount table entry contains the pathconf_limits_and_options element. This |
---|
| 487 | element is a table of constants that is associated with the file system. |
---|
| 488 | |
---|
| 489 | The name argument is used to reference the desired constant from the |
---|
| 490 | pathconf_limits_and_options table. |
---|
| 491 | |
---|
| 492 | |
---|
| 493 | @page |
---|
| 494 | @section fstat |
---|
| 495 | |
---|
| 496 | @subheading File: |
---|
| 497 | |
---|
| 498 | fstat.c |
---|
| 499 | |
---|
| 500 | @subheading Processing: |
---|
| 501 | |
---|
| 502 | This routine will return information concerning a file or network connection. If |
---|
| 503 | the file descriptor is associated with a network connection, the current |
---|
| 504 | implementation of fstat() will return a mode set to S_IFSOCK. In a later version, |
---|
| 505 | this routine will map the status of a network connection to an external handler |
---|
| 506 | routine. |
---|
| 507 | |
---|
| 508 | If the file descriptor is associated with a node under a file system, the fstat() |
---|
| 509 | routine will map to the fstat() function taken from the node handler table. |
---|
| 510 | |
---|
| 511 | @subheading Development Comments: |
---|
| 512 | |
---|
| 513 | This routine validates that the struct stat pointer is not NULL so that the return |
---|
| 514 | location is valid. |
---|
| 515 | |
---|
| 516 | The struct stat is then initialized to all zeros. |
---|
| 517 | |
---|
| 518 | Rtems_file_descriptor_type() is then used to determine if the file descriptor is |
---|
| 519 | associated with a network connection. If it is, network status processing is |
---|
| 520 | performed. In the current implementation, the file descriptor type processing |
---|
| 521 | needs to be improved. It currently just drops into the normal processing for file |
---|
| 522 | system nodes. |
---|
| 523 | |
---|
| 524 | If the file descriptor is associated with a node under a file system, the following |
---|
| 525 | steps are performed: |
---|
| 526 | |
---|
| 527 | @enumerate |
---|
| 528 | |
---|
| 529 | @item Obtain the file control block that is associated with the file descriptor |
---|
| 530 | index. |
---|
| 531 | |
---|
| 532 | @item Range check the file descriptor index. |
---|
| 533 | |
---|
| 534 | @item Test to see if there is a non-NULL function pointer in the handler table |
---|
| 535 | for the fstat() function. If there is, invoke the function with the file |
---|
| 536 | control block and the pointer to the stat structure. |
---|
| 537 | |
---|
| 538 | @end enumerate |
---|
| 539 | |
---|
| 540 | @page |
---|
| 541 | @section ioctl |
---|
| 542 | |
---|
| 543 | @subheading File: |
---|
| 544 | |
---|
| 545 | ioctl.c |
---|
| 546 | |
---|
| 547 | @subheading Processing: |
---|
| 548 | |
---|
| 549 | Not defined in the POSIX 1003.1b standard but commonly supported in most |
---|
| 550 | UNIX and POSIX system. Ioctl() is a catchall for I/O operations. Routine is |
---|
| 551 | layered on external network handlers and file system specific handlers. The |
---|
| 552 | development of new file systems should not alter the basic processing performed |
---|
| 553 | by this routine. |
---|
| 554 | |
---|
| 555 | @subheading Development Comments: |
---|
| 556 | |
---|
| 557 | |
---|
| 558 | The file descriptor is examined to determine if it is associated with a network |
---|
| 559 | device. If it is processing is mapped to an external network handler. The value |
---|
| 560 | returned by this handler is then returned to the calling program. |
---|
| 561 | |
---|
| 562 | File descriptors that are associated with a file system undergo the following |
---|
| 563 | processing: |
---|
| 564 | |
---|
| 565 | @enumerate |
---|
| 566 | |
---|
| 567 | @item The file descriptor index is used to obtain the associated file control block. |
---|
| 568 | |
---|
| 569 | @item The file descriptor value is range checked. |
---|
| 570 | |
---|
| 571 | @item A test is made to determine if the handler table that is referenced in the file |
---|
| 572 | control block contains an entry for the ioctl() handler function. If it does |
---|
| 573 | not, an error is returned to the calling routine. |
---|
| 574 | |
---|
| 575 | @item If the ioctl() handler function exists, it is called with the file control block, |
---|
| 576 | the command and buffer as its parameters. |
---|
| 577 | |
---|
| 578 | @item The return code from this function is then sent to the calling routine. |
---|
| 579 | |
---|
| 580 | @end enumerate |
---|
| 581 | |
---|
| 582 | |
---|
| 583 | @page |
---|
| 584 | @section link |
---|
| 585 | |
---|
| 586 | @subheading File: |
---|
| 587 | |
---|
| 588 | link.c |
---|
| 589 | |
---|
| 590 | @subheading Processing: |
---|
| 591 | |
---|
| 592 | This routine will establish a hard link to a file, directory or a device. The target of |
---|
| 593 | the hard link must be in the same file system as the new link being created. A link |
---|
| 594 | to an existing link is also permitted but the existing link is evaluated before the |
---|
| 595 | new link is made. This implies that links to links are reduced to links to files, |
---|
| 596 | directories or devices before they are made. |
---|
| 597 | |
---|
| 598 | @subheading Development Comments: |
---|
| 599 | |
---|
| 600 | Calling parameters: |
---|
| 601 | const char *existing |
---|
| 602 | const char *new |
---|
| 603 | |
---|
| 604 | Link() will determine if the target of the link actually exists using |
---|
| 605 | rtems_filesystem_evaluate_path() |
---|
| 606 | |
---|
| 607 | Rtems_filesystem_get_start_loc() is used to determine where to start the path |
---|
| 608 | evaluation of the new name. This macro examines the first characters of the name |
---|
| 609 | to see if the name of the new link starts with a rtems_filesystem_is_separator. If it |
---|
| 610 | does the search starts from the root of the RTEMS file system; otherwise the |
---|
| 611 | search will start from the current directory. |
---|
| 612 | |
---|
| 613 | The OPS table evalformake() function for the parent's file system is used to |
---|
| 614 | locate the node that will be the parent of the new link. It will also locate the start |
---|
| 615 | of the new path's name. This name will be used to define a child under the parent |
---|
| 616 | directory. |
---|
| 617 | |
---|
| 618 | If the parent is found, the routine will determine if the hard link that we are trying |
---|
| 619 | to create will cross a file system boundary. This is not permitted for hard-links. |
---|
| 620 | |
---|
| 621 | If the hard-link does not cross a file system boundary, a check is performed to |
---|
| 622 | determine if the OPS table contains an entry for the link() function. |
---|
| 623 | |
---|
| 624 | If a link() function is defined, the OPS table link () function will be called to |
---|
| 625 | establish the actual link within the file system. |
---|
| 626 | |
---|
| 627 | The return code from the OPS table link() function is returned to the calling |
---|
| 628 | program. |
---|
| 629 | |
---|
| 630 | @page |
---|
| 631 | @section lseek |
---|
| 632 | |
---|
| 633 | @subheading File: |
---|
| 634 | |
---|
| 635 | lseek.c |
---|
| 636 | |
---|
| 637 | @subheading Processing: |
---|
| 638 | |
---|
| 639 | This routine is layered on both external handlers and file system / node type |
---|
| 640 | specific handlers. This routine should allow for the support of new file systems |
---|
| 641 | without modification. |
---|
| 642 | |
---|
| 643 | @subheading Development Comments: |
---|
| 644 | |
---|
| 645 | This routine will determine if the file descriptor is associated with a network |
---|
| 646 | device. If it is lseek will map to an external network handler. The handler will be |
---|
| 647 | called with the file descriptor, offset and whence as its calling parameters. The |
---|
| 648 | return code from the external handler will be returned to the calling routine. |
---|
| 649 | |
---|
| 650 | If the file descriptor is not associated with a network connection, it is associated |
---|
| 651 | with a node in a file system. The following steps will be performed for file system nodes: |
---|
| 652 | |
---|
| 653 | @enumerate |
---|
| 654 | |
---|
| 655 | @item The file descriptor is used to obtain the file control block for the node. |
---|
| 656 | |
---|
| 657 | @item The file descriptor is range checked. |
---|
| 658 | |
---|
| 659 | @item The offset element of the file control block is altered as indicated by |
---|
| 660 | the offset and whence calling parameters |
---|
| 661 | |
---|
| 662 | @item The handler table in the file control block is examined to determine if |
---|
| 663 | it contains an entry for the lseek() function. If it does not an error is |
---|
| 664 | returned to the calling program. |
---|
| 665 | |
---|
| 666 | @item The lseek() function from the designated handler table is called with |
---|
| 667 | the file control block, offset and whence as calling arguments |
---|
| 668 | |
---|
| 669 | @item The return code from the lseek() handler function is returned to the |
---|
| 670 | calling program |
---|
| 671 | |
---|
| 672 | @end enumerate |
---|
| 673 | |
---|
| 674 | |
---|
| 675 | @page |
---|
| 676 | @section mkdir |
---|
| 677 | |
---|
| 678 | @subheading File: |
---|
| 679 | |
---|
| 680 | mkdir.c |
---|
| 681 | |
---|
| 682 | @subheading Processing: |
---|
| 683 | |
---|
| 684 | This routine attempts to create a directory node under the file system. The routine |
---|
| 685 | is layered the mknod() function. |
---|
| 686 | |
---|
| 687 | @subheading Development Comments: |
---|
| 688 | |
---|
| 689 | See mknod() for developmental comments. |
---|
| 690 | |
---|
| 691 | @page |
---|
| 692 | @section mkfifo |
---|
| 693 | |
---|
| 694 | @subheading File: |
---|
| 695 | |
---|
| 696 | mkfifo.c |
---|
| 697 | |
---|
| 698 | @subheading Processing: |
---|
| 699 | |
---|
| 700 | This routine attempts to create a FIFO node under the file system. The routine is |
---|
| 701 | layered the mknod() function. |
---|
| 702 | |
---|
| 703 | @subheading Development Comments: |
---|
| 704 | |
---|
| 705 | See mknod() for developmental comments |
---|
| 706 | |
---|
| 707 | @page |
---|
| 708 | @section mknod |
---|
| 709 | |
---|
| 710 | @subheading File: |
---|
| 711 | |
---|
| 712 | mknod.c |
---|
| 713 | |
---|
| 714 | @subheading Processing: |
---|
| 715 | |
---|
| 716 | This function will allow for the creation of the following types of nodes under the |
---|
| 717 | file system: |
---|
| 718 | |
---|
| 719 | @itemize @bullet |
---|
| 720 | |
---|
| 721 | @item directories |
---|
| 722 | |
---|
| 723 | @item regular files |
---|
| 724 | |
---|
| 725 | @item character devices |
---|
| 726 | |
---|
| 727 | @item block devices |
---|
| 728 | |
---|
| 729 | @item fifos |
---|
| 730 | |
---|
| 731 | @end itemize |
---|
| 732 | |
---|
| 733 | At the present time, an attempt to create a FIFO will result in an ENOTSUP error |
---|
| 734 | to the calling function. This routine is layered the file system specific routines |
---|
| 735 | evalformake and mknod. The introduction of a new file system must include its |
---|
| 736 | own evalformake and mknod function to support the generic mknod() function. |
---|
| 737 | Under this condition the generic mknod() function should accommodate other |
---|
| 738 | file system types without alteration. |
---|
| 739 | |
---|
| 740 | @subheading Development Comments: |
---|
| 741 | |
---|
| 742 | Test for nodal types - I thought that this test should look like the following code: |
---|
| 743 | |
---|
| 744 | @example |
---|
| 745 | if ( (mode & S_IFDIR) = = S_IFDIR) || |
---|
| 746 | (mode & S_IFREG) = = S_IFREG) || |
---|
| 747 | (mode & S_IFCHR) = = S_IFCHR) || |
---|
| 748 | (mode & S_IFBLK) = = S_IFBLK) || |
---|
| 749 | (mode & S_IFIFO) = = S_IFIFO)) |
---|
| 750 | Set_errno_and_return_minus_one (EINVAL); |
---|
| 751 | |
---|
| 752 | @end example |
---|
| 753 | |
---|
| 754 | Where: |
---|
| 755 | |
---|
| 756 | @itemize @bullet |
---|
| 757 | @item S_IFREG (0100000) - Creation of a regular file |
---|
| 758 | @item S_IFCHR (0020000) - Creation of a character device |
---|
| 759 | @item S_IFBLK (0060000) - Creation of a block device |
---|
| 760 | @item S_IFIFO (0010000) - Creation of a FIFO |
---|
| 761 | @end itemize |
---|
| 762 | |
---|
| 763 | Determine if the pathname that we are trying to create starts at the root directory |
---|
| 764 | or is relative to the current directory using the rtems_filesystem_get_start_loc() |
---|
| 765 | function. |
---|
| 766 | |
---|
| 767 | Determine if the pathname leads to a valid directory that can be accessed for the |
---|
| 768 | creation of a node. |
---|
| 769 | |
---|
| 770 | If the pathname is a valid location to create a node, verify that a file system |
---|
| 771 | specific mknod() function exists. |
---|
| 772 | |
---|
| 773 | If the mknod() function exists, call the file system specific mknod () function. |
---|
| 774 | Pass the name, mode, device type and the location information associated with the |
---|
| 775 | directory under which the node will be created. |
---|
| 776 | |
---|
| 777 | @page |
---|
| 778 | @section mount |
---|
| 779 | |
---|
| 780 | @subheading File: |
---|
| 781 | |
---|
| 782 | mount.c |
---|
| 783 | |
---|
| 784 | |
---|
| 785 | Arguments (Not a standard POSIX call): |
---|
| 786 | |
---|
| 787 | Rtems_filesystem_mount_table_entry_t **mt_entry, |
---|
| 788 | |
---|
| 789 | If the mount operation is successful, this pointer to a pointer will be set to |
---|
| 790 | reference the mount table chain entry that has been allocated for this file |
---|
| 791 | system mount. |
---|
| 792 | |
---|
| 793 | rtems_filesystem_operations_table *fs_ops, |
---|
| 794 | |
---|
| 795 | This is a pointer to a table of functions that are associated with the file |
---|
| 796 | system that we are about to mount. This is the mechanism to selected file |
---|
| 797 | system type without keeping a dynamic database of all possible file |
---|
| 798 | system types that are valid for the mount operation. Using this method, it |
---|
| 799 | is only necessary to configure the file systems that we wish to use into the |
---|
| 800 | RTEMS build. Unused file systems types will not be drawn into the build. |
---|
| 801 | |
---|
| 802 | char *fsoptions, |
---|
| 803 | |
---|
| 804 | This argument points to a string that selects mounting for read only access |
---|
| 805 | or read/write access. Valid states are "RO" and "RW" |
---|
| 806 | |
---|
| 807 | char *device, |
---|
| 808 | |
---|
| 809 | This argument is reserved for the name of a device that will be used to |
---|
| 810 | access the file system information. Current file system implementations |
---|
| 811 | are memory based and do not require a device to access file system |
---|
| 812 | information. |
---|
| 813 | |
---|
| 814 | char *mount_point |
---|
| 815 | |
---|
| 816 | This is a pathname to a directory in a currently mounted file system that |
---|
| 817 | allows read, write and execute permissions. |
---|
| 818 | |
---|
| 819 | @subheading Processing: |
---|
| 820 | |
---|
| 821 | This routine will handle the mounting of a file system on a mount point. If the |
---|
| 822 | operation is successful, a pointer to the mount table chain entry associated with |
---|
| 823 | the mounted file system will be returned to the calling function. The specifics |
---|
| 824 | about the processing required at the mount point and within the file system being |
---|
| 825 | mounted is isolated in the file system specific mount() and fsmount_me () |
---|
| 826 | functions. This allows the generic mount() function to remain unaltered even if |
---|
| 827 | new file system types are introduced. |
---|
| 828 | |
---|
| 829 | |
---|
| 830 | |
---|
| 831 | @subheading Development Comments: |
---|
| 832 | |
---|
| 833 | This routine will use get_file_system_options() to determine if the mount options |
---|
| 834 | are valid ("RO" or "RW"). |
---|
| 835 | |
---|
| 836 | It confirms that a file system ops-table has been selected. |
---|
| 837 | |
---|
| 838 | Space is allocated for a mount table entry and selective elements of the temporary |
---|
| 839 | mount table entry are initialized. |
---|
| 840 | |
---|
| 841 | If a mount point is specified: |
---|
| 842 | The mount point is examined to determine that it is a directory and also |
---|
| 843 | has the appropriate permissions to allow a file system to be mounted. |
---|
| 844 | |
---|
| 845 | The current mount table chain is searched to determine that there is not |
---|
| 846 | another file system mounted at the mount point we are trying to mount |
---|
| 847 | onto. |
---|
| 848 | |
---|
| 849 | If a mount function is defined in the ops table for the file system |
---|
| 850 | containing the mount point, it is called at this time. |
---|
| 851 | |
---|
| 852 | If no mount point is specified: |
---|
| 853 | Processing if performed to set up the mount table chain entry as the base |
---|
| 854 | file system. |
---|
| 855 | |
---|
| 856 | If the fsmount_me() function is specified for ops-table of the file system being |
---|
| 857 | mounted, that function is called to initialize for the new file system. |
---|
| 858 | |
---|
| 859 | On successful completion, the temporary mount table entry will be placed on the |
---|
| 860 | mount table chain to record the presence of the mounted file system. |
---|
| 861 | |
---|
| 862 | @page |
---|
| 863 | @section open |
---|
| 864 | |
---|
| 865 | @subheading File: |
---|
| 866 | |
---|
| 867 | open.c |
---|
| 868 | |
---|
| 869 | @subheading Processing: |
---|
| 870 | |
---|
| 871 | This routine is layered on both RTEMS calls and file system specific |
---|
| 872 | implementations of the open() function. These functional interfaces should not |
---|
| 873 | change for new file systems and therefore this code should be stable as new file |
---|
| 874 | systems are introduced. |
---|
| 875 | |
---|
| 876 | @subheading Development Comments: |
---|
| 877 | |
---|
| 878 | This routine will allocate a file control block for the file or device that we are |
---|
| 879 | about to open. |
---|
| 880 | |
---|
| 881 | It will then test to see if the pathname exists. If it does a |
---|
| 882 | rtems_filesystem_location_info_t data structure will be filled out. This structure |
---|
| 883 | contains information that associates node information, file system specific |
---|
| 884 | functions and mount table chain information with the pathname. |
---|
| 885 | |
---|
| 886 | If the create option has been it will attempt to create a node for a regular file along |
---|
| 887 | the specified path. If a file already exists along this path, an error will be |
---|
| 888 | generated; otherwise, a node will be allocated for the file under the file system |
---|
| 889 | that contains the pathname. When a new node is created, it is also evaluated so |
---|
| 890 | that an appropriate rtems_filesystem_location_info_t data structure can be filled |
---|
| 891 | out for the newly created node. |
---|
| 892 | |
---|
| 893 | If the file exists or the new file was created successfully, the file control block |
---|
| 894 | structure will be initialized with handler table information, node information and |
---|
| 895 | the rtems_filesystem_location_info_t data structure that describes the node and |
---|
| 896 | file system data in detail. |
---|
| 897 | |
---|
| 898 | If an open() function exists in the file system specific handlers table for the node |
---|
| 899 | that we are trying to open, it will be called at this time. |
---|
| 900 | |
---|
| 901 | If any error is detected in the process, cleanup is performed. It consists of freeing |
---|
| 902 | the file control block structure that was allocated at the beginning of the generic |
---|
| 903 | open() routine. |
---|
| 904 | |
---|
| 905 | On a successful open(), the index into the file descriptor table will be calculated |
---|
| 906 | and returned to the calling routine. |
---|
| 907 | |
---|
| 908 | @page |
---|
| 909 | @section opendir |
---|
| 910 | |
---|
| 911 | @subheading File: |
---|
| 912 | |
---|
| 913 | opendir.c |
---|
| 914 | |
---|
| 915 | @subheading Processing: |
---|
| 916 | |
---|
| 917 | This routine will attempt to open a directory for read access. It will setup a DIR |
---|
| 918 | control structure that will be used to access directory information. This routine is |
---|
| 919 | layered on the generic open() routine and file system specific directory |
---|
| 920 | processing routines. |
---|
| 921 | |
---|
| 922 | @subheading Development Comments: |
---|
| 923 | |
---|
| 924 | The BSD group provided this routine. |
---|
| 925 | |
---|
| 926 | @page |
---|
| 927 | @section pathconf |
---|
| 928 | |
---|
| 929 | @subheading File: |
---|
| 930 | |
---|
| 931 | pathconf.c |
---|
| 932 | |
---|
| 933 | @subheading Processing: |
---|
| 934 | |
---|
| 935 | This routine will obtain the value of one of the path configuration parameters and |
---|
| 936 | return it to the calling routine. It is layered on the generic open() and fpathconf () |
---|
| 937 | functions. These interfaces should not change with the addition of new file system |
---|
| 938 | types. |
---|
| 939 | |
---|
| 940 | @subheading Development Comments: |
---|
| 941 | |
---|
| 942 | This routine will try to open the file indicated by path. |
---|
| 943 | |
---|
| 944 | If successful, the file descriptor will be used to access the pathconf value specified |
---|
| 945 | by -name- using the fpathconf() function. |
---|
| 946 | |
---|
| 947 | The file that was accessed is then closed. |
---|
| 948 | |
---|
| 949 | @page |
---|
| 950 | @section read |
---|
| 951 | |
---|
| 952 | @subheading File: |
---|
| 953 | |
---|
| 954 | deviceio.c |
---|
| 955 | |
---|
| 956 | @subheading Processing: |
---|
| 957 | |
---|
| 958 | This routine is layered on a set of RTEMS calls and file system specific read |
---|
| 959 | operations. The functions are layered in such a way as to isolate them from |
---|
| 960 | change as new file systems are introduced. |
---|
| 961 | |
---|
| 962 | @subheading Development Comments: |
---|
| 963 | |
---|
| 964 | This routine will examine the type of file descriptor it is sent. |
---|
| 965 | |
---|
| 966 | If the file descriptor is associated with a network device, the read function will be |
---|
| 967 | mapped to a special network handler. The return code from the network handler |
---|
| 968 | will then be sent as the return code from generic read() function. |
---|
| 969 | |
---|
| 970 | For file descriptors that are associated with the file system the following sequence |
---|
| 971 | will be performed: |
---|
| 972 | |
---|
| 973 | @enumerate |
---|
| 974 | |
---|
| 975 | @item Obtain the file control block associated with the file descriptor |
---|
| 976 | |
---|
| 977 | @item Range check the file descriptor |
---|
| 978 | |
---|
| 979 | @item Determine that the buffer pointer is not invalid |
---|
| 980 | |
---|
| 981 | @item Check that the count is not zero |
---|
| 982 | |
---|
| 983 | @item Check the file control block to see if we have permissions to read |
---|
| 984 | |
---|
| 985 | @item If there is a read function in the handler table, invoke the handler table |
---|
| 986 | read() function |
---|
| 987 | |
---|
| 988 | @item Use the return code from the handler table read function(number of |
---|
| 989 | bytes read) to increment the offset element of the file control block |
---|
| 990 | |
---|
| 991 | @item Return the number of bytes read to the calling program |
---|
| 992 | |
---|
| 993 | @end enumerate |
---|
| 994 | |
---|
| 995 | @page |
---|
| 996 | @section readdir |
---|
| 997 | |
---|
| 998 | @subheading File: |
---|
| 999 | |
---|
| 1000 | readdir.c |
---|
| 1001 | |
---|
| 1002 | @subheading Processing: |
---|
| 1003 | |
---|
| 1004 | This routine was acquired from the BSD group. It has not been altered from its |
---|
| 1005 | original form. |
---|
| 1006 | |
---|
| 1007 | @subheading Development Comments: |
---|
| 1008 | |
---|
| 1009 | The routine calls a customized getdents() function that is provided by the user. |
---|
| 1010 | This routine provides the file system specific aspects of reading a directory. |
---|
| 1011 | |
---|
| 1012 | It is layered on the read() function in the directory handler table. This function |
---|
| 1013 | has been mapped to the Imfs_dir_read() function. |
---|
| 1014 | |
---|
| 1015 | @page |
---|
| 1016 | @section unmount |
---|
| 1017 | |
---|
| 1018 | @subheading File: |
---|
| 1019 | |
---|
| 1020 | unmount.c |
---|
| 1021 | |
---|
| 1022 | @subheading Processing: |
---|
| 1023 | |
---|
| 1024 | This routine will attempt to dismount a mounted file system and then free all |
---|
| 1025 | resources that were allocated for the management of that file system. |
---|
| 1026 | |
---|
| 1027 | @subheading Development Comments: |
---|
| 1028 | |
---|
| 1029 | @itemize @bullet |
---|
| 1030 | |
---|
| 1031 | @item This routine will determine if there are any file systems currently mounted |
---|
| 1032 | under the file system that we are trying to dismount. This would prevent the |
---|
| 1033 | dismount of the file system. |
---|
| 1034 | |
---|
| 1035 | @item It will test to see if the current directory is in the file system that we are |
---|
| 1036 | attempting to dismount. This would prevent the dismount of the file system. |
---|
| 1037 | |
---|
| 1038 | @item It will scan all the currently open file descriptors to determine is there is an |
---|
| 1039 | open file descriptor to a file in the file system that we are attempting to |
---|
| 1040 | unmount(). |
---|
| 1041 | |
---|
| 1042 | @end itemize |
---|
| 1043 | |
---|
| 1044 | If the above preconditions are met then the following sequence is performed: |
---|
| 1045 | |
---|
| 1046 | @enumerate |
---|
| 1047 | |
---|
| 1048 | @item Call the file system specific unmount() function for the file system that |
---|
| 1049 | contains the mount point. This routine should indicate that the mount point |
---|
| 1050 | no longer has a file system mounted below it. |
---|
| 1051 | |
---|
| 1052 | @item Call the file system specific fsunmount_me() function for the mounted |
---|
| 1053 | file system that we are trying to unmount(). This routine should clean up |
---|
| 1054 | any resources that are no longer needed for the management of the file |
---|
| 1055 | system being un-mounted. |
---|
| 1056 | |
---|
| 1057 | @item Extract the mount table entry for the file system that was just dismounted |
---|
| 1058 | from the mount table chain. |
---|
| 1059 | |
---|
| 1060 | @item Free the memory associated with the extracted mount table entry. |
---|
| 1061 | |
---|
| 1062 | @end enumerate |
---|
| 1063 | |
---|
| 1064 | @page |
---|
| 1065 | @section eval |
---|
| 1066 | |
---|
| 1067 | @subheading File: |
---|
| 1068 | |
---|
| 1069 | XXX |
---|
| 1070 | |
---|
| 1071 | @subheading Processing: |
---|
| 1072 | |
---|
| 1073 | XXX |
---|
| 1074 | |
---|
| 1075 | @subheading Development Comments: |
---|
| 1076 | |
---|
| 1077 | XXX |
---|
| 1078 | |
---|
| 1079 | @page |
---|
| 1080 | @section getdentsc |
---|
| 1081 | |
---|
| 1082 | @subheading File: |
---|
| 1083 | |
---|
| 1084 | XXX |
---|
| 1085 | |
---|
| 1086 | @subheading Processing: |
---|
| 1087 | |
---|
| 1088 | XXX |
---|
| 1089 | |
---|
| 1090 | @subheading Development Comments: |
---|
| 1091 | |
---|
| 1092 | XXX |
---|
| 1093 | |
---|