Added library man page and examples subdir.

examples/Makefile

@@ -0,0 +1,18 @@
+IPERFDIR =	..
+
+CC =		gcc
+
+CFLAGS =	-I$(IPERFDIR)/src
+LDFLAGS =	-L$(IPERFDIR)/src
+LIBS =		-liperf
+
+all:		mic mis
+
+mic:		mic.c $(IPERFDIR)/src/iperf_api.h $(IPERFDIR)/src/libiperf.a
+	$(CC) $(CFLAGS) mic.c $(LDFLAGS) $(LIBS) -o mic
+
+mis:		mis.c $(IPERFDIR)/src/iperf_api.h $(IPERFDIR)/src/libiperf.a
+	$(CC) $(CFLAGS) mis.c $(LDFLAGS) $(LIBS) -o mis
+
+clean:
+	-rm -f mic mis *.o *.a a.out core core.* *.core

examples/mic.c

@@ -0,0 +1,48 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <sysexits.h>
+#include <stdint.h>
+
+#include <iperf_api.h>
+
+int
+main( int argc, char** argv )
+{
+    char* argv0;
+    char* host;
+    int port;
+    struct iperf_test *test;
+
+    argv0 = strrchr( argv[0], '/' );
+    if ( argv0 != (char*) 0 )
+	++argv0;
+    else
+	argv0 = argv[0];
+
+    if ( argc != 3 ) {
+	fprintf( stderr, "usage: %s [host] [port]\n", argv0 );
+	exit( EXIT_FAILURE );
+    }
+    host = argv[1];
+    port = atoi( argv[2] );
+
+    test = iperf_new_test();
+    if ( test == NULL ) {
+	fprintf( stderr, "%s: failed to create test\n", argv0 );
+	exit( EXIT_FAILURE );
+    }
+    iperf_defaults( test );
+    iperf_set_test_role( test, 'c' );
+    iperf_set_test_server_hostname( test, host );
+    iperf_set_test_server_port( test, port );
+
+    if ( iperf_run_client( test ) < 0 ) {
+	fprintf( stderr, "%s: error - %s\n", argv0, iperf_strerror( i_errno ) );
+	exit( EXIT_FAILURE );
+    }
+
+    iperf_free_test( test );
+    exit( EXIT_SUCCESS );
+}

examples/mis.c

@@ -0,0 +1,46 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <sysexits.h>
+#include <stdint.h>
+
+#include <iperf_api.h>
+
+int
+main( int argc, char** argv )
+{
+    char* argv0;
+    int port;
+    struct iperf_test *test;
+
+    argv0 = strrchr( argv[0], '/' );
+    if ( argv0 != (char*) 0 )
+	++argv0;
+    else
+	argv0 = argv[0];
+
+    if ( argc != 2 ) {
+	fprintf( stderr, "usage: %s [port]\n", argv0 );
+	exit( EXIT_FAILURE );
+    }
+    port = atoi( argv[1] );
+
+    test = iperf_new_test();
+    if ( test == NULL ) {
+	fprintf( stderr, "%s: failed to create test\n", argv0 );
+	exit( EXIT_FAILURE );
+    }
+    iperf_defaults( test );
+    iperf_set_test_role( test, 's' );
+    iperf_set_test_server_port( test, port );
+
+    for (;;) {
+	if ( iperf_run_server( test ) < 0 )
+	    fprintf( stderr, "%s: error - %s\n\n", argv0, iperf_strerror( i_errno ) );
+	iperf_reset_test( test );
+    }
+
+    iperf_free_test( test );
+    exit( EXIT_SUCCESS );
+}

src/Makefile.am

@@ -73,4 +73,4 @@ TESTS                   = \
                         t_units \
                         t_uuid
 
-dist_man1_MANS          = iperf3.1
+dist_man_MANS          = iperf3.1 libiperf.3

src/Makefile.in

@@ -42,7 +42,7 @@ bin_PROGRAMS = iperf3$(EXEEXT)
 noinst_PROGRAMS = t_timer$(EXEEXT) t_units$(EXEEXT) t_uuid$(EXEEXT) \
 	iperf3_profile$(EXEEXT)
 subdir = src
-DIST_COMMON = $(dist_man1_MANS) $(include_HEADERS) \
+DIST_COMMON = $(dist_man_MANS) $(include_HEADERS) \
 	$(srcdir)/Makefile.am $(srcdir)/Makefile.in \
 	$(srcdir)/config.h.in
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
@@ -59,7 +59,8 @@ am__vpath_adj = case $$p in \
   esac;
 am__strip_dir = `echo $$p | sed -e 's|^.*/||'`;
 am__installdirs = "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" \
-	"$(DESTDIR)$(man1dir)" "$(DESTDIR)$(includedir)"
+	"$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man3dir)" \
+	"$(DESTDIR)$(includedir)"
 libLIBRARIES_INSTALL = $(INSTALL_DATA)
 LIBRARIES = $(lib_LIBRARIES)
 ARFLAGS = cru
