Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NETGRAPH(3)		 BSD Library Functions Manual		   NETGRAPH(3)

     NgMkSockNode, NgNameNode, NgSendMsg, NgRecvMsg, NgSendData, NgRecvData,
     NgSetDebug, NgSetErrLog --	netgraph user library

     Netgraph User Library (libnetgraph, -lnetgraph)

     #include <netgraph.h>

     NgMkSockNode(const	char *name, int	*csp, int *dsp);

     NgNameNode(int cs,	const char *path, const	char *fmt, ...);

     NgSendMsg(int cs, const char *path, int cookie, int cmd, const void *arg,
	 size_t	arglen);

     NgSendAsciiMsg(int	cs, const char *path, const char *fmt, ...);

     NgSendMsgReply(int	cs, const char *path, struct ng_mesg *msg,
	 const void *arg, size_t arglen);

     NgRecvMsg(int cs, struct ng_mesg *rep, size_t replen, char	*path);

     NgRecvAsciiMsg(int	cs, struct ng_mesg *rep, size_t	replen,	char *path);

     NgSendData(int ds,	const char *hook, const	u_char *buf, size_t len);

     NgRecvData(int ds,	u_char *buf, size_t len, char *hook);

     NgSetDebug(int level);

     NgSetErrLog(void (*log)(const char	*fmt, ...),
	 void (*logx)(const char *fmt, ...));

     These functions facilitate	user-mode program participation	in the kernel
     netgraph(4) graph-based networking	system,	by utilizing the netgraph
     socket node type (see ng_socket(4)).

     NgMkSockNode() should be called first, to create a	new socket type	net-
     graph node	with associated	control	and data sockets.  If name is non-
     NULL, the node will have that global name assigned	to it.	*csp and *dsp
     will be set to the	newly opened control and data sockets associated with
     the node; either csp or dsp may be	NULL if	only one socket	is desired.
     NgMkSockNode() loads the socket node type KLD if it's not already loaded.

     NgNameNode() assigns a global name	to the node addressed by path.

     NgSendMsg() sends a binary	control	message	from the socket	node associ-
     ated with control socket cs to the	node addressed by path.	 The cookie
     indicates how to interpret	cmd, which indicates a specific	command.  Ex-
     tra argument data (if any)	is specified by	arg and	arglen.	 The cookie,
     cmd, and argument data are	defined	by the header file corresponding to
     the type of the node being	addressed.  The	unique,	non-negative token
     value chosen for use in the message header	is returned.  This value is
     typically used to associate replies.

     Use NgSendMsgReply() to send reply	to a previously	received control mes-
     sage.  The	original message header	should be pointed to by	msg.

     NgSendAsciiMsg() performs the same	function as NgSendMsg(), but adds sup-
     port for ASCII encoding of	control	messages.  NgSendAsciiMsg() formats
     its input a la printf(3) and then sends the resulting ASCII string	to the
     node in a NGM_ASCII2BINARY	control	message.  The node returns a binary
     version of	the message, which is then sent	back to	the node just as with
     NgSendMsg().  As with NgSendMsg(),	the message token value	is returned.
     Note that ASCII conversion	may not	be supported by	all node types.

     NgRecvMsg() reads the next	control	message	received by the	node associ-
     ated with control socket cs.  The message and any extra argument data
     must fit in replen	bytes.	If path	is non-NULL, it	must point to a	buffer
     of	at least NG_PATHLEN + 1	bytes, which will be filled in (and NUL	termi-
     nated) with the path to the node from which the message was received.

     The length	of the control message is returned.  A return value of zero
     indicates that the	socket was closed.

     NgRecvAsciiMsg() works exactly like NgRecvMsg(), except that after	the
     message is	received, any binary arguments are converted to	ASCII by send-
     ing a NGM_BINARY2ASCII request back to the	originating node.  The result
     is	the same as NgRecvAsciiMsg(), with the exception that the reply	argu-
     ments field will contain a	NUL-terminated ASCII version of	the arguments
     (and the reply header argument length field will be adjusted).

     NgSendData() writes a data	packet out on the specified hook of the	node
     corresponding to data socket ds.  The node	must already be	connected to
     some other	node via that hook.

     NgRecvData() reads	the next data packet (of up to len bytes) received by
     the node corresponding to data socket ds and stores it in buf, which must
     be	large enough to	hold the entire	packet.	 If hook is non-NULL, it must
     point to a	buffer of at least NG_HOOKLEN +	1 bytes, which will be filled
     in	(and NUL terminated) with the name of the hook on which	the data was

     The length	of the packet is returned.  A return value of zero indicates
     that the socket was closed.

     NgSetDebug() and NgSetErrLog() are	used for debugging.  NgSetDebug() sets
     the debug level (if non-negative),	and returns the	old setting.  Higher
     debug levels result in more verbosity.  The default is zero.  All debug
     and error messages	are logged via the functions specified in the most re-
     cent call to NgSetErrLog().  The default logging functions	are vwarn(3)
     and vwarnx(3).

     At	debug level 3, the library attempts to display control message argu-
     ments in ASCII format; however, this results in additional	messages being
     sent which	may interfere with debugging.  At even higher levels, even
     these additional messages will be displayed, etc.

     Note that select(2) can be	used on	the data and the control sockets to
     detect the	presence of incoming data and control messages,	respectively.
     Data and control packets are always written and read atomically, i.e., in
     one whole piece.

     User mode programs	must be	linked with the	-lnetgraph flag	to link	in
     this library.

     To	enable Netgraph	in your	kernel,	either your kernel must	be compiled
     with "options NETGRAPH" in	the kernel configuration file, or else the
     netgraph(4) and ng_socket(4) KLD modules must have	been loaded via

     NgSetDebug() returns the previous debug setting.  NgSetErrLog() has no
     return value.  All	other functions	return -1 if there was an error	and
     set errno accordingly.  A return value of zero from NgRecvMsg() or
     NgRecvData() indicates that the netgraph socket has been closed.

     For NgSendAsciiMsg() and NgRecvAsciiMsg(),	the following additional er-
     rors are possible:

     [ENOSYS]		The node type does not know how	to encode or decode
			the control message.

     [ERANGE]		The encoded or decoded arguments were too long for the
			supplied buffer.

     [ENOENT]		An unknown structure field was seen in an ASCII	con-
			trol message.

     [EALREADY]		The same structure field was specified twice in	an
			ASCII control message.

     [EINVAL]		ASCII control message parse error or illegal value.

     [E2BIG]		ASCII control message array or fixed width string buf-
			fer overflow.

     select(2),	socket(2), warnx(3), kld(4), netgraph(4), ng_socket(4)

     The netgraph system was designed and first	implemented at Whistle Commu-
     nications,	Inc. in	a version of FreeBSD 2.2 customized for	the Whistle

     Archie Cobbs <>

BSD			       January 19, 1999				   BSD


Want to link to this manual page? Use this URL:

home | help