VxWorks Reference Manual : Libraries
wdbTsfsDrv - virtual generic file I/O driver for the WDB agent
wdbTsfsDrv( ) - initialize the TSFS device driver for a WDB agent
This library provides a virtual file I/O driver for use with the WDB agent. I/O is performed on this virtual I/O device exactly as it would be on any device referencing a VxWorks file system. File operations, such as read( ) and write( ), move data over a virtual I/O channel created between the WDB agent and the Tornado target server. The operations are then executed on the host file system. Because file operations are actually performed on the host file system by the target server, the file system presented by this virtual I/O device is known as the target-server file system, or TSFS.
The driver is installed with wdbTsfsDrv( ), creating a device typically called /tgtsvr. See the manual page for wdbTsfsDrv( ) for more information about using this function. The initialization is done automatically, enabling access to TSFS, when INCLUDE_WDB_TSFS is defined. The target server also must have TSFS enabled in order to use TSFS. See the WindView User's Guide: Data Upload and the target server documentation.
TSFS provides all of the functionality of other VxWorks file systems. For details, see the VxWorks Programmer's Guide: I/O System and Local File Systems. In addition to normal files, however, TSFS also provides basic access to TCP sockets. This includes opening the client side of a TCP socket, reading, writing, and closing the socket. Basic setsockopt( ) commands are also supported.
To open a TCP socket using TSFS, use a filename of the form:
TCP:server_name | server_ip:port_numberTo open and connect a TCP socket to a server socket located on a server named mongoose, listening on port 2010, use the following:fd = open ("/tgtsvr/TCP:mongoose:2010", 0, 0)The open flags and permission arguments to the open call are ignored when opening a socket through TSFS. If the server mongoose has an IP number of 144.12.44.12, you can use the following equivalent form of the command:fd = open ("/tgtsvr/TCP:144.12.44.12:2010", 0, 0)
All directory functions, such as mkdir( ), rmdir( ), opendir( ), readdir( ), closedir( ), and rewinddir( ) are supported by TSFS, regardless of whether the target server providing TSFS is being run on a UNIX or Windows host.
While it is possible to open and close directories using open( ) and close( ), it is not possible to read from a directory using read( ). Instead, readdir( ) must be used. It is also not possible to write to an open directory, and opening a directory for anything other than read-only results in an error, with errno set to EISDIR. Calling read( ) on a directory returns ERROR with errno set to EISDIR.
When the target server that is providing the TSFS is running on a Windows host, the default file-translation mode is binary translation. If text translation is required, then WDB_TSFS_O_TEXT can be included in the mode argument to open( ). For example:
fd = open ("/tgtsvr/foo", O_CREAT | O_RDWR | WDB_TSFS_O_TEXT, 0777)If the target server providing TSFS services is running on a UNIX host, WDB_TSFS_O_TEXT is ignored.
For general information on the target server, see the reference entry for tgtsvr. In order to use this library, the target server must support and be configured with the following options:
- -R root
- Specify the root of the host's file system that is visible to target processes using TSFS. This flag is required to use TSFS. Files under this root are by default read only. To allow read/write access, specify -RW.
- -RW
- Allow read and write access to host files by target processes using TSFS. When this option is specified, access to the target server is restricted as if -L were also specified.
TSFS supports the following ioctl( ) functions for controlling files and sockets. Details about each function can be found in the documentation listed below.
- FIOSEEK
- FIOWHERE
- FIOMKDIR
- Create a directory. The path, in this case /tgtsvr/tmp, must be an absolute path prefixed with the device name. To create the directory /tmp on the root of the TSFS file system use the following:
status = ioctl (fd, FIOMKDIR, "/tgtsvr/tmp")- FIORMDIR
- Remove a directory. The path, in this case /tgtsvr/foo, must be an absolute path prefixed with the device name. To remove the directory /foo from the root of the TSFS file system, use the following:
status = ioctl (fd, FIORMDIR, "/tgtsvr/foo")- FIORENAME
- Rename the file or directory represented by fd to the name in the string pointed to by arg. The path indicated by arg may be prefixed with the device name or not. Using this ioctl( ) function with the path /foo/goo produces the same outcome as the path /tgtsvr/foo/goo. The path is not modified to account for the current working directory, and therefore must be an absolute path.
char *arg = "/tgtsvr/foo/goo"; status = ioctl (fd, FIORENAME, arg);- FIOREADDIR
- FIONREAD
- Return the number of bytes ready to read on a TSFS socket file descriptor.
- FIOFSTATGET
- FIOGETFL
The following ioctl( ) functions can be used only on socket file descriptors. Using these functions with ioctl( ) provides similar behavior to the setsockopt( ) and getsockopt( ) functions usually used with socket descriptors. Each command's name is derived from a getsockopt( )/setsockopt( ) command and works in exactly the same way as the respective getsockopt( )/setsockopt( ) command. The functions setsockopt( ) and getsockopt( ) can not be used with TSFS socket file descriptors.
For example, to enable recording of debugging information on the TSFS socket file descriptor, call:
int arg = 1; status = ioctl (fd, SO_SETDEBUG, arg);To determine whether recording of debugging information for the TSFS-socket file descritptor is enabled or disabled, call:int arg; status = ioctl (fd, SO_GETDEBUG, & arg);After the call to ioctl( ), arg contains the state of the debugging attribute.The ioctl( ) functions supported for TSFS sockets are:
- SO_SETDEBUG
- Equivalent to setsockopt( ) with the SO_DEBUG command.
- SO_GETDEBUG
- Equivalent to getsockopt( ) with the SO_DEBUG command.
- SO_SETSNDBUF
- This command changes the size of the send buffer of the host socket. The configuration of the WDB channel between the host and target also affects the number of bytes that can be written to the TSFS file descriptor in a single attempt.
- SO_SETRCVBUF
- This command changes the size of the receive buffer of the host socket. The configuration of the WDB channel between the host and target also affects the number of bytes that can be read from the TSFS file descriptor in a single attempt.
- SO_SETDONTROUTE
- Equivalent to setsockopt( ) with the SO_DONTROUTE command.
- SO_GETDONTROUTE
- Equivalent to getsockopt( ) with the SO_DONTROUTE command.
- SO_SETOOBINLINE
- Equivalent to setsockopt( ) with the SO_OOBINLINE command.
- SO_GETOOBINLINE
- Equivalent to getsockopt( ) with the SO_OOBINLINE command.
- SO_SNDURGB
- The SO_SNDURGB command sends one out-of-band byte (pointed to by arg) through the socket.
The routines in this library return the VxWorks error codes that most closely match the errnos generated by the corresponding host function. If an error is encountered that is due to a WDB failure, a WDB error is returned instead of the standard VxWorks errno. If an errno generated on the host has no reasonable VxWorks counterpart, the host errno is passed to the target calling routine unchanged.
wdbTsfsDrv, Tornado User's Guide, VxWorks Programmer's Guide: I/O System, Local File Systems
wdbTsfsDrv( ) - initialize the TSFS device driver for a WDB agent
STATUS wdbTsfsDrv ( char * name /* root name in i/o system */ )
This routine initializes the VxWorks virtual I/O "2" driver and creates a TSFS device of the specified name.
This routine should be called exactly once, before any reads, writes, or opens. Normally, it is called by usrRoot( ) in usrConfig.c, and the device name created is /tgtsvr.
After this routine has been called, individual virtual I/O channels can be opened by appending the host file name to the virtual I/O device name. For example, to get a file descriptor for the host file /etc/passwd, call open( ) as follows:
fd = open ("/tgtsvr/etc/passwd", O_RDWR, 0)
OK, or ERROR if the driver can not be installed.