VxWorks Reference Manual : Libraries
ioLib - I/O interface library
creat( ) - create a file
unlink( ) - delete a file (POSIX)
remove( ) - remove a file (ANSI)
open( ) - open a file
close( ) - close a file
rename( ) - change the name of a file
read( ) - read bytes from a file or device
write( ) - write bytes to a file
ioctl( ) - perform an I/O control function
lseek( ) - set a file read/write pointer
ioDefPathSet( ) - set the current default path
ioDefPathGet( ) - get the current default path
chdir( ) - set the current default path
getcwd( ) - get the current default path (POSIX)
getwd( ) - get the current default path
ioGlobalStdSet( ) - set the file descriptor for global standard input/output/error
ioGlobalStdGet( ) - get the file descriptor for global standard input/output/error
ioTaskStdSet( ) - set the file descriptor for task standard input/output/error
ioTaskStdGet( ) - get the file descriptor for task standard input/output/error
isatty( ) - return whether the underlying driver is a tty device
This library contains the interface to the basic I/O system. It includes:
- Interfaces to the seven basic driver-provided functions: creat( ), remove( ), open( ), close( ), read( ), write( ), and ioctl( ).
- Interfaces to several file system functions, including rename( ) and lseek( ).
- Routines to set and get the current working directory.
- Routines to assign task and global standard file descriptors.
At the basic I/O level, files are referred to by a file descriptor. A file descriptor is a small integer returned by a call to open( ) or creat( ). The other basic I/O calls take a file descriptor as a parameter to specify the intended file.
Three file descriptors are reserved and have special meanings:
0 (STD_IN) - standard input
1 (STD_OUT) - standard output
2 (STD_ERR) - standard error outputVxWorks allows two levels of redirection. First, there is a global assignment of the three standard file descriptors. By default, new tasks use this global assignment. The global assignment of the three standard file descriptors is controlled by the routines ioGlobalStdSet( ) and ioGlobalStdGet( ).
Second, individual tasks may override the global assignment of these file descriptors with their own assignments that apply only to that task. The assignment of task-specific standard file descriptors is controlled by the routines ioTaskStdSet( ) and ioTaskStdGet( ).
ioLib.h
ioLib, iosLib, ansiStdio, VxWorks Programmer's Guide: I/O System
creat( ) - create a file
int creat ( const char * name, /* name of the file to create */ int flag /* O_RDONLY, O_WRONLY, or O_RDWR */ )
This routine creates a file called name and opens it with a specified flag. This routine determines on which device to create the file; it then calls the create routine of the device driver to do most of the work. Therefore, much of what transpires is device/driver-dependent.
The parameter flag is set to O_RDONLY (0), O_WRONLY (1), or O_RDWR (2) for the duration of time the file is open. To create NFS files with a UNIX chmod-type file mode, call open( ) with the file mode specified in the third argument.
For more information about situations when there are no file descriptors available, see the manual entry for iosInit( ).
A file descriptor number, or ERROR if a filename is not specified, the device does not exist, no file descriptors are available, or the driver returns ERROR.
unlink( ) - delete a file (POSIX)
STATUS unlink ( char * name /* name of the file to remove */ )
This routine deletes a specified file. It performs the same function as remove( ) and is provided for POSIX compatibility.
OK if there is no delete routine for the device or the driver returns OK; ERROR if there is no such device or the driver returns ERROR.
remove( ) - remove a file (ANSI)
STATUS remove ( const char * name /* name of the file to remove */ )
This routine deletes a specified file. It calls the driver for the particular device on which the file is located to do the work.
OK if there is no delete routine for the device or the driver returns OK; ERROR if there is no such device or the driver returns ERROR.
ioLib, American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: Input/Output (stdio.h),
open( ) - open a file
int open ( const char * name, /* name of the file to open */ int flags, /* O_RDONLY, O_WRONLY, O_RDWR, or O_CREAT */ int mode /* mode of file to create (UNIX chmod style) */ )
This routine opens a file for reading, writing, or updating, and returns a file descriptor for that file. The arguments to open( ) are the filename and the type of access:
In general, open( ) can only open pre-existing devices and files. However, for NFS network devices only, files can also be created with open( ) by performing a logical OR operation with O_CREAT and the flags argument. In this case, the file is created with a UNIX chmod-style file mode, as indicated with mode. For example:
O_RDONLY (0) (or READ) - open for reading only. O_WRONLY (1) (or WRITE) - open for writing only. O_RDWR (2) (or UPDATE) - open for reading and writing. O_CREAT (0x0200) - create a file. fd = open ("/usr/myFile", O_CREAT | O_RDWR, 0644);Only the NFS driver uses the mode argument.
For more information about situations when there are no file descriptors available, see the manual entry for iosInit( ).
A file descriptor number, or ERROR if a file name is not specified, the device does not exist, no file descriptors are available, or the driver returns ERROR.
ELOOP
VARARGS2
close( ) - close a file
STATUS close ( int fd /* file descriptor to close */ )
This routine closes the specified file and frees the file descriptor. It calls the device driver to do the work.
The status of the driver close routine, or ERROR if the file descriptor is invalid.
rename( ) - change the name of a file
int rename ( const char * oldname, /* name of file to rename */ const char * newname /* name with which to rename file */ )
This routine changes the name of a file from oldfile to newfile.
Only certain devices support rename( ). To confirm that your device supports it, consult the respective xxDrv or xxFs listings to verify that ioctl FIORENAME exists. For example, dosFs and rt11Fs support rename( ), but netDrv and nfsDrv do not.
OK, or ERROR if the file could not be opened or renamed.
read( ) - read bytes from a file or device
int read ( int fd, /* file descriptor from which to read */ char * buffer, /* pointer to buffer to receive bytes */ size_t maxbytes /* max no. of bytes to read into buffer */ )
This routine reads a number of bytes (less than or equal to maxbytes) from a specified file descriptor and places them in buffer. It calls the device driver to do the work.
The number of bytes read (between 1 and maxbytes, 0 if end of file), or ERROR if the file descriptor does not exist, the driver does not have a read routines, or the driver returns ERROR. If the driver does not have a read routine, errno is set to ENOTSUP.
write( ) - write bytes to a file
int write ( int fd, /* file descriptor on which to write */ char * buffer, /* buffer containing bytes to be written */ size_t nbytes /* number of bytes to write */ )
This routine writes nbytes bytes from buffer to a specified file descriptor fd. It calls the device driver to do the work.
The number of bytes written (if not equal to nbytes, an error has occurred), or ERROR if the file descriptor does not exist, the driver does not have a write routine, or the driver returns ERROR. If the driver does not have a write routine, errno is set to ENOTSUP.
ioctl( ) - perform an I/O control function
int ioctl ( int fd, /* file descriptor */ int function, /* function code */ int arg /* arbitrary argument */ )
This routine performs an I/O control function on a device. The control functions used by VxWorks device drivers are defined in the header file ioLib.h. Most requests are passed on to the driver for handling. Since the availability of ioctl( ) functions is driver-specific, these functions are discussed separately in tyLib, pipeDrv, nfsDrv, dosFsLib, rt11FsLib, and rawFsLib.
The following example renames the file or directory to the string "newname":
ioctl (fd, FIORENAME, "newname");Note that the function FIOGETNAME is handled by the I/O interface level and is not passed on to the device driver itself. Thus this function code value should not be used by customer-written drivers.
The return value of the driver, or ERROR if the file descriptor does not exist.
ioLib, tyLib, pipeDrv, nfsDrv, dosFsLib, rt11FsLib, rawFsLib, VxWorks Programmer's Guide: I/O System, Local File Systems
VARARGS2
lseek( ) - set a file read/write pointer
int lseek ( int fd, /* file descriptor */ long offset, /* new byte offset to seek to */ int whence /* relative file position */ )
This routine sets the file read/write pointer of file fd to offset. The argument whence, which affects the file position pointer, has three values:
This routine calls ioctl( ) with functions FIOWHERE, FIONREAD, and FIOSEEK.
SEEK_SET (0) - set to offset SEEK_CUR (1) - set to current position plus offset SEEK_END (2) - set to the size of the file plus offset
The new offset from the beginning of the file, or ERROR.
SEE ALSO ioLib
ioDefPathSet( ) - set the current default path
STATUS ioDefPathSet ( char * name /* name of the new default device and path */ )
This routine sets the default I/O path. All relative pathnames specified to the I/O system will be prepended with this pathname. This pathname must be an absolute pathname, i.e., name must begin with an existing device name.
OK, or ERROR if the first component of the pathname is not an existing device.
ioLib, ioDefPathGet( ), chdir( ), getcwd( )
ioDefPathGet( ) - get the current default path
void ioDefPathGet ( char * pathname /* where to return the name */ )
This routine copies the name of the current default path to pathname. The parameter pathname should be MAX_FILENAME_LENGTH characters long.
N/A
ioLib, ioDefPathSet( ), chdir( ), getcwd( )
chdir( ) - set the current default path
STATUS chdir ( char * pathname /* name of the new default path */ )
This routine sets the default I/O path. All relative pathnames specified to the I/O system will be prepended with this pathname. This pathname must be an absolute pathname, i.e., name must begin with an existing device name.
OK, or ERROR if the first component of the pathname is not an existing device.
ioLib, ioDefPathSet( ), ioDefPathGet( ), getcwd( )
getcwd( ) - get the current default path (POSIX)
char *getcwd ( char * buffer, /* where to return the pathname */ int size /* size in bytes of buffer */ )
This routine copies the name of the current default path to buffer. It provides the same functionality as ioDefPathGet( ) and is provided for POSIX compatibility.
A pointer to the supplied buffer, or NULL if size is too small to hold the current default path.
ioLib, ioDefPathSet( ), ioDefPathGet( ), chdir( )
getwd( ) - get the current default path
char *getwd ( char * pathname /* where to return the pathname */ )
This routine copies the name of the current default path to pathname. It provides the same functionality as ioDefPathGet( ) and getcwd( ). It is provided for compatibility with some older UNIX systems.
The parameter pathname should be MAX_FILENAME_LENGTH characters long.
A pointer to the resulting path name.
ioGlobalStdSet( ) - set the file descriptor for global standard input/output/error
void ioGlobalStdSet ( int stdFd, /* std input (0), output (1), or error (2) */ int newFd /* new underlying file descriptor */ )
This routine changes the assignment of a specified global standard file descriptor stdFd (0, 1, or, 2) to the specified underlying file descriptor newFd. newFd should be a file descriptor open to the desired device or file. All tasks will use this new assignment when doing I/O to stdFd, unless they have specified a task-specific standard file descriptor (see ioTaskStdSet( )). If stdFd is not 0, 1, or 2, this routine has no effect.
N/A
ioLib, ioGlobalStdGet( ), ioTaskStdSet( )
ioGlobalStdGet( ) - get the file descriptor for global standard input/output/error
int ioGlobalStdGet ( int stdFd /* std input (0), output (1), or error (2) */ )
This routine returns the current underlying file descriptor for global standard input, output, and error.
The underlying global file descriptor, or ERROR if stdFd is not 0, 1, or 2.
ioLib, ioGlobalStdSet( ), ioTaskStdGet( )
ioTaskStdSet( ) - set the file descriptor for task standard input/output/error
void ioTaskStdSet ( int taskId, /* task whose std fd is to be set (0 = self) */ int stdFd, /* std input (0), output (1), or error (2) */ int newFd /* new underlying file descriptor */ )
This routine changes the assignment of a specified task-specific standard file descriptor stdFd (0, 1, or, 2) to the specified underlying file descriptornewFd. newFd should be a file descriptor open to the desired device or file. The calling task will use this new assignment when doing I/O to stdFd, instead of the system-wide global assignment which is used by default. If stdFd is not 0, 1, or 2, this routine has no effect.
This routine has no effect if it is called at interrupt level.
N/A
ioLib, ioGlobalStdGet( ), ioTaskStdGet( )
ioTaskStdGet( ) - get the file descriptor for task standard input/output/error
int ioTaskStdGet ( int taskId, /* ID of desired task (0 = self) */ int stdFd /* std input (0), output (1), or error (2) */ )
This routine returns the current underlying file descriptor for task-specific standard input, output, and error.
The underlying file descriptor, or ERROR if stdFd is not 0, 1, or 2, or the routine is called at interrupt level.
ioLib, ioGlobalStdGet( ), ioTaskStdSet( )
isatty( ) - return whether the underlying driver is a tty device
BOOL isatty ( int fd /* file descriptor to check */ )
This routine simply invokes the ioctl( ) function FIOISATTY on the specified file descriptor.
TRUE, or FALSE if the driver does not indicate a tty device.