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

FreeBSD Manual Pages

  
 
  

home | help
ZSTR(3)				  CZMQ Manual			       ZSTR(3)

NAME
       zstr - Class for	sending	and receiving strings

SYNOPSIS
       //  This	is a stable class, and may not change except for emergencies. It
       //  is provided in stable builds.
       //  This	class has draft	methods, which may change over time. They are not
       //  in stable releases, by default. Use --enable-drafts to enable.
       //  Receive C string from socket. Caller	must free returned string using
       //  zstr_free().	Returns	NULL if	the context is being terminated	or the
       //  process was interrupted.
       //  Caller owns return value and	must destroy it	when done.
       CZMQ_EXPORT char	*
	   zstr_recv (void *source);

       //  Receive a series of strings (until NULL) from multipart data.
       //  Each	string is allocated and	filled with string data; if there
       //  are not enough frames, unallocated strings are set to NULL.
       //  Returns -1 if the message could not be read,	else returns the
       //  number of strings filled, zero or more. Free	each returned string
       //  using zstr_free(). If not enough strings are	provided, remaining
       //  multipart frames in the message are dropped.
       CZMQ_EXPORT int
	   zstr_recvx (void *source, char **string_p, ...);

       //  Send	a C string to a	socket,	as a frame. The	string is sent without
       //  trailing null byte; to read this you	can use	zstr_recv, or a	similar
       //  method that adds a null terminator on the received string. String
       //  may be NULL,	which is sent as "".
       CZMQ_EXPORT int
	   zstr_send (void *dest, const	char *string);

       //  Send	a C string to a	socket,	as zstr_send(),	with a MORE flag, so that
       //  you can send	further	strings	in the same multi-part message.
       CZMQ_EXPORT int
	   zstr_sendm (void *dest, const char *string);

       //  Send	a formatted string to a	socket.	Note that you should NOT use
       //  user-supplied strings in the	format (they may contain '%' which
       //  will	create security	holes).
       CZMQ_EXPORT int
	   zstr_sendf (void *dest, const char *format, ...) CHECK_PRINTF (2);

       //  Send	a formatted string to a	socket,	as for zstr_sendf(), with a
       //  MORE	flag, so that you can send further strings in the same multi-part
       //  message.
       CZMQ_EXPORT int
	   zstr_sendfm (void *dest, const char *format,	...) CHECK_PRINTF (2);

       //  Send	a series of strings (until NULL) as multipart data
       //  Returns 0 if	the strings could be sent OK, or -1 on error.
       CZMQ_EXPORT int
	   zstr_sendx (void *dest, const char *string, ...);

       //  Free	a provided string, and nullify the parent pointer. Safe	to call	on
       //  a null pointer.
       CZMQ_EXPORT void
	   zstr_free (char **string_p);

       //  Self	test of	this class.
       CZMQ_EXPORT void
	   zstr_test (bool verbose);

       #ifdef CZMQ_BUILD_DRAFT_API
       //  *** Draft method, for development use, may change without warning ***
       //  De-compress and receive C string from socket, received as a message
       //  with	two frames: size of the	uncompressed string, and the string itself.
       //  Caller must free returned string using zstr_free(). Returns NULL if the
       //  context is being terminated or the process was interrupted.
       //  Caller owns return value and	must destroy it	when done.
       CZMQ_EXPORT char	*
	   zstr_recv_compress (void *source);

       //  *** Draft method, for development use, may change without warning ***
       //  Compress and	send a C string	to a socket, as	a message with two frames:
       //  size	of the uncompressed string, and	the string itself. The string is
       //  sent	without	trailing null byte; to read this you can use
       //  zstr_recv_compress, or a similar method that	de-compresses and adds a
       //  null	terminator on the received string.
       CZMQ_EXPORT int
	   zstr_send_compress (void *dest, const char *string);

       //  *** Draft method, for development use, may change without warning ***
       //  Compress and	send a C string	to a socket, as	zstr_send_compress(),
       //  with	a MORE flag, so	that you can send further strings in the same
       //  multi-part message.
       CZMQ_EXPORT int
	   zstr_sendm_compress (void *dest, const char *string);

       //  *** Draft method, for development use, may change without warning ***
       //  Accepts a void pointer and returns a	fresh character	string.	If source
       //  is null, returns an empty string.
       //  Caller owns return value and	must destroy it	when done.
       CZMQ_EXPORT char	*
	   zstr_str (void *source);

       #endif // CZMQ_BUILD_DRAFT_API
       Please add '@interface' section in './../src/zstr.c'.

