1ZSTR(3) CZMQ Manual ZSTR(3)
2
6 zstr - Class for 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 // De-compress and receive C string from socket, received as a message
71 // with two frames: size of the uncompressed string, and the string itself.
72 // Caller must free returned string using zstr_free(). Returns NULL if the
73 // context is being terminated or the process was interrupted.
74 // Caller owns return value and must destroy it when done.
75 CZMQ_EXPORT char *
76 zstr_recv_compress (void *source);
77 // *** Draft method, for development use, may change without warning ***
79 // Compress and send a C string to a socket, as a message with two frames:
80 // size of the uncompressed string, and the string itself. The string is
81 // sent without trailing null byte; to read this you can use
82 // zstr_recv_compress, or a similar method that de-compresses and adds a
83 // null terminator on the received string.
84 CZMQ_EXPORT int
85 zstr_send_compress (void *dest, const char *string);
86 // *** Draft method, for development use, may change without warning ***
88 // Compress and send a C string to a socket, as zstr_send_compress(),
89 // with a MORE flag, so that you can send further strings in the same
90 // multi-part message.
91 CZMQ_EXPORT int
92 zstr_sendm_compress (void *dest, const char *string);
93 // *** Draft method, for development use, may change without warning ***
95 // Accepts a void pointer and returns a fresh character string. If source
96 // is null, returns an empty string.
97 // Caller owns return value and must destroy it when done.
98 CZMQ_EXPORT char *
99 zstr_str (void *source);
100 #endif // CZMQ_BUILD_DRAFT_API
102 Please add '@interface' section in './../src/zstr.c'.
103
105 The zstr class provides utility functions for sending and receiving C
106 strings across 0MQ sockets. It sends strings without a terminating
107 null, and appends a null byte on received strings. This class is for
108 simple message sending.
109 Memory Wire
111 +-------------+---+ +---+-------------+
112 Send | S t r i n g | 0 | ----> | 6 | S t r i n g |
113 +-------------+---+ +---+-------------+
114 Wire Heap
116 +---+-------------+ +-------------+---+
117 Recv | 6 | S t r i n g | ----> | S t r i n g | 0 |
118 +---+-------------+ +-------------+---+
119
121 From zstr_test method.
122 // Create two PAIR sockets and connect over inproc
124 zsock_t *output = zsock_new_pair ("@inproc://zstr.test");
125 assert (output);
126 zsock_t *input = zsock_new_pair (">inproc://zstr.test");
127 assert (input);
128 // Send ten strings, five strings with MORE flag and then END
130 int string_nbr;
131 for (string_nbr = 0; string_nbr < 10; string_nbr++)
132 zstr_sendf (output, "this is string %d", string_nbr);
133 zstr_sendx (output, "This", "is", "almost", "the", "very", "END", NULL);
134 // Read and count until we receive END
136 string_nbr = 0;
137 for (string_nbr = 0;; string_nbr++) {
138 char *string = zstr_recv (input);
139 assert (string);
140 if (streq (string, "END")) {
141 zstr_free (&string);
142 break;
143 }
144 zstr_free (&string);
145 }
146 assert (string_nbr == 15);
147 #ifdef HAVE_LIBLZ4
149 int ret = zstr_send_compress (output, "loooong");
150 assert (ret == 0);
151 char *string = zstr_recv_compress (input);
152 assert (string);
153 assert (streq (string, "loooong"));
154 zstr_free (&string);
155 zstr_send_compress (output, "loooong");
157 assert (ret == 0);
158 zmsg_t *msg = zmsg_recv (input);
159 assert (msg);
160 assert (*((size_t *)zframe_data (zmsg_first (msg))) == strlen ("loooong"));
161 zmsg_destroy (&msg);
162 #endif
163 zsock_destroy (&input);
165 zsock_destroy (&output);
166 #if defined (ZMQ_SERVER)
168 // Test SERVER/CLIENT over zstr
169 zsock_t *server = zsock_new_server ("inproc://zstr-test-routing");
170 zsock_t *client = zsock_new_client ("inproc://zstr-test-routing");;
171 assert (server);
172 assert (client);
173 // Try normal ping-pong to check reply routing ID
175 int rc = zstr_send (client, "Hello");
176 assert (rc == 0);
177 char *request = zstr_recv (server);
178 assert (streq (request, "Hello"));
179 assert (zsock_routing_id (server));
180 freen (request);
181 rc = zstr_send (server, "World");
183 assert (rc == 0);
184 char *reply = zstr_recv (client);
185 assert (streq (reply, "World"));
186 freen (reply);
187 rc = zstr_sendf (server, "%s", "World");
189 assert (rc == 0);
190 reply = zstr_recv (client);
191 assert (streq (reply, "World"));
192 freen (reply);
193 // Try ping-pong using sendx and recx
195 rc = zstr_sendx (client, "Hello", NULL);
196 assert (rc == 0);
197 rc = zstr_recvx (server, &request, NULL);
198 assert (rc >= 0);
199 assert (streq (request, "Hello"));
200 freen (request);
201 rc = zstr_sendx (server, "World", NULL);
203 assert (rc == 0);
204 rc = zstr_recvx (client, &reply, NULL);
205 assert (rc >= 0);
206 assert (streq (reply, "World"));
207 freen (reply);
208 // Client and server disallow multipart
210 rc = zstr_sendm (client, "Hello");
211 assert (rc == -1);
212 rc = zstr_sendm (server, "World");
213 assert (rc == -1);
214 zsock_destroy (&client);
216 zsock_destroy (&server);
217 #endif
218 #if defined (__WINDOWS__)
220 zsys_shutdown();
221 #endif
222
225 The czmq manual was written by the authors in the AUTHORS file.
226
228 Main web site:
229 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
231
233 Copyright (c) the Contributors as noted in the AUTHORS file. This file
234 is part of CZMQ, the high-level C binding for 0MQ:
235 http://czmq.zeromq.org. This Source Code Form is subject to the terms
236 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
237 distributed with this file, You can obtain one at
238 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
239 distribution.
240
242 1. zeromq-dev@lists.zeromq.org
243 mailto:zeromq-dev@lists.zeromq.org
244CZMQ 4.2.1 07/19/2023 ZSTR(3)