@@ -120,8 +121,9 @@ DIST_SOURCES = $(libiperf_a_SOURCES) $(iperf3_SOURCES) \
 	$(iperf3_profile_SOURCES) $(t_timer_SOURCES) \
 	$(t_units_SOURCES) $(t_uuid_SOURCES)
 man1dir = $(mandir)/man1
+man3dir = $(mandir)/man3
 NROFF = nroff
-MANS = $(dist_man1_MANS)
+MANS = $(dist_man_MANS)
 includeHEADERS_INSTALL = $(INSTALL_HEADER)
 HEADERS = $(include_HEADERS)
 ETAGS = etags
@@ -300,7 +302,7 @@ TESTS = \
                         t_units \
                         t_uuid
 
-dist_man1_MANS = iperf3.1
+dist_man_MANS = iperf3.1 libiperf.3
 all: config.h
 	$(MAKE) $(AM_MAKEFLAGS) all-am
 
@@ -817,6 +819,51 @@ uninstall-man1:
 	  echo " rm -f '$(DESTDIR)$(man1dir)/$$inst'"; \
 	  rm -f "$(DESTDIR)$(man1dir)/$$inst"; \
 	done
+install-man3: $(man3_MANS) $(man_MANS)
+	@$(NORMAL_INSTALL)
+	test -z "$(man3dir)" || $(mkdir_p) "$(DESTDIR)$(man3dir)"
+	@list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \
+	l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
+	for i in $$l2; do \
+	  case "$$i" in \
+	    *.3*) list="$$list $$i" ;; \
+	  esac; \
+	done; \
+	for i in $$list; do \
+	  if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \
+	  else file=$$i; fi; \
+	  ext=`echo $$i | sed -e 's/^.*\\.//'`; \
+	  case "$$ext" in \
+	    3*) ;; \
+	    *) ext='3' ;; \
+	  esac; \
+	  inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \
+	  inst=`echo $$inst | sed -e 's/^.*\///'`; \
+	  inst=`echo $$inst | sed '$(transform)'`.$$ext; \
+	  echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \
+	  $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst"; \
+	done
+uninstall-man3:
+	@$(NORMAL_UNINSTALL)
+	@list='$(man3_MANS) $(dist_man3_MANS) $(nodist_man3_MANS)'; \
+	l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
+	for i in $$l2; do \
+	  case "$$i" in \
+	    *.3*) list="$$list $$i" ;; \
+	  esac; \
+	done; \
+	for i in $$list; do \
+	  ext=`echo $$i | sed -e 's/^.*\\.//'`; \
+	  case "$$ext" in \
+	    3*) ;; \
+	    *) ext='3' ;; \
+	  esac; \
+	  inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \
+	  inst=`echo $$inst | sed -e 's/^.*\///'`; \
+	  inst=`echo $$inst | sed '$(transform)'`.$$ext; \
+	  echo " rm -f '$(DESTDIR)$(man3dir)/$$inst'"; \
+	  rm -f "$(DESTDIR)$(man3dir)/$$inst"; \
+	done
 install-includeHEADERS: $(include_HEADERS)
 	@$(NORMAL_INSTALL)
 	test -z "$(includedir)" || $(mkdir_p) "$(DESTDIR)$(includedir)"
@@ -988,7 +1035,7 @@ check-am: all-am
 check: check-am
 all-am: Makefile $(LIBRARIES) $(PROGRAMS) $(MANS) $(HEADERS) config.h
 installdirs:
-	for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(includedir)"; do \
+	for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man3dir)" "$(DESTDIR)$(includedir)"; do \
 	  test -z "$$dir" || $(mkdir_p) "$$dir"; \
 	done
 install: install-am
@@ -1042,7 +1089,7 @@ install-exec-am: install-binPROGRAMS install-libLIBRARIES
 
 install-info: install-info-am
 
-install-man: install-man1
+install-man: install-man1 install-man3
 
 installcheck-am:
 
@@ -1067,7 +1114,7 @@ ps-am:
 uninstall-am: uninstall-binPROGRAMS uninstall-includeHEADERS \
 	uninstall-info-am uninstall-libLIBRARIES uninstall-man
 
-uninstall-man: uninstall-man1
+uninstall-man: uninstall-man1 uninstall-man3
 
 .PHONY: CTAGS GTAGS all all-am check check-TESTS check-am clean \
 	clean-binPROGRAMS clean-generic clean-libLIBRARIES \
@@ -1077,13 +1124,14 @@ uninstall-man: uninstall-man1
 	html-am info info-am install install-am install-binPROGRAMS \
 	install-data install-data-am install-exec install-exec-am \
 	install-includeHEADERS install-info install-info-am \
