zstr(3) - 0MQ Api

zstr(3)

CZMQ Manual - CZMQ/2.2.1

Name

zstr - sending and receiving strings

Synopsis

//  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.
CZMQ_EXPORT char *
    zstr_recv (void *socket);

//  Receive C string from socket, if socket had input ready. Caller must
//  free returned string using zstr_free. Returns NULL if there was no input
//  waiting, or if the context was terminated. Use zctx_interrupted to exit
//  any loop that relies on this method.
CZMQ_EXPORT char *
    zstr_recv_nowait (void *socket);

//  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.
CZMQ_EXPORT int
    zstr_send (void *socket, 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 *socket, 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 *socket, const char *format, ...);

//  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 *socket, const char *format, ...);

//  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 *socket, const char *string, ...);

//  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().
CZMQ_EXPORT int
    zstr_recvx (void *socket, char **string_p, ...);

//  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 int
    zstr_test (bool verbose);

Description

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

Example

From zstr_test method

 zctx_t *ctx = zctx_new ();
 assert (ctx);

 void *output = zsocket_new (ctx, ZMQ_PAIR);
 assert (output);
 zsocket_bind (output, "inproc://zstr.test");
 void *input = zsocket_new (ctx, ZMQ_PAIR);
 assert (input);
 zsocket_connect (input, "inproc://zstr.test");

 // 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);
 if (streq (string, "END")) {
 zstr_free (&string);
 break;
 }
 zstr_free (&string);
 }
 assert (string_nbr == 15);
  zctx_destroy (&ctx);

Authors

The CZMQ manual was written by Pieter Hintjens<moc.xitami|hp#moc.xitami|hp>.

Resources

Main web site: http://czmq.zeromq.org/

Report bugs to the ØMQ development mailing list: <gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez>

Copyright

Copyright (c) 1991-2014 iMatix and Contributors. License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>. This is free software: you are free to change it and redistribute it. There is NO WARRANTY, to the extent permitted by law. For details see the files COPYING and COPYING.LESSER included with the CZMQ distribution.

0MQ Api