Nut/OS  4.10.3
API Reference
Low Level I/O

Low level input and output operations. More...

Collaboration diagram for Low Level I/O:

Defines

#define _O_RDONLY   0x0000
#define _O_WRONLY   0x0001
#define _O_RDWR   0x0002
#define _O_APPEND   0x0008
#define _O_CREAT   0x0100
#define _O_TRUNC   0x0200
#define _O_EXCL   0x0400
#define _O_TEXT   0x4000
#define _O_BINARY   0x8000
#define IOCTL_GETSTATUS   0x0001
#define IOCTL_SETSTATUS   0x0002
#define IOCTL_SETBUFFERMODE   0x0003
#define IOCTL_GETBUFFERMODE   0x0004
#define IOCTL_GETOUTBUFSIZE   0x0005
#define IOCTL_SETOUTBUFSIZE   0x0006
#define IOCTL_GETINBUFSIZE   0x0007
#define IOCTL_SETINBUFSIZE   0x0008
#define IOCTL_FLUSHOUTBUF   0x0009
 Flush the output buffer.
#define IOCTL_GETFILESIZE   0x000A
 Return the number of bytes currently available in the input buffer.
#define IOCTL_GETOUTBUFCOUNT   0x000B
 Return the number of bytes currently available in the input buffer.
#define IOCTL_GETINBUFCOUNT   0x000C
 Return the number of bytes currently available in the output buffer.

Functions

int _close (int fd)
 Close a file, device or socket.
long _filelength (int fd)
 Return the length of a file.
int _ioctl (int fd, int cmd, void *data)
 Perform device specific control functions.
int _open (CONST char *name, int mode)
 Open a file.
int _read (int fd, void *buffer, unsigned int count)
 Read data from a file, device or socket.
int _seek (int fd, long offset, int origin)
 Move read/write position of a file.
long _tell (int fd)
 Return the read/write position of a stream.
int _write (int fd, CONST void *data, unsigned int count)
 Write data to a file, device or socket.
int _write_P (int fd, PGM_P data, unsigned int count)
 Writes data from program space to a file, device or socket.

Detailed Description

Low level input and output operations.

 #include <io.h> 

Standard C runtime file interface to Nut/OS devices.


Define Documentation

#define _O_RDONLY   0x0000

Read only.

Definition at line 76 of file fcntl.h.

Referenced by _fmode(), NutFtpTransferFile(), PhatDirOpen(), PhatDirRemove(), and UsartOpen().

#define _O_WRONLY   0x0001

Write only.

Definition at line 77 of file fcntl.h.

Referenced by _fmode(), NutInit(), UsartOpen(), and VsCodecOpen().

#define _O_RDWR   0x0002

Read and write.

Examples:
ftpd/ftpserv.c, httpd/httpserv.c, and pppc/pppc.c.

Definition at line 78 of file fcntl.h.

Referenced by _fmode(), main(), PerCiDump(), PerCiInit(), PerCiOpen(), and PhatDirCreate().

#define _O_APPEND   0x0008

Start writing at the end.

Definition at line 79 of file fcntl.h.

Referenced by _fmode(), and PhatFileOpen().

#define _O_CREAT   0x0100

Create file if it does not exist.

Definition at line 80 of file fcntl.h.

Referenced by _fmode(), NutFtpTransferFile(), NutInit(), PerCiInit(), PhatDirCreate(), and PhatFileOpen().

#define _O_TRUNC   0x0200

Truncate file if it exists.

Definition at line 81 of file fcntl.h.

Referenced by _fmode(), NutFtpTransferFile(), NutInit(), PerCiInit(), and PhatFileOpen().

#define _O_EXCL   0x0400

Open only if it does not exist.

Definition at line 82 of file fcntl.h.

Referenced by PhatDirCreate(), and PhatFileOpen().

#define _O_TEXT   0x4000

EOL translation.

Definition at line 83 of file fcntl.h.

