1ZSTR(3)                           CZMQ Manual                          ZSTR(3)
2
3
4

NAME

6       zstr - Class for sending and receiving strings
7

SYNOPSIS

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
20       //  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
30       //  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
37       //  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
42       //  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
48       //  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
54       //  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
59       //  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
64       //  Self test of this class.
65       CZMQ_EXPORT void
66           zstr_test (bool verbose);
67
68       #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
78       //  *** 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
87       //  *** 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
94       //  *** 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
101       #endif // CZMQ_BUILD_DRAFT_API
102       Please add '@interface' section in './../src/zstr.c'.
103

DESCRIPTION

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
110                  Memory                       Wire
111                  +-------------+---+          +---+-------------+
112           Send   | S t r i n g | 0 |  ---->   | 6 | S t r i n g |
113                  +-------------+---+          +---+-------------+
114
115                  Wire                         Heap
116                  +---+-------------+          +-------------+---+
117           Recv   | 6 | S t r i n g |  ---->   | S t r i n g | 0 |
118                  +---+-------------+          +-------------+---+
119

EXAMPLE

121       From zstr_test method.
122
123           //  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
129           //  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
135           //  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
148           #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
156           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
164           zsock_destroy (&input);
165           zsock_destroy (&output);
166
167           #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
174           //  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
182           rc = zstr_send (server, "World");
183           assert (rc == 0);
184           char *reply = zstr_recv (client);
185           assert (streq (reply, "World"));
186           freen (reply);
187
188           rc = zstr_sendf (server, "%s", "World");
189           assert (rc == 0);
190           reply = zstr_recv (client);
191           assert (streq (reply, "World"));
192           freen (reply);
193
194           //  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
202           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
209           //  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
215           zsock_destroy (&client);
216           zsock_destroy (&server);
217           #endif
218
219           #if defined (__WINDOWS__)
220           zsys_shutdown();
221           #endif
222
223

AUTHORS

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

RESOURCES

228       Main web site:
229
230       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

NOTES

242        1. zeromq-dev@lists.zeromq.org
243           mailto:zeromq-dev@lists.zeromq.org
244
245
246
247CZMQ 4.2.1                        07/19/2023                           ZSTR(3)
Impressum