-	install-libLIBRARIES install-man install-man1 install-strip \
+	install-libLIBRARIES install-man install-man1 install-man3 \
-	installcheck installcheck-am installdirs maintainer-clean \
+	install-strip installcheck installcheck-am installdirs \
-	maintainer-clean-generic mostlyclean mostlyclean-compile \
+	maintainer-clean maintainer-clean-generic mostlyclean \
-	mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+	mostlyclean-compile mostlyclean-generic mostlyclean-libtool \
-	tags uninstall uninstall-am uninstall-binPROGRAMS \
+	pdf pdf-am ps ps-am tags uninstall uninstall-am \
-	uninstall-includeHEADERS uninstall-info-am \
+	uninstall-binPROGRAMS uninstall-includeHEADERS \
-	uninstall-libLIBRARIES uninstall-man uninstall-man1
+	uninstall-info-am uninstall-libLIBRARIES uninstall-man \
+	uninstall-man1 uninstall-man3
 
 # Tell versions [3.59,3.63) of GNU make to not export all variables.
 # Otherwise a system limit (for SysV at least) may be exceeded.

src/libiperf.3

@@ -0,0 +1,105 @@
+.TH LIBIPERF 3 "March 2013" NLANR/DAST "User Manuals"
+.SH NAME
+libiperf \- API for iperf3 network throughput tester
+
+.SH SYNOPSIS
+#include <iperf_api.h>
+.br
+-liperf
+
+.SH DESCRIPTION
+.PP
+Libiperf gives you access to all the functionality of the iperf3
+network testing tool.
+You can build it directly into your own program, instead of having
+to run it as a shell command.
+
+.SH CALLS
+Initialization / termination:
+.nf
+    struct iperf_test *iperf_new_test();
+    int iperf_defaults(struct iperf_test *t);
+    void iperf_free_test(struct iperf_test *t);
+.fi
+Setting test parameters:
+.nf
+    void iperf_set_test_role( struct iperf_test *pt, char role );
+    void iperf_set_test_server_hostname( struct iperf_test *t, char *server_hos
+    void iperf_set_test_server_port( struct iperf_test *t, int server_port );
+    void iperf_set_test_duration( struct iperf_test *t, int duration );
+    void iperf_set_test_blksize( struct iperf_test *t, int blksize );
+    void iperf_set_test_num_streams( struct iperf_test *t, int num_streams );
+    void iperf_set_test_json_output( struct iperf_test *t, int json_output );
+    int iperf_has_zerocopy( void );
+    void iperf_set_test_zerocopy( struct iperf_test* t, int zerocopy );
+.fi
+Running a test:
+.nf
+    int iperf_run_client(struct iperf_test *);
+    int iperf_run_server(struct iperf_test *);
+    void iperf_test_reset(struct iperf_test *);
+.fi
+Error reporting:
+.nf
+    void iperf_err(struct iperf_test *t, const char *format, ...);
+    char *iperf_strerror(int);
+    extern int i_errno;
+.fi
+This is not a complete list of the available calls.
+See the include file for more.
+
+.SH EXAMPLES
+Here's some sample code that runs an iperf client:
+.nf
+    struct iperf_test *test;
+    test = iperf_new_test();
+    if ( test == NULL ) {
+        fprintf( stderr, "%s: failed to create test\n", argv0 );
+        exit( EXIT_FAILURE );
+    }
+    iperf_defaults( test );
+    iperf_set_test_role( test, 'c' );
+    iperf_set_test_server_hostname( test, host );
+    iperf_set_test_server_port( test, port );
+    if ( iperf_run_client( test ) < 0 ) {
+        fprintf( stderr, "%s: error - %s\n", argv0, iperf_strerror( i_errno ) );
+        exit( EXIT_FAILURE );
+    }
+    iperf_free_test( test );
+.fi
+And here's a server:
+.nf
+    struct iperf_test *test;
+    test = iperf_new_test();
+    if ( test == NULL ) {
+        fprintf( stderr, "%s: failed to create test\n", argv0 );
+        exit( EXIT_FAILURE );
+    }
+    iperf_defaults( test );
+    iperf_set_test_role( test, 's' );
+    iperf_set_test_server_port( test, port );
+    for (;;) {
+        if ( iperf_run_server( test ) < 0 )
+            fprintf( stderr, "%s: error - %s\n\n", argv0, iperf_strerror( i_errn
+o ) );
+        iperf_reset_test( test );
+    }
+    iperf_free_test( test );
+.fi
+These are not complete programs, just excerpts.
+The full runnable source code can be found in the examples subdirectory
+of the iperf3 source tree.
+
+.SH AUTHORS
+Iperf was originally written by Mark Gates and Alex Warshavsky.
+Man page and maintence by Jon Dugan <jdugan at x1024 dot net>.
+Other contributions from Ajay Tirumala, Jim Ferguson,
+Feng Qin,
+Kevin Gibbs,
+John Estabrook <jestabro at ncsa.uiuc.edu>,
+Andrew Gallatin <gallatin at gmail.com>,
+Stephen Hemminger <shemminger at linux-foundation.org>
+
+.SH "SEE ALSO"
+iperf3(1),
+http://code.google.com/p/iperf/