User API
[Real-Time Driver Model]

---

Detailed Description

This is the upper interface of RTDM provided to application programs both in kernel and user space. Note that certain functions may not be implemented by every device. Refer to the Device Profiles for precise information.

Files
file	rtdm.h
	Real-Time Driver Model for Xenomai, user API header.
Functions
int	rt_dev_open (const char *path, int oflag,...)
	Open a device.
int	rt_dev_socket (int protocol_family, int socket_type, int protocol)
	Create a socket.
int	rt_dev_close (int fd)
	Close a device or socket.
int	rt_dev_ioctl (int fd, int request,...)
	Issue an IOCTL.
ssize_t	rt_dev_read (int fd, void *buf, size_t nbyte)
	Read from device.
ssize_t	rt_dev_write (int fd, const void *buf, size_t nbyte)
	Write to device.
ssize_t	rt_dev_recvmsg (int fd, struct msghdr *msg, int flags)
	Receive message from socket.
ssize_t	rt_dev_recvfrom (int fd, void *buf, size_t len, int flags, struct sockaddr *from, socklen_t *fromlen)
	Receive message from socket.
ssize_t	rt_dev_recv (int fd, void *buf, size_t len, int flags)
	Receive message from socket.
ssize_t	rt_dev_sendmsg (int fd, const struct msghdr *msg, int flags)
	Transmit message to socket.
ssize_t	rt_dev_sendto (int fd, const void *buf, size_t len, int flags, const struct sockaddr *to, socklen_t tolen)
	Transmit message to socket.
ssize_t	rt_dev_send (int fd, const void *buf, size_t len, int flags)
	Transmit message to socket.
int	rt_dev_bind (int fd, const struct sockaddr *my_addr, socklen_t addrlen)
	Bind to local address.
int	rt_dev_connect (int fd, const struct sockaddr *serv_addr, socklen_t addrlen)
	Connect to remote address.
int	rt_dev_listen (int fd, int backlog)
	Listen for incomming connection requests.
int	rt_dev_accept (int fd, struct sockaddr *addr, socklen_t *addrlen)
	Accept a connection requests.
int	rt_dev_shutdown (int fd, int how)
	Shut down parts of a connection.
int	rt_dev_getsockopt (int fd, int level, int optname, void *optval, socklen_t *optlen)
	Get socket option.
int	rt_dev_setsockopt (int fd, int level, int optname, const void *optval, socklen_t optlen)
	Set socket option.
int	rt_dev_getsockname (int fd, struct sockaddr *name, socklen_t *namelen)
	Get local socket address.
int	rt_dev_getpeername (int fd, struct sockaddr *name, socklen_t *namelen)
	Get socket destination address.

---

Function Documentation

int rt_dev_accept (  int  fd, struct sockaddr *  addr, socklen_t *  addrlen )

Accept a connection requests. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [out]  addr  Buffer for remote address [in,out]  addrlen  Address buffer size Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: accept() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_bind (  int  fd, const struct sockaddr *  my_addr, socklen_t  addrlen )

Bind to local address. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  my_addr  Address buffer [in]  addrlen  Address buffer size Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: bind() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_close (  int  fd  )

Close a device or socket. Parameters: [in]  fd  File descriptor as returned by rt_dev_open() or rt_dev_socket() Returns: 0 on success, otherwise a negative error code. Note: If the matching rt_dev_open() or rt_dev_socket() call took place in non-real-time context, rt_dev_close() must be issued within non-real-time as well. Otherwise, the call will fail. Killing a real-time task that is blocked on some device operation can lead to stalled file descriptors. To avoid such scenarios, always close the device before explicitely terminating any real-time task which may use it. To cleanup a stalled file descriptor, send its number to the open_fildes /proc entry, e.g. via #> echo 3 > /proc/xenomai/rtdm/open_fildes Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: close() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_connect (  int  fd, const struct sockaddr *  serv_addr, socklen_t  addrlen )

Connect to remote address. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  serv_addr  Address buffer [in]  addrlen  Address buffer size Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: connect() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_getpeername (  int  fd, struct sockaddr *  name, socklen_t *  namelen )

Get socket destination address. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [out]  name  Address buffer [in,out]  namelen  Address buffer size Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: getpeername() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_getsockname (  int  fd, struct sockaddr *  name, socklen_t *  namelen )