Referenced by _fdopen(), _fmode(), fopen(), and freopen().

#define _O_BINARY   0x8000
#define IOCTL_GETSTATUS   0x0001

Definition at line 66 of file io.h.

#define IOCTL_SETSTATUS   0x0002

Definition at line 67 of file io.h.

#define IOCTL_SETBUFFERMODE   0x0003

Definition at line 68 of file io.h.

#define IOCTL_GETBUFFERMODE   0x0004

Definition at line 69 of file io.h.

#define IOCTL_GETOUTBUFSIZE   0x0005

Definition at line 70 of file io.h.

#define IOCTL_SETOUTBUFSIZE   0x0006

Definition at line 71 of file io.h.

#define IOCTL_GETINBUFSIZE   0x0007

Definition at line 72 of file io.h.

#define IOCTL_SETINBUFSIZE   0x0008

Definition at line 73 of file io.h.

#define IOCTL_FLUSHOUTBUF   0x0009

Flush the output buffer.

Currently not provided by any known device.

Definition at line 78 of file io.h.

#define IOCTL_GETFILESIZE   0x000A

Return the number of bytes currently available in the input buffer.

Definition at line 81 of file io.h.

Referenced by _filelength(), and NutTcpDeviceIOCtl().

#define IOCTL_GETOUTBUFCOUNT   0x000B

Return the number of bytes currently available in the input buffer.

Definition at line 84 of file io.h.

Referenced by NutTcpDeviceIOCtl().

#define IOCTL_GETINBUFCOUNT   0x000C

Return the number of bytes currently available in the output buffer.

Definition at line 87 of file io.h.

Referenced by NutTcpDeviceIOCtl().


Function Documentation

int _close ( int  fd)

Close a file, device or socket.

The calling thread may be suspended until all buffered output data has been written.

Parameters:
fdDescriptor of a previously opened file, device or connected socket.
Returns:
0 if the file was successfully closed or -1 to indicate an error.

Definition at line 75 of file close.c.

References _NUTDEVICE::dev_close, _NUTFILE::nf_dev, NUTASSERT, and _NUTVIRTUALDEVICE::vdv_write.

Referenced by fclose(), NutFtpTransferFile(), PerCiClose(), PerCiDump(), PerCiInit(), and PerCiOpen().

long _filelength ( int  fd)

Return the length of a file.

Parameters:
fdDescriptor of a previously opened file, device or connected socket.
Returns:
Filelength in bytes or -1 in case of an error.

Definition at line 87 of file filelength.c.

References _NUTDEVICE::dev_size, EBADF, errno, IOCTL_GETFILESIZE, _NUTFILE::nf_dev, NUTASSERT, and _NUTVIRTUALDEVICE::vdv_ioctl.

Referenced by kbhit(), NutHttpProcessAsp(), PerCiDump(), and PerCiOpen().

int _ioctl ( int  fd,
int  cmd,
void *  data 
)

Perform device specific control functions.

Check the specific device driver for a list of supported control functions.

Parameters:
fdDescriptor of a previously opened device or connected socket.
cmdRequested control function.
dataPoints to a buffer that contains any data required for the given control function or receives data from that function.

Definition at line 80 of file ioctl.c.

References _NUTDEVICE::dev_ioctl, _NUTFILE::nf_dev, NUTASSERT, and _NUTVIRTUALDEVICE::vdv_ioctl.

Referenced by InitDebugDevice(), IpcpLowerDown(), main(), NutChatSend(), and NutNetIfConfig2().

int _open ( CONST char *  name,
int  mode 
)

Open a file.

Parameters:
nameThe name of a registered device, optionally followed by a colon and a filename.
modeOperation mode. May be any of the following:
  • _O_APPEND Always write at the end.
  • _O_BINARY Raw mode.
  • _O_CREAT Create file if it does not exist.
  • _O_EXCL Open only if it does not exist.
  • _O_RDONLY Read only.
  • _O_RDWR Read and write.
  • _O_TEXT End of line translation.
  • _O_TRUNC Truncate file if it exists.
  • _O_WRONLY Write only.
