VxWorks API Reference : OS Libraries
netDrv - network remote file I/O driver
netDrv( ) - install the network remote file driver
netDevCreate( ) - create a remote file device
netDevCreate2( ) - create a remote file device with fixed buffer size
netDrvDebugLevelSet( ) - set the debug level of the netDrv library routines
netDrvFileDoesNotExistInstall( ) - install an applette to test if the file exists
This driver provides facilities for accessing files transparently over the network via FTP or RSH. By creating a network device with netDevCreate( ), files on a remote UNIX machine may be accessed as if they were local.
When a remote file is opened, the entire file is copied over the network to a local buffer. When a remote file is created, an empty local buffer is opened. Any reads, writes, or ioctl( ) calls are performed on the local copy of the file. If the file was opened with the flags O_WRONLY or O_RDWR and modified, the local copy is sent back over the network to the UNIX machine when the file is closed.
Note that this copying of the entire file back and forth can make netDrv devices awkward to use. A preferable mechanism is NFS as provided by nfsDrv.
Most of the routines in this driver are accessible only through the I/O system. However, two routines must be called directly: netDrv( ) to initialize the driver and netDevCreate( ) to create devices.
This driver supports the creation, deletion, opening, reading, writing, and appending of files. The renaming of files is not supported.
Before using the driver, it must be initialized by calling the routine netDrv( ). This routine should be called only once, before any reads, writes, netDevCreate( ), or netDevCreate2( ) calls. Initialization is performed automatically when INCLUDE_NET_DRV is defined.
To access files on a remote host, a network device must be created by calling netDevCreate( ) or netDevCreate2( ). The arguments to netDevCreate( ) are the name of the device, the name of the host the device will access, and the remote file access protocol to be used -- RSH or FTP. The arguments to netDevCreate2( ) are ones described above and a size of buffer used in the network device as a fourth argument. By convention, a network device name is the remote machine name followed by a colon ":". For example, for a UNIX host on the network "wrs", files can be accessed by creating a device called "wrs:". For more information, see the manual entry for netDevCreate( ) and netDevCreate2( ).
The network driver responds to the following ioctl( ) functions:
- FIOGETNAME
- Gets the file name of the file descriptor fd and copies it to the buffer specified by nameBuf:
status = ioctl (fd, FIOGETNAME, &nameBuf);- FIONREAD
- Copies to nBytesUnread the number of bytes remaining in the file specified by fd:
status = ioctl (fd, FIONREAD, &nBytesUnread);- FIOSEEK
- Sets the current byte offset in the file to the position specified by newOffset. If the seek goes beyond the end-of-file, the file grows. The end-of-file pointer changes to the new position, and the new space is filled with zeroes:
status = ioctl (fd, FIOSEEK, newOffset);- FIOWHERE
- Returns the current byte position in the file. This is the byte offset of the next byte to be read or written. It takes no additional argument:
position = ioctl (fd, FIOWHERE, 0);- FIOFSTATGET
- Gets file status information. The argument statStruct is a pointer to a stat structure that is filled with data describing the specified file. Normally, the stat( ) or fstat( ) routine is used to obtain file information, rather than using the FIOFSTATGET function directly. netDrv only fills in three fields of the stat structure: st_dev, st_mode, and st_size. st_mode is always filled with S_IFREG.
struct stat statStruct; fd = open ("file", O_RDONLY); status = ioctl (fd, FIOFSTATGET, &statStruct);
The netDrv implementation strategy implies that directories cannot always be distinguished from plain files. Thus, opendir( ) does not work for directories mounted on netDrv devices, and ll( ) does not flag subdirectories with the label "DIR" in listings from netDrv devices.
When the access method is FTP, operations can only be done on files that the FTP server allows to download. In particular it is not possible to stat a directory, doing so will result in "dirname: not a plain file" error.
netDrv.h
remLib, netLib, sockLib, hostAdd( )
netDrv( ) - install the network remote file driver
STATUS netDrv (void)
This routine initializes and installs the network driver. It must be called before other network remote file functions are performed. It is called automatically when INCLUDE_NET_DRV is defined.
Under VxWorks AE, you can call this function from within the kernel protection domain only. This restriction does not apply under non-AE versions of VxWorks.
OK or ERROR.
netDevCreate( ) - create a remote file device
STATUS netDevCreate ( char * devName, /* name of device to create */ char * host, /* host this device will talk to */ int protocol /* remote file access protocol 0 = RSH, 1 = FTP */ )
This routine creates a remote file device. Normally, a network device is created for each remote machine whose files are to be accessed. By convention, a network device name is the remote machine name followed by a colon ":". For example, for a UNIX host on the network whose name is "wrs", files can be accessed by creating a device called "wrs:". Files can be accessed via RSH as follows:
netDevCreate ("wrs:", "wrs", rsh);The file /usr/dog on the UNIX system "wrs" can now be accessed as "wrs:/usr/dog" via RSH.Before creating a device, the host must have already been created with hostAdd( ).
OK or ERROR.
netDevCreate2( ) - create a remote file device with fixed buffer size
STATUS netDevCreate2 ( char * devName, /* name of device to create */ char * host, /* host this device will talk to */ int protocol, /* remote file access protocol 0 = RSH, 1 = FTP */ UINT bufSize /* size of buffer in NET_FD */ )
This routine creates a remote file device, just like netDevCreate( ), but it allows very large files to be accessed without loading the entire file to memory. The fourth parameter bufSize specifies the amount of memory. If the bufSize is zero, then the behavior is exactly the same as netDevCreate( ). If bufSize is not zero, the following restrictions apply:
- O_RDONLY, O_WRONLY open modes are supported, but not O_RDWR open mode. - seek is supported in O_RDONLY open mode, but not in O_WRONLY open mode. - backward seek will be slow if it is beyond the buffer.
OK or ERROR.
netDrv, netDevCreate( )
netDrvDebugLevelSet( ) - set the debug level of the netDrv library routines
STATUS netDrvDebugLevelSet ( UINT32 debugLevel /* NETDRV_DEBUG_OFF, NETDRV_DEBUG_ERRORS, */ /* NETDRV_DEBUG_ALL */ )
This routine enables the debugging of calls to the net driver. The argument NETLIB_DEBUG_ERRORS will display only error messages to the console. The argument NETLIB_DEBUG_ALL will display warnings and errors to the console.
OK, or ERROR if the debug level is invalid
netDrvFileDoesNotExistInstall( ) - install an applette to test if the file exists
STATUS netDrvFileDoesNotExistInstall ( FUNCPTR pAppletteRtn /* Function that returns TRUE or FALSE */ )
Install a function which will test if a given file exists.
The pAppletteRtn argument provides a routine using the following interface:
STATUS appletteRoutine ( char *filename, /* file name queried */ char *response /* server response string */ )The netDrv routine calls the applette routine during an open with O_CREAT specified. The system will perform an NLST command and then use the applette routine to parse the response. The routine compensates for server response implementaion variations. The applette should return OK if the file is not found and ERROR if the file is found.
OK, installation successful; ERROR, installation error.