DESCRIPTION
       The zstr	class provides utility functions for sending and receiving C
       strings across 0MQ sockets. It sends strings without a terminating
       null, and appends a null	byte on	received strings. This class is	for
       simple message sending.

		  Memory		       Wire
		  +-------------+---+	       +---+-------------+
	   Send	  | S t	r i n g	| 0 |  ---->   | 6 | S t r i n g |
		  +-------------+---+	       +---+-------------+

		  Wire			       Heap
		  +---+-------------+	       +-------------+---+
	   Recv	  | 6 |	S t r i	n g |  ---->   | S t r i n g | 0 |
		  +---+-------------+	       +-------------+---+

EXAMPLE
       From zstr_test method.

	   //  Create two PAIR sockets and connect over	inproc
	   zsock_t *output = zsock_new_pair ("@inproc://zstr.test");
	   assert (output);
	   zsock_t *input = zsock_new_pair (">inproc://zstr.test");
	   assert (input);

	   //  Send ten	strings, five strings with MORE	flag and then END
	   int string_nbr;
	   for (string_nbr = 0;	string_nbr < 10; string_nbr++)
	       zstr_sendf (output, "this is string %d",	string_nbr);
	   zstr_sendx (output, "This", "is", "almost", "the", "very", "END", NULL);

	   //  Read and	count until we receive END
	   string_nbr =	0;
	   for (string_nbr = 0;; string_nbr++) {
	       char *string = zstr_recv	(input);
	       assert (string);
	       if (streq (string, "END")) {
		   zstr_free (&string);
		   break;
	       }
	       zstr_free (&string);
	   }
	   assert (string_nbr == 15);

	   #ifdef HAVE_LIBLZ4
	   int ret = zstr_send_compress	(output, "loooong");
	   assert (ret == 0);
	   char	*string	= zstr_recv_compress (input);
	   assert (string);
	   assert (streq (string, "loooong"));
	   zstr_free (&string);

	   zstr_send_compress (output, "loooong");
	   assert (ret == 0);
	   zmsg_t *msg = zmsg_recv (input);
	   assert (msg);
	   assert (*((size_t *)zframe_data (zmsg_first (msg))) == strlen ("loooong"));
	   zmsg_destroy	(&msg);
	   #endif

	   zsock_destroy (&input);
	   zsock_destroy (&output);

	   #if defined (ZMQ_SERVER)
	   //  Test SERVER/CLIENT over zstr
	   zsock_t *server = zsock_new_server ("inproc://zstr-test-routing");
	   zsock_t *client = zsock_new_client ("inproc://zstr-test-routing");;
	   assert (server);
	   assert (client);

	   //  Try normal ping-pong to check reply routing ID
	   int rc = zstr_send (client, "Hello");
	   assert (rc == 0);
	   char	*request = zstr_recv (server);
	   assert (streq (request, "Hello"));
	   assert (zsock_routing_id (server));
	   freen (request);

	   rc =	zstr_send (server, "World");
	   assert (rc == 0);
	   char	*reply = zstr_recv (client);
	   assert (streq (reply, "World"));
	   freen (reply);

	   rc =	zstr_sendf (server, "%s", "World");
	   assert (rc == 0);
	   reply = zstr_recv (client);
	   assert (streq (reply, "World"));
	   freen (reply);

	   //  Try ping-pong using sendx and recx
	   rc =	zstr_sendx (client, "Hello", NULL);
	   assert (rc == 0);
	   rc =	zstr_recvx (server, &request, NULL);
	   assert (rc >= 0);
	   assert (streq (request, "Hello"));
	   freen (request);

	   rc =	zstr_sendx (server, "World", NULL);
	   assert (rc == 0);
	   rc =	zstr_recvx (client, &reply, NULL);
	   assert (rc >= 0);
	   assert (streq (reply, "World"));
	   freen (reply);

	   //  Client and server disallow multipart
	   rc =	zstr_sendm (client, "Hello");
	   assert (rc == -1);
	   rc =	zstr_sendm (server, "World");
	   assert (rc == -1);

	   zsock_destroy (&client);
	   zsock_destroy (&server);
	   #endif

	   #if defined (__WINDOWS__)
	   zsys_shutdown();
	   #endif

AUTHORS
       The czmq	manual was written by the authors in the AUTHORS file.

RESOURCES
       Main web	site:

       Report bugs to the email	<zeromq-dev@lists.zeromq.org[1]>

COPYRIGHT
       Copyright (c) the Contributors as noted in the AUTHORS file. This file
       is part of CZMQ,	the high-level C binding for 0MQ:
       http://czmq.zeromq.org. This Source Code	Form is	subject	to the terms
       of the Mozilla Public License, v. 2.0. If a copy	of the MPL was not
       distributed with	this file, You can obtain one at
       http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
       distribution.

NOTES
	1. zeromq-dev@lists.zeromq.org
	   mailto:zeromq-dev@lists.zeromq.org

CZMQ 4.1.1			  03/01/2021			       ZSTR(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHORS | RESOURCES | COPYRIGHT | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zstr&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help