FreeBSD Manual Pages

home | help
AG_NET(3)		     Library Functions Manual		       AG_NET(3)

NAME
     AG_Net -- agar network interface

SYNOPSIS
     #include <agar/core.h>

DESCRIPTION
     AG_Net  provides  a  cross-platform  interface  to network sockets, DNS and
     other  network-related  functions.   Available  backends	include   "bsd",
     "dummy",  "winsock1" and "winsock2".  The default backend is selected based
     on present platform capabilities.

NETWORK ADDRESSES
     AG_NetAddrList * AG_NetResolve(const char *hostname, const char *port, Uint
     flags)

     AG_NetAddrList * AG_NetGetIfConfig(void)

     AG_NetAddrList * AG_NetAddrListNew(void)

     void AG_NetAddrListClear(AG_NetAddrList *list)

     void AG_NetAddrListFree(AG_NetAddrList *list)

     AG_NetAddr * AG_NetAddrNew(void)

     AG_NetAddr * AG_NetAddrDup(const AG_NetAddr *a)

     int AG_NetAddrCompare(const AG_NetAddr *a, const AG_NetAddr *b)

     int AG_NetAddrIsAny(const AG_NetAddr *a)

     const char * AG_NetAddrNumerical(AG_NetAddr *a)

     void AG_NetAddrFree(AG_NetAddr *a)

     The AG_NetResolve() function looks up a specified host  hostname  and  port
     number  (or  service  name) port.	If the lookup is successful, the results
     are returned as a list of addresses.  Optional flags include:

     AG_NET_ADDRCONFIG	   Use IPv6 based on host interface status.
     AG_NET_NUMERIC_HOST   Require a hostname in numerical notation.
     AG_NET_NUMERIC_PORT   Require a numerical port number.

     The AG_NetGetIfConfig() function returns the list of  addresses  associated
     with  local  network  interfaces (i.e., the list of addresses that would be
     displayed by ifconfig(8) under Unix).  If the call is  unsupported  on  the
     present platform, the function returns NULL.

     The  AG_NetAddrList  structure  stores  a	list  of network addresses.  The
     AG_NetAddrListNew() function returns an empty, newly allocated list, AG_Ne-
     tAddrListClear() removes all addresses from the given  list  and  AG_NetAd-
     drListFree() releases all resources allocated by the list.

     The AG_NetAddr structure stores a single network address and a port number.
     The  AG_NetAddrNew() function returns a newly-allocated address.  AG_NetAd-
     drDup() returns a newly-allocated duplicate of a.

     AG_NetAddrCompare() evaluates to 0 if a and b represent  the  same  address
     and  port,  otherwise  a non-zero value (suitable for sorting) is returned.
     AG_NetAddrIsAny() returns 1 if the address represents "*" (any address).

     The AG_NetAddrNumerical() function returns a pointer to an (internally-man-
     aged) string buffer containing a numerical representation of  the	address.
     The buffer will remains valid until the AG_NetAddr is freed.

     The AG_NetAddrFree() routine destroys all resources allocated by a.

