diff --git a/examples/Makefile b/examples/Makefile new file mode 100644 index 0000000..c9990a9 --- /dev/null +++ b/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 diff --git a/examples/mic.c b/examples/mic.c new file mode 100644 index 0000000..a1195d7 --- /dev/null +++ b/examples/mic.c @@ -0,0 +1,48 @@ +#include +#include +#include +#include +#include +#include + +#include + +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 ); +} diff --git a/examples/mis.c b/examples/mis.c new file mode 100644 index 0000000..211682d --- /dev/null +++ b/examples/mis.c @@ -0,0 +1,46 @@ +#include +#include +#include +#include +#include +#include + +#include + +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 ); +} diff --git a/src/Makefile.am b/src/Makefile.am index 6a85f73..ec674ac 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -73,4 +73,4 @@ TESTS = \ t_units \ t_uuid -dist_man1_MANS = iperf3.1 +dist_man_MANS = iperf3.1 libiperf.3 diff --git a/src/Makefile.in b/src/Makefile.in index 5328b12..289ea10 100644 --- a/src/Makefile.in +++ b/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 \ - installcheck installcheck-am installdirs maintainer-clean \ - maintainer-clean-generic mostlyclean mostlyclean-compile \ - mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ - tags uninstall uninstall-am uninstall-binPROGRAMS \ - uninstall-includeHEADERS uninstall-info-am \ - uninstall-libLIBRARIES uninstall-man uninstall-man1 + install-libLIBRARIES install-man install-man1 install-man3 \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-compile mostlyclean-generic mostlyclean-libtool \ + pdf pdf-am ps ps-am tags uninstall uninstall-am \ + uninstall-binPROGRAMS uninstall-includeHEADERS \ + 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. diff --git a/src/libiperf.3 b/src/libiperf.3 new file mode 100644 index 0000000..af2f3d4 --- /dev/null +++ b/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 +.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 . +Other contributions from Ajay Tirumala, Jim Ferguson, +Feng Qin, +Kevin Gibbs, +John Estabrook , +Andrew Gallatin , +Stephen Hemminger + +.SH "SEE ALSO" +iperf3(1), +http://code.google.com/p/iperf/