1ZSYS(3) CZMQ Manual ZSYS(3)
2
6 zsys - system-level methods
7
9 #define UDP_FRAME_MAX 255 // Max size of UDP frame
10 // Callback for interrupt signal handler
12 typedef void (zsys_handler_fn) (int signal_value);
13 // Initialize CZMQ zsys layer; this happens automatically when you create
15 // a socket or an actor; however this call lets you force initialization
16 // earlier, so e.g. logging is properly set-up before you start working.
17 // Not threadsafe, so call only from main thread. Safe to call multiple
18 // times. Returns global CZMQ context.
19 CZMQ_EXPORT void *
20 zsys_init (void);
21 // Optionally shut down the CZMQ zsys layer; this normally happens automatically
23 // when the process exits; however this call lets you force a shutdown
24 // earlier, avoiding any potential problems with atexit() ordering, especially
25 // with Windows dlls.
26 CZMQ_EXPORT void
27 zsys_shutdown (void);
28 // Get a new ZMQ socket, automagically creating a ZMQ context if this is
30 // the first time. Caller is responsible for destroying the ZMQ socket
31 // before process exits, to avoid a ZMQ deadlock. Note: you should not use
32 // this method in CZMQ apps, use zsock_new() instead.
33 // *** This is for CZMQ internal use only and may change arbitrarily ***
34 CZMQ_EXPORT void *
35 zsys_socket (int type, const char *filename, size_t line_nbr);
36 // Destroy/close a ZMQ socket. You should call this for every socket you
38 // create using zsys_socket().
39 // *** This is for CZMQ internal use only and may change arbitrarily ***
40 CZMQ_EXPORT int
41 zsys_close (void *handle, const char *filename, size_t line_nbr);
42 // Return ZMQ socket name for socket type
44 // *** This is for CZMQ internal use only and may change arbitrarily ***
45 CZMQ_EXPORT char *
46 zsys_sockname (int socktype);
47 // Create a pipe, which consists of two PAIR sockets connected over inproc.
49 // The pipe is configured to use the zsys_pipehwm setting. Returns the
50 // frontend socket successful, NULL if failed.
51 CZMQ_EXPORT zsock_t *
52 zsys_create_pipe (zsock_t **backend_p);
53 // Set interrupt handler; this saves the default handlers so that a
55 // zsys_handler_reset () can restore them. If you call this multiple times
56 // then the last handler will take affect. If handler_fn is NULL, disables
57 // default SIGINT/SIGTERM handling in CZMQ.
58 CZMQ_EXPORT void
59 zsys_handler_set (zsys_handler_fn *handler_fn);
60 // Reset interrupt handler, call this at exit if needed
62 CZMQ_EXPORT void
63 zsys_handler_reset (void);
64 // Set default interrupt handler, so Ctrl-C or SIGTERM will set
66 // zsys_interrupted. Idempotent; safe to call multiple times.
67 // *** This is for CZMQ internal use only and may change arbitrarily ***
68 CZMQ_EXPORT void
69 zsys_catch_interrupts (void);
70 // Return 1 if file exists, else zero
72 CZMQ_EXPORT bool
73 zsys_file_exists (const char *filename);
74 // Return size of file, or -1 if not found
76 CZMQ_EXPORT ssize_t
77 zsys_file_size (const char *filename);
78 // Return file modification time. Returns 0 if the file does not exist.
80 CZMQ_EXPORT time_t
81 zsys_file_modified (const char *filename);
82 // Return file mode; provides at least support for the POSIX S_ISREG(m)
84 // and S_ISDIR(m) macros and the S_IRUSR and S_IWUSR bits, on all boxes.
85 // Returns a mode_t cast to int, or -1 in case of error.
86 CZMQ_EXPORT int
87 zsys_file_mode (const char *filename);
88 // Delete file. Does not complain if the file is absent
90 CZMQ_EXPORT int
91 zsys_file_delete (const char *filename);
92 // Check if file is 'stable'
94 CZMQ_EXPORT bool
95 zsys_file_stable (const char *filename);
96 // Create a file path if it doesn't exist. The file path is treated as a
98 // printf format.
99 CZMQ_EXPORT int
100 zsys_dir_create (const char *pathname, ...);
101 // Remove a file path if empty; the pathname is treated as printf format.
103 CZMQ_EXPORT int
104 zsys_dir_delete (const char *pathname, ...);
105 // Move to a specified working directory. Returns 0 if OK, -1 if this failed.
107 CZMQ_EXPORT int
108 zsys_dir_change (const char *pathname);
109 // Set private file creation mode; all files created from here will be
111 // readable/writable by the owner only.
112 CZMQ_EXPORT void
113 zsys_file_mode_private (void);
114 // Reset default file creation mode; all files created from here will use
116 // process file mode defaults.
117 CZMQ_EXPORT void
118 zsys_file_mode_default (void);
119 // Return the CZMQ version for run-time API detection; returns version
121 // number into provided fields, providing reference isn't null in each case.
122 CZMQ_EXPORT void
123 zsys_version (int *major, int *minor, int *patch);
124 // Format a string using printf formatting, returning a freshly allocated
126 // buffer. If there was insufficient memory, returns NULL. Free the returned
127 // string using zstr_free().
128 CZMQ_EXPORT char *
129 zsys_sprintf (const char *format, ...);
130 // Format a string with a va_list argument, returning a freshly allocated
132 // buffer. If there was insufficient memory, returns NULL. Free the returned
133 // string using zstr_free().
134 CZMQ_EXPORT char *
135 zsys_vprintf (const char *format, va_list argptr);
136 // Create UDP beacon socket; if the routable option is true, uses
138 // multicast (not yet implemented), else uses broadcast. This method
139 // and related ones might _eventually_ be moved to a zudp class.
140 // *** This is for CZMQ internal use only and may change arbitrarily ***
141 CZMQ_EXPORT SOCKET
142 zsys_udp_new (bool routable);
143 // Close a UDP socket
145 // *** This is for CZMQ internal use only and may change arbitrarily ***
146 CZMQ_EXPORT int
147 zsys_udp_close (SOCKET handle);
148 // Send zframe to UDP socket, return -1 if sending failed due to
150 // interface having disappeared (happens easily with WiFi)
151 // *** This is for CZMQ internal use only and may change arbitrarily ***
152 CZMQ_EXPORT int
153 zsys_udp_send (SOCKET udpsock, zframe_t *frame, inaddr_t *address, int addrlen);
154 // Receive zframe from UDP socket, and set address of peer that sent it
156 // The peername must be a char [INET_ADDRSTRLEN] array.
157 // *** This is for CZMQ internal use only and may change arbitrarily ***
158 CZMQ_EXPORT zframe_t *
159 zsys_udp_recv (SOCKET udpsock, char *peername, int peerlen);
160 // Handle an I/O error on some socket operation; will report and die on
162 // fatal errors, and continue silently on "try again" errors.
163 // *** This is for CZMQ internal use only and may change arbitrarily ***
164 CZMQ_EXPORT void
165 zsys_socket_error (const char *reason);
166 // Return current host name, for use in public tcp:// endpoints. Caller gets
168 // a freshly allocated string, should free it using zstr_free(). If the host
169 // name is not resolvable, returns NULL.
170 CZMQ_EXPORT char *
171 zsys_hostname (void);
172 // Move the current process into the background. The precise effect depends
174 // on the operating system. On POSIX boxes, moves to a specified working
175 // directory (if specified), closes all file handles, reopens stdin, stdout,
176 // and stderr to the null device, and sets the process to ignore SIGHUP. On
177 // Windows, does nothing. Returns 0 if OK, -1 if there was an error.
178 CZMQ_EXPORT int
179 zsys_daemonize (const char *workdir);
180 // Drop the process ID into the lockfile, with exclusive lock, and switch
182 // the process to the specified group and/or user. Any of the arguments
183 // may be null, indicating a no-op. Returns 0 on success, -1 on failure.
184 // Note if you combine this with zsys_daemonize, run after, not before
185 // that method, or the lockfile will hold the wrong process ID.
186 CZMQ_EXPORT int
187 zsys_run_as (const char *lockfile, const char *group, const char *user);
188 // Returns true if the underlying libzmq supports CURVE security.
190 // Uses a heuristic probe according to the version of libzmq being used.
191 CZMQ_EXPORT bool
192 zsys_has_curve (void);
193 // Configure the number of I/O threads that ZeroMQ will use. A good
195 // rule of thumb is one thread per gigabit of traffic in or out. The
196 // default is 1, sufficient for most applications. If the environment
197 // variable ZSYS_IO_THREADS is defined, that provides the default.
198 // Note that this method is valid only before any socket is created.
199 CZMQ_EXPORT void
200 zsys_set_io_threads (size_t io_threads);
201 // Configure the number of sockets that ZeroMQ will allow. The default
203 // is 1024. The actual limit depends on the system, and you can query it
204 // by using zsys_socket_limit (). A value of zero means "maximum".
205 // Note that this method is valid only before any socket is created.
206 CZMQ_EXPORT void
207 zsys_set_max_sockets (size_t max_sockets);
208 // Return maximum number of ZeroMQ sockets that the system will support.
210 CZMQ_EXPORT size_t
211 zsys_socket_limit (void);
212 // Configure the maximum allowed size of a message sent.
214 // The default is INT_MAX.
215 CZMQ_EXPORT void
216 zsys_set_max_msgsz (int max_msgsz);
217 // Return maximum message size.
219 CZMQ_EXPORT int
220 zsys_max_msgsz (void);
221 // Configure the default linger timeout in msecs for new zsock instances.
223 // You can also set this separately on each zsock_t instance. The default
224 // linger time is zero, i.e. any pending messages will be dropped. If the
225 // environment variable ZSYS_LINGER is defined, that provides the default.
226 // Note that process exit will typically be delayed by the linger time.
227 CZMQ_EXPORT void
228 zsys_set_linger (size_t linger);
229 // Configure the default outgoing pipe limit (HWM) for new zsock instances.
231 // You can also set this separately on each zsock_t instance. The default
232 // HWM is 1,000, on all versions of ZeroMQ. If the environment variable
233 // ZSYS_SNDHWM is defined, that provides the default. Note that a value of
234 // zero means no limit, i.e. infinite memory consumption.
235 CZMQ_EXPORT void
236 zsys_set_sndhwm (size_t sndhwm);
237 // Configure the default incoming pipe limit (HWM) for new zsock instances.
239 // You can also set this separately on each zsock_t instance. The default
240 // HWM is 1,000, on all versions of ZeroMQ. If the environment variable
241 // ZSYS_RCVHWM is defined, that provides the default. Note that a value of
242 // zero means no limit, i.e. infinite memory consumption.
243 CZMQ_EXPORT void
244 zsys_set_rcvhwm (size_t rcvhwm);
245 // Configure the default HWM for zactor internal pipes; this is set on both
247 // ends of the pipe, for outgoing messages only (sndhwm). The default HWM is
248 // 1,000, on all versions of ZeroMQ. If the environment var ZSYS_ACTORHWM is
249 // defined, that provides the default. Note that a value of zero means no
250 // limit, i.e. infinite memory consumption.
251 CZMQ_EXPORT void
252 zsys_set_pipehwm (size_t pipehwm);
253 // Return the HWM for zactor internal pipes.
255 CZMQ_EXPORT size_t
256 zsys_pipehwm (void);
257 // Configure use of IPv6 for new zsock instances. By default sockets accept
259 // and make only IPv4 connections. When you enable IPv6, sockets will accept
260 // and connect to both IPv4 and IPv6 peers. You can override the setting on
261 // each zsock_t instance. The default is IPv4 only (ipv6 set to 0). If the
262 // environment variable ZSYS_IPV6 is defined (as 1 or 0), this provides the
263 // default. Note: has no effect on ZMQ v2.
264 CZMQ_EXPORT void
265 zsys_set_ipv6 (int ipv6);
266 // Return use of IPv6 for zsock instances.
268 CZMQ_EXPORT int
269 zsys_ipv6 (void);
270 // Set network interface name to use for broadcasts, particularly zbeacon.
272 // This lets the interface be configured for test environments where required.
273 // For example, on Mac OS X, zbeacon cannot bind to 255.255.255.255 which is
274 // the default when there is no specified interface. If the environment
275 // variable ZSYS_INTERFACE is set, use that as the default interface name.
276 // Setting the interface to "*" means "use all available interfaces".
277 CZMQ_EXPORT void
278 zsys_set_interface (const char *value);
279 // Return network interface to use for broadcasts, or "" if none was set.
281 CZMQ_EXPORT const char *
282 zsys_interface (void);
283 // Set IPv6 address to use zbeacon socket, particularly for receiving zbeacon.
285 // This needs to be set IPv6 is enabled as IPv6 can have multiple addresses
286 // on a given interface. If the environment variable ZSYS_IPV6_ADDRESS is set,
287 // use that as the default IPv6 address.
288 CZMQ_EXPORT void
289 zsys_set_ipv6_address (const char *value);
290 // Return IPv6 address to use for zbeacon reception, or "" if none was set.
292 CZMQ_EXPORT const char *
293 zsys_ipv6_address (void);
294 // Set IPv6 milticast address to use for sending zbeacon messages. This needs
296 // to be set if IPv6 is enabled. If the environment variable
297 // ZSYS_IPV6_MCAST_ADDRESS is set, use that as the default IPv6 multicast
298 // address.
299 CZMQ_EXPORT void
300 zsys_set_ipv6_mcast_address (const char *value);
301 // Return IPv6 multicast address to use for sending zbeacon, or "" if none was
303 // set.
304 CZMQ_EXPORT const char *
305 zsys_ipv6_mcast_address (void);
306 // Configure the automatic use of pre-allocated FDs when creating new sockets.
308 // If 0 (default), nothing will happen. Else, when a new socket is bound, the
309 // system API will be used to check if an existing pre-allocated FD with a
310 // matching port (if TCP) or path (if IPC) exists, and if it does it will be
311 // set via the ZMQ_USE_FD socket option so that the library will use it
312 // instead of creating a new socket.
313 CZMQ_EXPORT void
314 zsys_set_auto_use_fd (int auto_use_fd);
315 // Return use of automatic pre-allocated FDs for zsock instances.
317 CZMQ_EXPORT int
318 zsys_auto_use_fd (void);
319 // Set log identity, which is a string that prefixes all log messages sent
321 // by this process. The log identity defaults to the environment variable
322 // ZSYS_LOGIDENT, if that is set.
323 CZMQ_EXPORT void
324 zsys_set_logident (const char *value);
325 // Set stream to receive log traffic. By default, log traffic is sent to
327 // stdout. If you set the stream to NULL, no stream will receive the log
328 // traffic (it may still be sent to the system facility).
329 CZMQ_EXPORT void
330 zsys_set_logstream (FILE *stream);
331 // Sends log output to a PUB socket bound to the specified endpoint. To
333 // collect such log output, create a SUB socket, subscribe to the traffic
334 // you care about, and connect to the endpoint. Log traffic is sent as a
335 // single string frame, in the same format as when sent to stdout. The
336 // log system supports a single sender; multiple calls to this method will
337 // bind the same sender to multiple endpoints. To disable the sender, call
338 // this method with a null argument.
339 CZMQ_EXPORT void
340 zsys_set_logsender (const char *endpoint);
341 // Enable or disable logging to the system facility (syslog on POSIX boxes,
343 // event log on Windows). By default this is disabled.
344 CZMQ_EXPORT void
345 zsys_set_logsystem (bool logsystem);
346 // Log error condition - highest priority
348 CZMQ_EXPORT void
349 zsys_error (const char *format, ...);
350 // Log warning condition - high priority
352 CZMQ_EXPORT void
353 zsys_warning (const char *format, ...);
354 // Log normal, but significant, condition - normal priority
356 CZMQ_EXPORT void
357 zsys_notice (const char *format, ...);
358 // Log informational message - low priority
360 CZMQ_EXPORT void
361 zsys_info (const char *format, ...);
362 // Log debug-level message - lowest priority
364 CZMQ_EXPORT void
365 zsys_debug (const char *format, ...);
366 // Self test of this class
368 CZMQ_EXPORT void
369 zsys_test (bool verbose);
370 // Global signal indicator, TRUE when user presses Ctrl-C or the process
372 // gets a SIGTERM signal.
373 CZMQ_EXPORT extern volatile int zsys_interrupted;
374 // Deprecated name for this variable
375 CZMQ_EXPORT extern volatile int zctx_interrupted;
376 Please add '@interface' section in './../src/zsys.c'.
377
379 The zsys class provides a portable wrapper for system calls. We collect
380 them here to reduce the number of weird #ifdefs in other classes. As
381 far as possible, the bulk of CZMQ classes are fully portable.
382 Please add @discuss section in ./../src/zsys.c.
384
386 From zsys_test method.
387 zsys_catch_interrupts ();
389 // Check capabilities without using the return value
391 int rc = zsys_has_curve ();
392 if (verbose) {
394 char *hostname = zsys_hostname ();
395 zsys_info ("host name is %s", hostname);
396 free (hostname);
397 zsys_info ("system limit is %zu ZeroMQ sockets", zsys_socket_limit ());
398 }
399 zsys_set_linger (0);
400 zsys_set_sndhwm (1000);
401 zsys_set_rcvhwm (1000);
402 zsys_set_pipehwm (2500);
403 assert (zsys_pipehwm () == 2500);
404 zsys_set_ipv6 (0);
405 // Test pipe creation
407 zsock_t *pipe_back;
408 zsock_t *pipe_front = zsys_create_pipe (&pipe_back);
409 zstr_send (pipe_front, "Hello");
410 char *string = zstr_recv (pipe_back);
411 assert (streq (string, "Hello"));
412 free (string);
413 zsock_destroy (&pipe_back);
414 zsock_destroy (&pipe_front);
415 // Test file manipulation
417 rc = zsys_file_delete ("nosuchfile");
418 assert (rc == -1);
419 bool rc_bool = zsys_file_exists ("nosuchfile");
421 assert (rc_bool != true);
422 rc = (int) zsys_file_size ("nosuchfile");
424 assert (rc == -1);
425 time_t when = zsys_file_modified (".");
427 assert (when > 0);
428 int mode = zsys_file_mode (".");
430 assert (S_ISDIR (mode));
431 assert (mode & S_IRUSR);
432 assert (mode & S_IWUSR);
433 zsys_file_mode_private ();
435 rc = zsys_dir_create ("%s/%s", ".", ".testsys/subdir");
436 assert (rc == 0);
437 when = zsys_file_modified ("./.testsys/subdir");
438 assert (when > 0);
439 assert (!zsys_file_stable ("./.testsys/subdir"));
440 rc = zsys_dir_delete ("%s/%s", ".", ".testsys/subdir");
441 assert (rc == 0);
442 rc = zsys_dir_delete ("%s/%s", ".", ".testsys");
443 assert (rc == 0);
444 zsys_file_mode_default ();
445 assert (zsys_dir_change (".") == 0);
446 int major, minor, patch;
448 zsys_version (&major, &minor, &patch);
449 assert (major == CZMQ_VERSION_MAJOR);
450 assert (minor == CZMQ_VERSION_MINOR);
451 assert (patch == CZMQ_VERSION_PATCH);
452 string = zsys_sprintf ("%s %02x", "Hello", 16);
454 assert (streq (string, "Hello 10"));
455 free (string);
456 char *str64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890,.";
458 int num10 = 1234567890;
459 string = zsys_sprintf ("%s%s%s%s%d", str64, str64, str64, str64, num10);
460 assert (strlen (string) == (4 * 64 + 10));
461 free (string);
462 // Test logging system
464 zsys_set_logident ("czmq_selftest");
465 zsys_set_logsender ("inproc://logging");
466 void *logger = zsys_socket (ZMQ_SUB, NULL, 0);
467 assert (logger);
468 rc = zmq_connect (logger, "inproc://logging");
469 assert (rc == 0);
470 rc = zmq_setsockopt (logger, ZMQ_SUBSCRIBE, "", 0);
471 assert (rc == 0);
472 if (verbose) {
474 zsys_error ("This is an %s message", "error");
475 zsys_warning ("This is a %s message", "warning");
476 zsys_notice ("This is a %s message", "notice");
477 zsys_info ("This is a %s message", "info");
478 zsys_debug ("This is a %s message", "debug");
479 zsys_set_logident ("hello, world");
480 zsys_info ("This is a %s message", "info");
481 zsys_debug ("This is a %s message", "debug");
482 // Check that logsender functionality is working
484 char *received = zstr_recv (logger);
485 assert (received);
486 zstr_free (&received);
487 }
488 zsys_close (logger, NULL, 0);
489
492 The czmq manual was written by the authors in the AUTHORS file.
493
495 Main web site:
496 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
498
500 Copyright (c) the Contributors as noted in the AUTHORS file. This file
501 is part of CZMQ, the high-level C binding for 0MQ:
502 http://czmq.zeromq.org. This Source Code Form is subject to the terms
503 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
504 distributed with this file, You can obtain one at
505 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
506 distribution.
507
509 1. zeromq-dev@lists.zeromq.org
510 mailto:zeromq-dev@lists.zeromq.org
511CZMQ 4.0.2 07/13/2018 ZSYS(3)