Returns:
File descriptor for the opened file or -1 to indicate an error.

Definition at line 94 of file open.c.

References CONST, _NUTDEVICE::dev_open, ENOENT, errno, NUTASSERT, and NutDeviceLookup().

Referenced by fopen(), freopen(), main(), NutFtpTransferFile(), PerCiDump(), PerCiInit(), and PerCiOpen().

Here is the call graph for this function:

int _read ( int  fd,
void *  buffer,
unsigned int  count 
)

Read data from a file, device or socket.

Parameters:
fdDescriptor of a previously opened file, device or connected socket.
bufferPointer to the buffer that receives the data.
countMaximum number of bytes to read.
Returns:
The number of bytes read, which may be less than the number of bytes specified. A return value of -1 indicates an error.

Definition at line 75 of file read.c.

References _NUTDEVICE::dev_read, _NUTFILE::nf_dev, NUTASSERT, and _NUTVIRTUALDEVICE::vdv_read.

int _seek ( int  fd,
long  offset,
int  origin 
)

Move read/write position of a file.

Parameters:
fdDescriptor of a previously opened file, device or connected socket.
offsetNumber of bytes from initial position.
originInitial position to seek from.
Returns:
0 if no error occured -1 on error. errno is set

Definition at line 73 of file seek.c.

References IOCTL_ARG3::arg1, IOCTL_ARG3::arg2, IOCTL_ARG3::arg3, _NUTDEVICE::dev_ioctl, EINVAL, errno, FS_FILE_SEEK, _NUTFILE::nf_dev, and NUTASSERT.

Referenced by fseek(), PerCiFlush(), PerCiOpen(), and PerCiWrite().

long _tell ( int  fd)

Return the read/write position of a stream.

Parameters:
fdDescriptor of a previously opened file, device or connected socket.
Returns:
The current position or -1 on error.

Definition at line 70 of file tell.c.

References IOCTL_ARG3::arg1, IOCTL_ARG3::arg2, IOCTL_ARG3::arg3, _NUTDEVICE::dev_ioctl, EINVAL, errno, FS_FILE_SEEK, _NUTFILE::nf_dev, NUTASSERT, and SEEK_CUR.

Referenced by ftell().

int _write ( int  fd,
CONST void *  data,
unsigned int  count 
)

Write data to a file, device or socket.

Parameters:
fdDescriptor of a previously opened file, device or connected socket.
dataPointer to data in program space to be written.
countNumber of bytes to write.
Returns:
The number of bytes written, which may be less than the number of bytes specified. A return value of -1 indicates an error.
Note:
The write implementation of the underlying driver does not need to be thread-safe. Parallel writes using device usartavr will lead to intermixed data (if data doesn't fit into ringbuffer on the first try )

Definition at line 84 of file write.c.

References _NUTDEVICE::dev_write, _NUTFILE::nf_dev, NUTASSERT, and _NUTVIRTUALDEVICE::vdv_write.

int _write_P ( int  fd,
PGM_P  data,
unsigned int  count 
)

Writes data from program space to a file, device or socket.

Similar to _write() except that the data is located in program memory.

Parameters:
fdDescriptor of a previously opened file, device or connected socket.
dataPointer to data in program space to be written.
countNumber of bytes to write.
Returns:
The number of bytes written, which may be less than the number of bytes specified. A return value of -1 indicates an error.
Note:
The write implementation of the underlying driver does not need to be thread-safe. Parallel writes using device usartavr will lead to intermixed data (if data doesn't fit into ringbuffer on the first try )

Definition at line 87 of file write_p.c.

References _NUTDEVICE::dev_write_P, _NUTFILE::nf_dev, NUTASSERT, and _NUTVIRTUALDEVICE::vdv_write_P.