1ZSTR(3) CZMQ Manual ZSTR(3)
2
6 zstr - sending and receiving strings
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // This class has draft methods, which may change over time. They are not
12 // in stable releases, by default. Use --enable-drafts to enable.
13 // Receive C string from socket. Caller must free returned string using
14 // zstr_free(). Returns NULL if the context is being terminated or the
15 // process was interrupted.
16 // Caller owns return value and must destroy it when done.
17 CZMQ_EXPORT char *
18 zstr_recv (void *source);
19 // Receive a series of strings (until NULL) from multipart data.
21 // Each string is allocated and filled with string data; if there
22 // are not enough frames, unallocated strings are set to NULL.
23 // Returns -1 if the message could not be read, else returns the
24 // number of strings filled, zero or more. Free each returned string
25 // using zstr_free(). If not enough strings are provided, remaining
26 // multipart frames in the message are dropped.
27 CZMQ_EXPORT int
28 zstr_recvx (void *source, char **string_p, ...);
29 // Send a C string to a socket, as a frame. The string is sent without
31 // trailing null byte; to read this you can use zstr_recv, or a similar
32 // method that adds a null terminator on the received string. String
33 // may be NULL, which is sent as "".
34 CZMQ_EXPORT int
35 zstr_send (void *dest, const char *string);
36 // Send a C string to a socket, as zstr_send(), with a MORE flag, so that
38 // you can send further strings in the same multi-part message.
39 CZMQ_EXPORT int
40 zstr_sendm (void *dest, const char *string);
41 // Send a formatted string to a socket. Note that you should NOT use
43 // user-supplied strings in the format (they may contain '%' which
44 // will create security holes).
45 CZMQ_EXPORT int
46 zstr_sendf (void *dest, const char *format, ...) CHECK_PRINTF (2);
47 // Send a formatted string to a socket, as for zstr_sendf(), with a
49 // MORE flag, so that you can send further strings in the same multi-part
50 // message.
51 CZMQ_EXPORT int
52 zstr_sendfm (void *dest, const char *format, ...) CHECK_PRINTF (2);
53 // Send a series of strings (until NULL) as multipart data
55 // Returns 0 if the strings could be sent OK, or -1 on error.
56 CZMQ_EXPORT int
57 zstr_sendx (void *dest, const char *string, ...);
58 // Free a provided string, and nullify the parent pointer. Safe to call on
60 // a null pointer.
61 CZMQ_EXPORT void
62 zstr_free (char **string_p);
63 // Self test of this class.
65 CZMQ_EXPORT void
66 zstr_test (bool verbose);
67 #ifdef CZMQ_BUILD_DRAFT_API
69 // *** Draft method, for development use, may change without warning ***
70 // Accepts a void pointer and returns a fresh character string. If source
71 // is null, returns an empty string.
72 // Caller owns return value and must destroy it when done.
73 CZMQ_EXPORT char *
74 zstr_str (void *source);
75 #endif // CZMQ_BUILD_DRAFT_API
77 Please add '@interface' section in './../src/zstr.c'.
78
80 The zstr class provides utility functions for sending and receiving C
81 strings across 0MQ sockets. It sends strings without a terminating
82 null, and appends a null byte on received strings. This class is for
83 simple message sending.
84 Memory Wire
86 +-------------+---+ +---+-------------+
87 Send | S t r i n g | 0 | ----> | 6 | S t r i n g |
88 +-------------+---+ +---+-------------+
89 Wire Heap
91 +---+-------------+ +-------------+---+
92 Recv | 6 | S t r i n g | ----> | S t r i n g | 0 |
93 +---+-------------+ +-------------+---+
94
96 From zstr_test method.
97 // Create two PAIR sockets and connect over inproc
99 zsock_t *output = zsock_new_pair ("@inproc://zstr.test");
100 assert (output);
101 zsock_t *input = zsock_new_pair (">inproc://zstr.test");
102 assert (input);
103 // Send ten strings, five strings with MORE flag and then END
105 int string_nbr;
106 for (string_nbr = 0; string_nbr < 10; string_nbr++)
107 zstr_sendf (output, "this is string %d", string_nbr);
108 zstr_sendx (output, "This", "is", "almost", "the", "very", "END", NULL);
109 // Read and count until we receive END
111 string_nbr = 0;
112 for (string_nbr = 0;; string_nbr++) {
113 char *string = zstr_recv (input);
114 assert (string);
115 if (streq (string, "END")) {
116 zstr_free (&string);
117 break;
118 }
119 zstr_free (&string);
120 }
121 assert (string_nbr == 15);
122 zsock_destroy (&input);
124 zsock_destroy (&output);
125 #if defined (ZMQ_SERVER)
127 // Test SERVER/CLIENT over zstr
128 zsock_t *server = zsock_new_server ("inproc://zstr-test-routing");
129 zsock_t *client = zsock_new_client ("inproc://zstr-test-routing");;
130 assert (server);
131 assert (client);
132 // Try normal ping-pong to check reply routing ID
134 int rc = zstr_send (client, "Hello");
135 assert (rc == 0);
136 char *request = zstr_recv (server);
137 assert (streq (request, "Hello"));
138 assert (zsock_routing_id (server));
139 free (request);
140 rc = zstr_send (server, "World");
142 assert (rc == 0);
143 char *reply = zstr_recv (client);
144 assert (streq (reply, "World"));
145 free (reply);
146 rc = zstr_sendf (server, "%s", "World");
148 assert (rc == 0);
149 reply = zstr_recv (client);
150 assert (streq (reply, "World"));
151 free (reply);
152 // Try ping-pong using sendx and recx
154 rc = zstr_sendx (client, "Hello", NULL);
155 assert (rc == 0);
156 rc = zstr_recvx (server, &request, NULL);
157 assert (rc >= 0);
158 assert (streq (request, "Hello"));
159 free (request);
160 rc = zstr_sendx (server, "World", NULL);
162 assert (rc == 0);
163 rc = zstr_recvx (client, &reply, NULL);
164 assert (rc >= 0);
165 assert (streq (reply, "World"));
166 free (reply);
167 // Client and server disallow multipart
169 rc = zstr_sendm (client, "Hello");
170 assert (rc == -1);
171 rc = zstr_sendm (server, "World");
172 assert (rc == -1);
173 zsock_destroy (&client);
175 zsock_destroy (&server);
176 #endif
177
180 The czmq manual was written by the authors in the AUTHORS file.
181
183 Main web site:
184 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
186
188 Copyright (c) the Contributors as noted in the AUTHORS file. This file
189 is part of CZMQ, the high-level C binding for 0MQ:
190 http://czmq.zeromq.org. This Source Code Form is subject to the terms
191 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
192 distributed with this file, You can obtain one at
193 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
194 distribution.
195
197 1. zeromq-dev@lists.zeromq.org
198 mailto:zeromq-dev@lists.zeromq.org
199CZMQ 4.0.2 12/31/2016 ZSTR(3)