fdops.h File Reference

File-descriptor types and declarations to support newlib. More...

#include <bspacm/core.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdarg.h>

Go to the source code of this file.

Data Structures
struct	sBSPACMnewlibFDOPSfileOps
struct	sBSPACMnewlibFDOPSfile

Typedefs
typedef struct sBSPACMnewlibFDOPSfile *	hBSPACMnewlibFDOPSfile
typedef hBSPACMnewlibFDOPSfile(*	fBSPACMnewlibFDOPSdriver) (const char *pathname, int flags)
typedef struct sBSPACMnewlibFDOPSfileOps	sBSPACMnewlibFDOPSfileOps
typedef struct sBSPACMnewlibFDOPSfile	sBSPACMnewlibFDOPSfile

Functions
void	vBSPACMnewlibFDOPSinitializeStdio_ (void)

Variables
const fBSPACMnewlibFDOPSdriver	xBSPACMnewlibFDOPSdriver []
hBSPACMnewlibFDOPSfile	xBSPACMnewlibFDOPSfile_ []
const uint8_t	nBSPACMnewlibFDOPSfile
hBSPACMnewlibFDOPSfile const	hBSPACMnewlibFDOPSfileRESERVED

Detailed Description

File-descriptor types and declarations to support newlib.

Homepage

http://github.com/pabigot/bspacm

Copyright

Copyright 2014, Peter A. Bigot. Licensed under BSD-3-Clause

Typedef Documentation

typedef hBSPACMnewlibFDOPSfile(* fBSPACMnewlibFDOPSdriver) (const char *pathname, int flags)

Signature of a the open function for a driver that supports the file-descriptor options of newlib.

An implementation of this function is provided for each driver supported by an application/environment, by linking an xBSPACMnewlibFDOPSdriver table that holds drivers in order of trial.

The newlib open() function invokes each driver in turn to see if it can create a handle for a file object, given the pathname and flags. The open succeeds only if such a file can be created.

Note

This function probably dynamically allocates the file object.

Parameters

pathname	the path to the device. For example, "/dev/uart2" might be used to identify the third UART device available on the platform.
flags	the standard flags from <fcntl.h> that describe how the device should be opened.

Returns

a pointer to a file object that can be used to interact with the device, or a null pointer if the driver is unable to open pathname with flags.

typedef sBSPACMnewlibFDOPSfile * hBSPACMnewlibFDOPSfile

Handle for the generic object that implements the file-descriptor–based operations of newlib.

typedef struct sBSPACMnewlibFDOPSfile sBSPACMnewlibFDOPSfile

Record for the state associated with a file descriptor.

typedef struct sBSPACMnewlibFDOPSfileOps sBSPACMnewlibFDOPSfileOps

Record for the implementations of file descriptor operations that are supported for a particular class of device.

Each operation has the standard POSIX environment interface and semantics, except that a hBSPACMnewlibFDOPSfile is passed instead of a descriptor.

The pointer to any operation may be null; if the corresponding operation is invoked the wrapper function will return an error after setting errno to EBADF (generally; some operations may use an alternative error code).

Function Documentation

void vBSPACMnewlibFDOPSinitializeStdio_

(

void

)

Function to initialize descriptors used by stdio.

newlib expects stdin (descriptor 0), stdout (1), and stderr (2) to be immediately available for use, but does not open them or associate them with a device. To ensure the C library descriptors are consistent with the handles in xBSPACMnewlibFDOPSfile_, the first invocation of any file-descriptor operation will initialize handles associated with these descriptors. That is done by this function.

The check for stdio being initialized is bypassed for calls to file descriptor operations invoked by this function. Consequently, implementations of this function may use open(), so long as the resulting descriptors end up as 0, 1, and 2 with their required properties.

Weakly Defined

The newlib_fdops library provides a weak default implementation of this, which opens /dev/console three times with parameters appropriate for stdin, stdout, and stderr, closing the corresponding descriptors first to ensure the association with the file handle is correct. If something goes wrong it uses hBSPACMnewlibFDOPSfileRESERVED to prevent the descriptors from being unintentionally used in subsequent open() calls.

Note

This function may be overridden by the application, but need not be. It should never be explicitly invoked by the application; it is documented solely to describe the infrastructure requirements for any overriding implementation.

Although the implementation will open the three standard descriptors, applications are permitted to close any or all of them, based on their needs. The corresponding slots in xBSPACMnewlibFDOPSfile_ will then be available for use as normal descriptors or as the standard ones.

Variable Documentation

hBSPACMnewlibFDOPSfile const hBSPACMnewlibFDOPSfileRESERVED

Handle for a file that supports no operations except closing it. This is used by implementations of vBSPACMnewlibFDOPSinitializeStdio() to reserve descriptors 0, 1, and 2 when the application has no device to support them. The application can then close those descriptors and re-use them.

const uint8_t nBSPACMnewlibFDOPSfile

The number of elements in xBSPACMnewlibFDOPSfile_. This is the array length, not the number of descriptors in use.

Weakly Defined

A weak definition with value 3, corresponding to the stdio descriptors, is provided in the newlib_fdops library, but should be overridden by any application that provides an alternative xBSPACMnewlibFDOPSfile_ definition.

See also

xBSPACMnewlibFDOPSfile_

const fBSPACMnewlibFDOPSdriver xBSPACMnewlibFDOPSdriver[]

A list of drivers supported by the infrastructure. The list of drivers must end with a null pointer.

The open() call will iterate through these in order to find a driver capable of creating a file descriptor based on the parameters to the open call.

Weakly Defined

The console capability provides a weak definition for this that supports only fBSPACMnewlibFDOPSdriverConsole(). Applications that intend to combine console support with other drivers must provide an alternative implementation to override this. Applications that need file descriptor operations but do not use the console capability must provide an implementation.

hBSPACMnewlibFDOPSfile xBSPACMnewlibFDOPSfile_[]

Array of handles to active file descriptor states. These should be in one-to-one correspondence with the set of file descriptors maintained by newlib. Elements of the array are null if the descriptor associated with the index is inactive. The least open index is used as the descriptor for the next successful open operation.

Generally applications should never need to examine this array. However, they do need to ensure presence of a definition that has sufficient room for the descriptors required by the application.

Weakly Defined

A weak definition for a three-element array is provided in the newlib_fdops library; this is sufficient for the stdio descriptors.

See also

nBSPACMnewlibFDOPSfile