Get local socket address. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [out]  name  Address buffer [in,out]  namelen  Address buffer size Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: getsockname() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_getsockopt (  int  fd, int  level, int  optname, void *  optval, socklen_t *  optlen )

Get socket option. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  level  Addressed stack level [in]  optname  Option name ID [out]  optval  Value buffer [in,out]  optlen  Value buffer size Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: getsockopt() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_ioctl (  int  fd, int  request,   ... )

Issue an IOCTL. Parameters: [in]  fd  File descriptor as returned by rt_dev_open() or rt_dev_socket() [in]  request  IOCTL code ...  Optional third argument, depending on IOCTL function (void * or unsigned long) Returns: Positiv value on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: ioctl() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_listen (  int  fd, int  backlog )

Listen for incomming connection requests. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  backlog  Maximum queue length Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: lsiten() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_open (  const char *  path, int  oflag,   ... )

Open a device. Parameters: [in]  path  Device name [in]  oflag  Open flags ...  Further parameters will be ignored. Returns: Positive file descriptor value on success, otherwise a negative error code. Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: open() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_read (  int  fd, void *  buf, size_t  nbyte )

Read from device. Parameters: [in]  fd  File descriptor as returned by rt_dev_open() [out]  buf  Input buffer [in]  nbyte  Number of bytes to read Returns: Number of bytes read, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: read() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_recv (  int  fd, void *  buf, size_t  len, int  flags )

Receive message from socket. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [out]  buf  Message buffer [in]  len  Message buffer size [in]  flags  Message flags Returns: Number of bytes received, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: recv() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_recvfrom (  int  fd, void *  buf, size_t  len, int  flags, struct sockaddr *  from, socklen_t *  fromlen )

Receive message from socket. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [out]  buf  Message buffer [in]  len  Message buffer size [in]  flags  Message flags [out]  from  Buffer for message sender address [in,out]  fromlen  Address buffer size Returns: Number of bytes received, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: recvfrom() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_recvmsg (  int  fd, struct msghdr *  msg, int  flags )

Receive message from socket. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in,out]  msg  Message descriptor [in]  flags  Message flags Returns: Number of bytes received, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: recvmsg() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_send (  int  fd, const void *  buf, size_t  len, int  flags )

Transmit message to socket. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  buf  Message buffer [in]  len  Message buffer size [in]  flags  Message flags Returns: Number of bytes sent, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: send() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_sendmsg (  int  fd, const struct msghdr *  msg, int  flags )

Transmit message to socket. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  msg  Message descriptor [in]  flags  Message flags Returns: Number of bytes sent, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: sendmsg() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_sendto (  int  fd, const void *  buf, size_t  len, int  flags, const struct sockaddr *  to, socklen_t  tolen )

Transmit message to socket. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  buf  Message buffer [in]  len  Message buffer size [in]  flags  Message flags [in]  to  Buffer for message destination address [in]  tolen  Address buffer size Returns: Number of bytes sent, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: sendto() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_setsockopt (  int  fd, int  level, int  optname, const void *  optval, socklen_t  optlen )

Set socket option. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  level  Addressed stack level [in]  optname  Option name ID [in]  optval  Value buffer [in]  optlen  Value buffer size Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: setsockopt() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_shutdown (  int  fd, int  how )

Shut down parts of a connection. Parameters: [in]  fd  File descriptor as returned by rt_dev_socket() [in]  how  Specifies the part to be shut down (SHUT_xxx) Returns: 0 on success, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: shutdown() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

int rt_dev_socket (  int  protocol_family, int  socket_type, int  protocol )

Create a socket. Parameters: [in]  protocol_family  Protocol family (PF_xxx) [in]  socket_type  Socket type (SOCK_xxx) [in]  protocol  Protocol ID, 0 for default Returns: Positive file descriptor value on success, otherwise a negative error code. Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: socket() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

ssize_t rt_dev_write (  int  fd, const void *  buf, size_t  nbyte )

Write to device. Parameters: [in]  fd  File descriptor as returned by rt_dev_open() [in]  buf  Output buffer [in]  nbyte  Number of bytes to write Returns: Number of bytes written, otherwise negative error code Environments: Depends on driver implementation, see Device Profiles. Rescheduling: possible. See also: write() in IEEE Std 1003.1, http://www.opengroup.org/onlinepubs/009695399

---