SOCKETS
     AG_NetSocket    *	  AG_NetSocketNew(enum	 ag_net_addr_family   af,   enum
     ag_net_socket_type type, int proto)

     void AG_NetSocketFree(AG_NetSocket *sock)

     int AG_NetConnect(AG_NetSocket *sock, const AG_NetAddrList *host)

     int AG_NetBind(AG_NetSocket *sock, const AG_NetAddr *addr)

     AG_NetSocket * AG_NetAccept(AG_NetSocket *sock)

     void AG_NetClose(AG_NetSocket *sock)

     int  AG_NetRead(AG_NetSocket  *sock,  void  *data,  AG_Size  size,  AG_Size
     *nRead)

     int AG_NetWrite(AG_NetSocket *sock, const void *data, AG_Size size, AG_Size
     *nWrote)

     int AG_NetGetOption(AG_NetSocket *sock, enum ag_net_socket_option opt, void
     *data)

     int  AG_NetGetOptionInt(AG_NetSocket  *sock, enum ag_net_socket_option opt,
     int *data)

     int  AG_NetSetOption(AG_NetSocket	*sock,	enum  ag_net_socket_option  opt,
     const void *data)

     int  AG_NetSetOptionInt(AG_NetSocket  *sock, enum ag_net_socket_option opt,
     int data)

     The AG_NetSocketNew() function creates an endpoint for  communication,  re-
     turning  a socket descriptor on success.  The af argument indicates the ad-
     dress family of the socket:

     AG_NET_AF_NONE   Undefined address family.
     AG_NET_LOCAL     Host-local protocols (e.g., Unix sockets)
     AG_NET_INET4     Internet version 4 address.
     AG_NET_INET6     Internet version 6 address.

     The proto argument is an optional protocol number (see protocols(5)).   The
     type argument may be set to:

     AG_NET_SOCKET_NONE   Undefined
     AG_NET_STREAM	  Stream socket
     AG_NET_DGRAM	  Datagram socket
     AG_NET_RAW 	  Raw-protocol interface
     AG_NET_RDM 	  Reliably-delivered packet
     AG_NET_SEQPACKET	  Sequenced packet stream

     The  AG_NetSocketFree()  function closes a socket, releasing all associated
     resources.

     The AG_NetConnect() call establishes a connection between sock and a remote
     host (specified as a list containing one or more addresses to try).

     The AG_NetBind() call assigns a local protocol address addr, to the  socket
     sock.   The  AG_NetAccept()  function should be called on a socket that was
     previously assigned a local address.  From the  queue  of	pending  connec-
     tions,  AG_NetAccept()  extracts the first connection request and returns a
     newly-created socket for the connection.

     The AG_NetClose() routine closes the connection on sock (without destroying
     the socket).

     The AG_NetRead() and AG_NetWrite() routines move data  between  the  socket
     and  a specified buffer data of size bytes.  On success, 0 is returned, and
     the number of bytes successfully read/written is returned in the nRead  and
     nWrite argument (which can be NULL).

     The  AG_NetGetOption() function returns the current value of the socket op-
     tion opt into data.  AG_NetSetOption() sets the specified socket option  to
     the  contents  of	data.  The AG_NetGetOptionInt() and AG_NetSetOptionInt()
     shorthands accept integer arguments  for  int  socket  options.   Available
     socket  options are as follows (unless indicated otherwise, int is the data
     type).

     AG_NET_DEBUG	   Enable debugging on the socket
     AG_NET_REUSEADDR	   Reuse local addresses
     AG_NET_KEEPALIVE	   Keep connections alive
     AG_NET_DONTROUTE	   Routing bypass for outgoing messages
     AG_NET_BROADCAST	   Transmit broadcast messages
     AG_NET_BINDANY	   Allow binding to any address
     AG_NET_SNDBUF	   Set buffer size for sending
     AG_NET_RCVBUF	   Set buffer size for receiving
     AG_NET_SNDLOWAT	   Set low watermark for sending
     AG_NET_RCVLOWAT	   Set low watermark for receiving
     AG_NET_BACKLOG	   Limit on incoming connection backlog
     AG_NET_OOBINLINE	   Receive out-of-band data inline (non-portable)
     AG_NET_REUSEPORT	   Allow address/port reuse (non-portable)
     AG_NET_TIMESTAMP	   Receive datagram timestamps (non-portable)
     AG_NET_NOSIGPIPE	   Disable generation of SIGPIPE (non-portable)
     AG_NET_LINGER	   Linger on AG_NetClose()  up	to  n  seconds	if  data
			   present (non-portable)
     AG_NET_ACCEPTFILTER   Kernel-based   accept  filter.   The  argument  is  a
			   AG_NetAcceptFilter structure (non-portable)

     The argument to AG_NET_ACCEPTFILTER is defined as follows:

     typedef struct ag_net_accept_filter {
	     char name[16];		     /* Filter module name */
	     char arg[240];		     /* Argument */
     } AG_NetAcceptFilter;

POLLING AND SOCKET SETS
     void AG_NetSocketSetInit(AG_NetSocketSet *set)

     void AG_NetSocketSetClear(AG_NetSocketSet *set)

     void AG_NetSocketSetFree(AG_NetSocketSet *set)

     int AG_NetPoll(AG_NetSocketSet *nsInput, AG_NetSocketSet  *nsRead,  AG_Net-
     SocketSet *nsWrite, AG_NetSocketSet *nsException, Uint32 timeout)

     The  AG_NetSocketSetInit()  function initializes a new socket set.  AG_Net-
     SocketSetClear() resets a socket set to the  empty  set.	AG_NetSocketSet-
     Free() releases all resources allocated by a socket set.

     The  AG_NetPoll() function blocks the execution of the current thread until
     an event is reported on one or more of the  sockets  in  the  nsInput  set.
     Sockets  with  data  available  for  reading/writing  are returned into the
     nsRead and nsWrite sets.  Sockets with other exceptions (such as availabil-
     ity of out-of-band data) are  returned  into  the	nsExcept  set.	 If  the
     timeout  argument	is  non-zero,  the  call  will time out in the specified
     amount of time (given in milliseconds).

STRUCTURE DATA
     For the AG_NetAddr structure:

     typedef struct ag_net_addr {
	     enum ag_net_addr_family family;	     /* Address family */
	     int port;				     /* Port number (if any) */
	     union {
		     struct {
			     char  *path;	     /* Unix socket path */
		     } local;
		     struct {
			     Uint32 addr;	     /* IPv4 address */
		     } inet4;
		     struct {
			     Uint8  addr[16];	     /* IPv6 address */
		     } inet6;
	     } data;
     } AG_NetAddr;

     For the AG_NetSocket structure:

     enum ag_net_addr_family family   Address family
     enum ag_net_socket_type type     Socket type
     int proto			      Socket protocol number
     AG_Mutex lock		      Exclusive access lock
     AG_NetAddr *addrLocal	      Bound local address
     AG_NetAddr *addrRemote	      Connected remote address
     int fd			      Socket file descriptor (non-portable)
     void *p			      Optional user-defined pointer

SEE ALSO
     AG_Intro(3), AG_OpenNetSocket(3)

HISTORY
     The AG_Net interface first appeared in Agar 1.5.0.

Agar 1.7			December 21, 2022		       AG_NET(3)
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Net&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>
home | help
Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages
