.\"* libvdeplug: a network namespace as a user library .\" Copyright (C) 2017 Renzo Davoli. University of Bologna. .\" .\" This library is free software; you can redistribute it and/or .\" modify it under the terms of the GNU Lesser General Public .\" License as published by the Free Software Foundation; either .\" version 2.1 of the License, or (at your option) any later version. .\" .\" This library is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU .\" Lesser General Public License for more details. .\" .\" You should have received a copy of the GNU Lesser General Public .\" License along with this library; if not, write to the Free Software .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA .TH libvdeplug 3 2017-05-21 "VirtualSquare" "Linux Programmer's Manual" .SH NAME vde_open, vde_recv, vde_send, vde_send, vde_recv, vde_close \- connect clients to a VDE (virtual distributed ethernet) network .SH SYNOPSIS .B #include .br .BI "VDECONN *vde_open(char *vde_url,char *descr, struct vde_open_args *open_args);" .br .BI "ssize_t vde_recv(VDECONN *conn,void *buf,size_t len,int flags);" .br .BI "ssize_t vde_send(VDECONN *conn,const void *buf,size_t len,int flags);" .br .BI "int vde_datafd(VDECONN *conn);" .br .BI "int vde_ctlfd(VDECONN *conn);" .br .BI "int vde_close(VDECONN *conn);" .sp These functions are provided by libvdeplug. Link with \fI-lvdeplug\fR. .SH DESCRIPTION Libvdeplug is the library used by clients to join a VDE network. It is a generic library which can use several different implementations for virtual distributed networks. In fact \fIvde_url\fR has the syntax \fImodule\fB://\fIspecific_address\fR. e.g. \fBvde:///home/user/myswitch\fR or \fBvxvde://239.0.0.1\fR. The default module is \fBlibvdeplug_vde(1)\fR (connection to a \fBvde_switch(1)\fR) and can be omitted. e.g. \fB/home/user/myswitch\fR means \fBvde:///home/user/myswitch\fR \fBvde_open\fR opens a VDE connection: \fIvde_url\fR is the vde network identifier as described here above and \fIdescr\fR is a description of this connection (it can be useful to identify this connection in the port list of a switch). \fRopen_args\fR has been left for backwards compatibility but can be safely set to NULL as all the options previosly defined as fields of \fIstruct vde_open_args\fR are now parameters of the VDE modules (can be defined using a module specific syntax in vde_url). \fBvde_recv\fR receives a packet from the VDE connection. \fBvde_send\fR sends a packet to the VDE connection. \fBvde_datafd\fR returns the data file descriptor of the connection: this descriptor can be used in \fBpoll(2)\fR or \fBselect(2)\fR (or similar) system calls. When this descriptor signals data available for reading \fBvde_recv\fR will not block. \fBvde_ctlfd\fR returns the control file descriptor of the connection. Not all the modules support control descritors, but when it is valid descriptor (greater or equal than 0) can be used to check if the remote endpoint (switch or peer) hanged up. No data can be sent or received using the control file descriptor, it returns an end-of-file condition when the connection get closed (zero length on reading). \fBvde_close\fR closes a vde connections. .SH RETURN VALUE \fBvde_open\fR returns the descriptor of the VDE connection which is used as a parameter of all the other functions. NULL is returned in case of error. \fBvde_recv\fR returns the length of the packet received. It should never be less then 14 bytes (the length of an ethernet header). It returns -1 in case of error, it may return 1 to notify that a packet has been received but it must be dropped (e.g. the sender was not allowed to send that packet). \fBvde_send\fR returns the number of bytes sent. It returns -1 in case of error. \fBvde_datafd\fR and \fBvde_ctlfd\fR returns a file descriptor and -1 in case of error. \fBvde_datafd\fR returns 0 in case of success and -1 in case of error. .SH NOTICE Virtual Distributed Ethernet is not related in any way with www.vde.com ("Verband der Elektrotechnik, Elektronik und Informationstechnik" i.e. the German "Association for Electrical, Electronic & Information Technologies"). .SH SEE ALSO \fBvde_plug\fR(1), \fBvde_switch\fR(1) .SH BUGS Bug reports should be addressed to .SH AUTHOR Renzo Davoli