1ZSYS(3) CZMQ Manual ZSYS(3)
2
6 zsys - Class for system-level methods
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 // Callback for interrupt signal handler
14 typedef void (zsys_handler_fn) (
15 int signal_value);
16 // Initialize CZMQ zsys layer; this happens automatically when you create
18 // a socket or an actor; however this call lets you force initialization
19 // earlier, so e.g. logging is properly set-up before you start working.
20 // Not threadsafe, so call only from main thread. Safe to call multiple
21 // times. Returns global CZMQ context.
22 CZMQ_EXPORT void *
23 zsys_init (void);
24 // Optionally shut down the CZMQ zsys layer; this normally happens automatically
26 // when the process exits; however this call lets you force a shutdown
27 // earlier, avoiding any potential problems with atexit() ordering, especially
28 // with Windows dlls.
29 CZMQ_EXPORT void
30 zsys_shutdown (void);
31 // Get a new ZMQ socket, automagically creating a ZMQ context if this is
33 // the first time. Caller is responsible for destroying the ZMQ socket
34 // before process exits, to avoid a ZMQ deadlock. Note: you should not use
35 // this method in CZMQ apps, use zsock_new() instead.
36 // *** This is for CZMQ internal use only and may change arbitrarily ***
37 CZMQ_EXPORT void *
38 zsys_socket (int type, const char *filename, size_t line_nbr);
39 // Destroy/close a ZMQ socket. You should call this for every socket you
41 // create using zsys_socket().
42 // *** This is for CZMQ internal use only and may change arbitrarily ***
43 CZMQ_EXPORT int
44 zsys_close (void *handle, const char *filename, size_t line_nbr);
45 // Return ZMQ socket name for socket type
47 // *** This is for CZMQ internal use only and may change arbitrarily ***
48 CZMQ_EXPORT char *
49 zsys_sockname (int socktype);
50 // Create a pipe, which consists of two PAIR sockets connected over inproc.
52 // The pipe is configured to use the zsys_pipehwm setting. Returns the
53 // frontend socket successful, NULL if failed.
54 CZMQ_EXPORT zsock_t *
55 zsys_create_pipe (zsock_t **backend_p);
56 // Set interrupt handler; this saves the default handlers so that a
58 // zsys_handler_reset () can restore them. If you call this multiple times
59 // then the last handler will take affect. If handler_fn is NULL, disables
60 // default SIGINT/SIGTERM handling in CZMQ.
61 CZMQ_EXPORT void
62 zsys_handler_set (zsys_handler_fn *handler_fn);
63 // Reset interrupt handler, call this at exit if needed
65 CZMQ_EXPORT void
66 zsys_handler_reset (void);
67 // Set default interrupt handler, so Ctrl-C or SIGTERM will set
69 // zsys_interrupted. Idempotent; safe to call multiple times.
70 // Can be suppressed by ZSYS_SIGHANDLER=false
71 // *** This is for CZMQ internal use only and may change arbitrarily ***
72 CZMQ_EXPORT void
73 zsys_catch_interrupts (void);
74 // Return 1 if file exists, else zero
76 CZMQ_EXPORT bool
77 zsys_file_exists (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
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 if IPv6 is disabled or
157 // NI_MAXHOST if it's enabled. Returns NULL when failing to get peer address.
158 // *** This is for CZMQ internal use only and may change arbitrarily ***
159 CZMQ_EXPORT zframe_t *
160 zsys_udp_recv (SOCKET udpsock, char *peername, int peerlen);
161 // Handle an I/O error on some socket operation; will report and die on
163 // fatal errors, and continue silently on "try again" errors.
164 // *** This is for CZMQ internal use only and may change arbitrarily ***
165 CZMQ_EXPORT void
166 zsys_socket_error (const char *reason);
167 // Return current host name, for use in public tcp:// endpoints. Caller gets
169 // a freshly allocated string, should free it using zstr_free(). If the host
170 // name is not resolvable, returns NULL.
171 CZMQ_EXPORT char *
172 zsys_hostname (void);
173 // Move the current process into the background. The precise effect depends
175 // on the operating system. On POSIX boxes, moves to a specified working
176 // directory (if specified), closes all file handles, reopens stdin, stdout,
177 // and stderr to the null device, and sets the process to ignore SIGHUP. On
178 // Windows, does nothing. Returns 0 if OK, -1 if there was an error.
179 CZMQ_EXPORT int
180 zsys_daemonize (const char *workdir);
181 // Drop the process ID into the lockfile, with exclusive lock, and switch
183 // the process to the specified group and/or user. Any of the arguments
184 // may be null, indicating a no-op. Returns 0 on success, -1 on failure.
185 // Note if you combine this with zsys_daemonize, run after, not before
186 // that method, or the lockfile will hold the wrong process ID.
187 CZMQ_EXPORT int
188 zsys_run_as (const char *lockfile, const char *group, const char *user);
189 // Returns true if the underlying libzmq supports CURVE security.
191 // Uses a heuristic probe according to the version of libzmq being used.
192 CZMQ_EXPORT bool
193 zsys_has_curve (void);
194 // Configure the number of I/O threads that ZeroMQ will use. A good
196 // rule of thumb is one thread per gigabit of traffic in or out. The
197 // default is 1, sufficient for most applications. If the environment
198 // variable ZSYS_IO_THREADS is defined, that provides the default.
199 // Note that this method is valid only before any socket is created.
200 CZMQ_EXPORT void
201 zsys_set_io_threads (size_t io_threads);
202 // Configure the scheduling policy of the ZMQ context thread pool.
204 // Not available on Windows. See the sched_setscheduler man page or sched.h
205 // for more information. If the environment variable ZSYS_THREAD_SCHED_POLICY
206 // is defined, that provides the default.
207 // Note that this method is valid only before any socket is created.
208 CZMQ_EXPORT void
209 zsys_set_thread_sched_policy (int policy);
210 // Configure the scheduling priority of the ZMQ context thread pool.
212 // Not available on Windows. See the sched_setscheduler man page or sched.h
213 // for more information. If the environment variable ZSYS_THREAD_PRIORITY is
214 // defined, that provides the default.
215 // Note that this method is valid only before any socket is created.
216 CZMQ_EXPORT void
217 zsys_set_thread_priority (int priority);
218 // Configure the numeric prefix to each thread created for the internal
220 // context's thread pool. This option is only supported on Linux.
221 // If the environment variable ZSYS_THREAD_NAME_PREFIX is defined, that
222 // provides the default.
223 // Note that this method is valid only before any socket is created.
224 CZMQ_EXPORT void
225 zsys_set_thread_name_prefix (int prefix);
226 // Return thread name prefix.
228 CZMQ_EXPORT int
229 zsys_thread_name_prefix (void);
230 // Adds a specific CPU to the affinity list of the ZMQ context thread pool.
232 // This option is only supported on Linux.
233 // Note that this method is valid only before any socket is created.
234 CZMQ_EXPORT void
235 zsys_thread_affinity_cpu_add (int cpu);
236 // Removes a specific CPU to the affinity list of the ZMQ context thread pool.
238 // This option is only supported on Linux.
239 // Note that this method is valid only before any socket is created.
240 CZMQ_EXPORT void
241 zsys_thread_affinity_cpu_remove (int cpu);
242 // Configure the number of sockets that ZeroMQ will allow. The default
244 // is 1024. The actual limit depends on the system, and you can query it
245 // by using zsys_socket_limit (). A value of zero means "maximum".
246 // Note that this method is valid only before any socket is created.
247 CZMQ_EXPORT void
248 zsys_set_max_sockets (size_t max_sockets);
249 // Return maximum number of ZeroMQ sockets that the system will support.
251 CZMQ_EXPORT size_t
252 zsys_socket_limit (void);
253 // Configure the maximum allowed size of a message sent.
255 // The default is INT_MAX.
256 CZMQ_EXPORT void
257 zsys_set_max_msgsz (int max_msgsz);
258 // Return maximum message size.
260 CZMQ_EXPORT int
261 zsys_max_msgsz (void);
262 // Configure the default linger timeout in msecs for new zsock instances.
264 // You can also set this separately on each zsock_t instance. The default
265 // linger time is zero, i.e. any pending messages will be dropped. If the
266 // environment variable ZSYS_LINGER is defined, that provides the default.
267 // Note that process exit will typically be delayed by the linger time.
268 CZMQ_EXPORT void
269 zsys_set_linger (size_t linger);
270 // Configure the default outgoing pipe limit (HWM) for new zsock instances.
272 // You can also set this separately on each zsock_t instance. The default
273 // HWM is 1,000, on all versions of ZeroMQ. If the environment variable
274 // ZSYS_SNDHWM is defined, that provides the default. Note that a value of
275 // zero means no limit, i.e. infinite memory consumption.
276 CZMQ_EXPORT void
277 zsys_set_sndhwm (size_t sndhwm);
278 // Configure the default incoming pipe limit (HWM) for new zsock instances.
280 // You can also set this separately on each zsock_t instance. The default
281 // HWM is 1,000, on all versions of ZeroMQ. If the environment variable
282 // ZSYS_RCVHWM is defined, that provides the default. Note that a value of
283 // zero means no limit, i.e. infinite memory consumption.
284 CZMQ_EXPORT void
285 zsys_set_rcvhwm (size_t rcvhwm);
286 // Configure the default HWM for zactor internal pipes; this is set on both
288 // ends of the pipe, for outgoing messages only (sndhwm). The default HWM is
289 // 1,000, on all versions of ZeroMQ. If the environment var ZSYS_ACTORHWM is
290 // defined, that provides the default. Note that a value of zero means no
291 // limit, i.e. infinite memory consumption.
292 CZMQ_EXPORT void
293 zsys_set_pipehwm (size_t pipehwm);
294 // Return the HWM for zactor internal pipes.
296 CZMQ_EXPORT size_t
297 zsys_pipehwm (void);
298 // Configure use of IPv6 for new zsock instances. By default sockets accept
300 // and make only IPv4 connections. When you enable IPv6, sockets will accept
301 // and connect to both IPv4 and IPv6 peers. You can override the setting on
302 // each zsock_t instance. The default is IPv4 only (ipv6 set to 0). If the
303 // environment variable ZSYS_IPV6 is defined (as 1 or 0), this provides the
304 // default. Note: has no effect on ZMQ v2.
305 CZMQ_EXPORT void
306 zsys_set_ipv6 (int ipv6);
307 // Return use of IPv6 for zsock instances.
309 CZMQ_EXPORT int
310 zsys_ipv6 (void);
311 // Set network interface name to use for broadcasts, particularly zbeacon.
313 // This lets the interface be configured for test environments where required.
314 // For example, on Mac OS X, zbeacon cannot bind to 255.255.255.255 which is
315 // the default when there is no specified interface. If the environment
316 // variable ZSYS_INTERFACE is set, use that as the default interface name.
317 // Setting the interface to "*" means "use all available interfaces".
318 CZMQ_EXPORT void
319 zsys_set_interface (const char *value);
320 // Return network interface to use for broadcasts, or "" if none was set.
322 CZMQ_EXPORT const char *
323 zsys_interface (void);
324 // Set IPv6 address to use zbeacon socket, particularly for receiving zbeacon.
326 // This needs to be set IPv6 is enabled as IPv6 can have multiple addresses
327 // on a given interface. If the environment variable ZSYS_IPV6_ADDRESS is set,
328 // use that as the default IPv6 address.
329 CZMQ_EXPORT void
330 zsys_set_ipv6_address (const char *value);
331 // Return IPv6 address to use for zbeacon reception, or "" if none was set.
333 CZMQ_EXPORT const char *
334 zsys_ipv6_address (void);
335 // Set IPv6 milticast address to use for sending zbeacon messages. This needs
337 // to be set if IPv6 is enabled. If the environment variable
338 // ZSYS_IPV6_MCAST_ADDRESS is set, use that as the default IPv6 multicast
339 // address.
340 CZMQ_EXPORT void
341 zsys_set_ipv6_mcast_address (const char *value);
342 // Return IPv6 multicast address to use for sending zbeacon, or "" if none was
344 // set.
345 CZMQ_EXPORT const char *
346 zsys_ipv6_mcast_address (void);
347 // Configure the automatic use of pre-allocated FDs when creating new sockets.
349 // If 0 (default), nothing will happen. Else, when a new socket is bound, the
350 // system API will be used to check if an existing pre-allocated FD with a
351 // matching port (if TCP) or path (if IPC) exists, and if it does it will be
352 // set via the ZMQ_USE_FD socket option so that the library will use it
353 // instead of creating a new socket.
354 CZMQ_EXPORT void
355 zsys_set_auto_use_fd (int auto_use_fd);
356 // Return use of automatic pre-allocated FDs for zsock instances.
358 CZMQ_EXPORT int
359 zsys_auto_use_fd (void);
360 // Set log identity, which is a string that prefixes all log messages sent
362 // by this process. The log identity defaults to the environment variable
363 // ZSYS_LOGIDENT, if that is set.
364 CZMQ_EXPORT void
365 zsys_set_logident (const char *value);
366 // Set stream to receive log traffic. By default, log traffic is sent to
368 // stdout. If you set the stream to NULL, no stream will receive the log
369 // traffic (it may still be sent to the system facility).
370 CZMQ_EXPORT void
371 zsys_set_logstream (FILE *stream);
372 // Sends log output to a PUB socket bound to the specified endpoint. To
374 // collect such log output, create a SUB socket, subscribe to the traffic
375 // you care about, and connect to the endpoint. Log traffic is sent as a
376 // single string frame, in the same format as when sent to stdout. The
377 // log system supports a single sender; multiple calls to this method will
378 // bind the same sender to multiple endpoints. To disable the sender, call
379 // this method with a null argument.
380 CZMQ_EXPORT void
381 zsys_set_logsender (const char *endpoint);
382 // Enable or disable logging to the system facility (syslog on POSIX boxes,
384 // event log on Windows). By default this is disabled.
385 CZMQ_EXPORT void
386 zsys_set_logsystem (bool logsystem);
387 // Log error condition - highest priority
389 CZMQ_EXPORT void
390 zsys_error (const char *format, ...);
391 // Log warning condition - high priority
393 CZMQ_EXPORT void
394 zsys_warning (const char *format, ...);
395 // Log normal, but significant, condition - normal priority
397 CZMQ_EXPORT void
398 zsys_notice (const char *format, ...);
399 // Log informational message - low priority
401 CZMQ_EXPORT void
402 zsys_info (const char *format, ...);
403 // Log debug-level message - lowest priority
405 CZMQ_EXPORT void
406 zsys_debug (const char *format, ...);
407 // Self test of this class.
409 CZMQ_EXPORT void
410 zsys_test (bool verbose);
411 #ifdef CZMQ_BUILD_DRAFT_API
413 // *** Draft method, for development use, may change without warning ***
414 // Check if default interrupt handler of Ctrl-C or SIGTERM was called.
415 // Does not work if ZSYS_SIGHANDLER is false and code does not call
416 // set interrupted on signal.
417 CZMQ_EXPORT bool
418 zsys_is_interrupted (void);
419 // *** Draft method, for development use, may change without warning ***
421 // Set interrupted flag. This is done by default signal handler, however
422 // this can be handy for language bindings or cases without default
423 // signal handler.
424 CZMQ_EXPORT void
425 zsys_set_interrupted (void);
426 // *** Draft method, for development use, may change without warning ***
428 // Format a string using printf formatting, returning a freshly allocated
429 // buffer. If there was insufficient memory, returns NULL. Free the returned
430 // string using zstr_free(). The hinted version allows to optimize by using
431 // a larger starting buffer size (known to/assumed by the developer) and so
432 // avoid reallocations.
433 CZMQ_EXPORT char *
434 zsys_sprintf_hint (int hint, const char *format, ...);
435 // *** Draft method, for development use, may change without warning ***
437 // Configure the numeric prefix to each thread created for the internal
438 // context's thread pool. This option is only supported on Linux.
439 // If the environment variable ZSYS_THREAD_NAME_PREFIX_STR is defined, that
440 // provides the default.
441 // Note that this method is valid only before any socket is created.
442 CZMQ_EXPORT void
443 zsys_set_thread_name_prefix_str (const char *prefix);
444 // *** Draft method, for development use, may change without warning ***
446 // Return thread name prefix.
447 CZMQ_EXPORT const char *
448 zsys_thread_name_prefix_str (void);
449 // *** Draft method, for development use, may change without warning ***
451 // Configure whether to use zero copy strategy in libzmq. If the environment
452 // variable ZSYS_ZERO_COPY_RECV is defined, that provides the default.
453 // Otherwise the default is 1.
454 CZMQ_EXPORT void
455 zsys_set_zero_copy_recv (int zero_copy);
456 // *** Draft method, for development use, may change without warning ***
458 // Return ZMQ_ZERO_COPY_RECV option.
459 CZMQ_EXPORT int
460 zsys_zero_copy_recv (void);
461 // *** Draft method, for development use, may change without warning ***
463 // Configure the threshold value of filesystem object age per st_mtime
464 // that should elapse until we consider that object "stable" at the
465 // current zclock_time() moment.
466 // The default is S_DEFAULT_ZSYS_FILE_STABLE_AGE_MSEC defined in zsys.c
467 // which generally depends on host OS, with fallback value of 5000.
468 CZMQ_EXPORT void
469 zsys_set_file_stable_age_msec (int64_t file_stable_age_msec);
470 // *** Draft method, for development use, may change without warning ***
472 // Return current threshold value of file stable age in msec.
473 // This can be used in code that chooses to wait for this timeout
474 // before testing if a filesystem object is "stable" or not.
475 CZMQ_EXPORT int64_t
476 zsys_file_stable_age_msec (void);
477 // *** Draft method, for development use, may change without warning ***
479 // Test if ipv6 is available on the system. Return true if available.
480 // The only way to reliably check is to actually open a socket and
481 // try to bind it. (ported from libzmq)
482 CZMQ_EXPORT bool
483 zsys_ipv6_available (void);
484 // *** Draft method, for development use, may change without warning ***
486 // Set IPv4 multicast address to use for sending zbeacon messages. By default
487 // IPv4 multicast is NOT used. If the environment variable
488 // ZSYS_IPV4_MCAST_ADDRESS is set, use that as the default IPv4 multicast
489 // address. Calling this function or setting ZSYS_IPV4_MCAST_ADDRESS
490 // will enable IPv4 zbeacon messages.
491 CZMQ_EXPORT void
492 zsys_set_ipv4_mcast_address (const char *value);
493 // *** Draft method, for development use, may change without warning ***
495 // Return IPv4 multicast address to use for sending zbeacon, or NULL if none was
496 // set.
497 CZMQ_EXPORT const char *
498 zsys_ipv4_mcast_address (void);
499 // *** Draft method, for development use, may change without warning ***
501 // Set multicast TTL default is 1
502 CZMQ_EXPORT void
503 zsys_set_mcast_ttl (byte value);
504 // *** Draft method, for development use, may change without warning ***
506 // Get multicast TTL
507 CZMQ_EXPORT byte
508 zsys_mcast_ttl (void);
509 // *** Draft method, for development use, may change without warning ***
511 // Print formatted string. Format is specified by variable names
512 // in Python-like format style
513 //
514 // "%(KEY)s=%(VALUE)s", KEY=key, VALUE=value
515 // become
516 // "key=value"
517 //
518 // Returns freshly allocated string or NULL in a case of error.
519 // Not enough memory, invalid format specifier, name not in args
520 // Caller owns return value and must destroy it when done.
521 CZMQ_EXPORT char *
522 zsys_zprintf (const char *format, zhash_t *args);
523 // *** Draft method, for development use, may change without warning ***
525 // Return error string for given format/args combination.
526 // Caller owns return value and must destroy it when done.
527 CZMQ_EXPORT char *
528 zsys_zprintf_error (const char *format, zhash_t *args);
529 // *** Draft method, for development use, may change without warning ***
531 // Print formatted string. Format is specified by variable names
532 // in Python-like format style
533 //
534 // "%(KEY)s=%(VALUE)s", KEY=key, VALUE=value
535 // become
536 // "key=value"
537 //
538 // Returns freshly allocated string or NULL in a case of error.
539 // Not enough memory, invalid format specifier, name not in args
540 // Caller owns return value and must destroy it when done.
541 CZMQ_EXPORT char *
542 zsys_zplprintf (const char *format, zconfig_t *args);
543 // *** Draft method, for development use, may change without warning ***
545 // Return error string for given format/args combination.
546 // Caller owns return value and must destroy it when done.
547 CZMQ_EXPORT char *
548 zsys_zplprintf_error (const char *format, zconfig_t *args);
549 #endif // CZMQ_BUILD_DRAFT_API
551 Please add '@interface' section in './../src/zsys.c'.
552
554 The zsys class provides a portable wrapper for system calls. We collect
555 them here to reduce the number of weird #ifdefs in other classes. As
556 far as possible, the bulk of CZMQ classes are fully portable.
557 Please add @discuss section in ./../src/zsys.c.
559
561 From zsys_test method.
562 zsys_catch_interrupts ();
564 // Check capabilities without using the return value
566 int rc = zsys_has_curve ();
567 const char *SELFTEST_DIR_RW = "src/selftest-rw";
569 if (verbose) {
571 char *hostname = zsys_hostname ();
572 zsys_info ("host name is %s", hostname);
573 freen (hostname);
574 zsys_info ("system limit is %zu ZeroMQ sockets", zsys_socket_limit ());
575 }
576 #ifdef CZMQ_BUILD_DRAFT_API
577 zsys_set_file_stable_age_msec (5123);
578 assert (zsys_file_stable_age_msec() == 5123);
579 zsys_set_file_stable_age_msec (-1);
580 assert (zsys_file_stable_age_msec() == 5123);
581 #endif // CZMQ_BUILD_DRAFT_API
582 zsys_set_linger (0);
583 zsys_set_sndhwm (1000);
584 zsys_set_rcvhwm (1000);
585 zsys_set_pipehwm (2500);
586 assert (zsys_pipehwm () == 2500);
587 zsys_set_ipv6 (0);
588 zsys_set_thread_priority (-1);
589 zsys_set_thread_sched_policy (-1);
590 zsys_set_thread_name_prefix (0);
591 assert (0 == zsys_thread_name_prefix());
592 assert (streq ("0", zsys_thread_name_prefix_str()));
593 zsys_thread_affinity_cpu_add (0);
594 zsys_thread_affinity_cpu_remove (0);
595 zsys_set_zero_copy_recv(0);
596 assert (0 == zsys_zero_copy_recv());
597 zsys_set_zero_copy_recv(1);
598 assert (1 == zsys_zero_copy_recv());
599 // Test pipe creation
601 zsock_t *pipe_back;
602 zsock_t *pipe_front = zsys_create_pipe (&pipe_back);
603 zstr_send (pipe_front, "Hello");
604 char *string = zstr_recv (pipe_back);
605 assert (streq (string, "Hello"));
606 freen (string);
607 zsock_destroy (&pipe_back);
608 zsock_destroy (&pipe_front);
609 // Test file manipulation
611 // Don't let anyone fool our workspace
613 if (zsys_file_exists ("nosuchfile")) {
614 zsys_warning ("zsys_test() had to remove 'nosuchfile' which was not expected here at all");
615 zsys_file_delete ("nosuchfile");
616 }
617 rc = zsys_file_delete ("nosuchfile");
619 assert (rc == -1);
620 bool rc_bool = zsys_file_exists ("nosuchfile");
622 assert (rc_bool != true);
623 rc = (int) zsys_file_size ("nosuchfile");
625 assert (rc == -1);
626 time_t when = zsys_file_modified (".");
628 assert (when > 0);
629 int mode = zsys_file_mode (".");
631 assert (S_ISDIR (mode));
632 assert (mode & S_IRUSR);
633 assert (mode & S_IWUSR);
634 const char *testbasedir = ".testsys";
636 const char *testsubdir = "subdir";
637 char *basedirpath = NULL; // subdir in a test, under SELFTEST_DIR_RW
638 char *dirpath = NULL; // subdir in a test, under basedirpath
639 char *relsubdir = NULL; // relative short "path" of subdir under testbasedir
640 basedirpath = zsys_sprintf ("%s/%s", SELFTEST_DIR_RW, testbasedir);
642 assert (basedirpath);
643 dirpath = zsys_sprintf ("%s/%s", basedirpath, testsubdir);
644 assert (dirpath);
645 relsubdir = zsys_sprintf ("%s/%s", testbasedir, testsubdir);
646 assert (relsubdir);
647 // Normally tests clean up in the end, but if a selftest run dies
649 // e.g. on assert(), workspace remains dirty. Better clean it up.
650 // We do not really care about results here - we clean up a possible
651 // dirty exit of an older build. If there are permission errors etc.
652 // the actual tests below would explode.
653 if (zsys_file_exists(dirpath)) {
654 if (verbose)
655 zsys_debug ("zsys_test() has to remove ./%s that should not have been here", dirpath);
656 zsys_dir_delete (dirpath);
657 }
658 if (zsys_file_exists (basedirpath)) {
659 if (verbose)
660 zsys_debug ("zsys_test() has to remove ./%s that should not have been here", basedirpath);
661 zsys_dir_delete (basedirpath);
662 }
663 // Added tracing because this file-age check fails on some systems
665 // presumably due to congestion in a mass-build and valgrind on top
666 zsys_file_mode_private ();
667 if (verbose)
668 printf ("zsys_test() at timestamp %" PRIi64 ": "
669 "Creating %s\n",
670 zclock_time(), relsubdir );
671 rc = zsys_dir_create ("%s/%s", SELFTEST_DIR_RW, relsubdir);
672 if (verbose)
673 printf ("zsys_test() at timestamp %" PRIi64 ": "
674 "Finished creating %s with return-code %d\n",
675 zclock_time(), relsubdir, rc );
676 assert (rc == 0);
677 when = zsys_file_modified (dirpath);
678 if (verbose)
679 printf ("zsys_test() at timestamp %" PRIi64 ": "
680 "Finished calling zsys_file_modified(), got age %jd\n",
681 zclock_time(), (intmax_t)when );
682 assert (when > 0);
683 if (verbose)
684 printf ("zsys_test() at timestamp %" PRIi64 ": "
685 "Checking if file is NOT stable (is younger than 1 sec)\n",
686 zclock_time() );
687 assert (!s_zsys_file_stable (dirpath, verbose));
688 if (verbose)
689 printf ("zsys_test() at timestamp %" PRIi64 ": "
690 "Passed the test, file is not stable - as expected\n",
691 zclock_time() );
692 rc = zsys_dir_delete ("%s/%s", SELFTEST_DIR_RW, relsubdir);
693 assert (rc == 0);
694 rc = zsys_dir_delete ("%s/%s", SELFTEST_DIR_RW, testbasedir);
695 assert (rc == 0);
696 zsys_file_mode_default ();
697 #if (defined (PATH_MAX))
699 char cwd[PATH_MAX];
700 #else
701 # if (defined (_MAX_PATH))
702 char cwd[_MAX_PATH];
703 # else
704 char cwd[1024];
705 # endif
706 #endif
707 memset (cwd, 0, sizeof(cwd));
708 #if (defined (WIN32))
709 if (_getcwd(cwd, sizeof(cwd)) != NULL) {
710 #else
711 if (getcwd(cwd, sizeof(cwd)) != NULL) {
712 #endif
713 if (verbose)
714 printf ("zsys_test() at timestamp %" PRIi64 ": "
715 "current working directory is %s\n",
716 zclock_time(), cwd);
717 assert (zsys_dir_change (SELFTEST_DIR_RW) == 0);
718 assert (zsys_dir_change (cwd) == 0);
719 }
720 else {
721 zsys_warning ("zsys_test() : got getcwd() error... "
722 "testing zsys_dir_change() anyway, but it can confuse "
723 "subsequent tests in this process");
724 assert (zsys_dir_change (SELFTEST_DIR_RW) == 0);
725 }
726 zstr_free (&basedirpath);
728 zstr_free (&dirpath);
729 zstr_free (&relsubdir);
730 // Other subtests
732 int major, minor, patch;
733 zsys_version (&major, &minor, &patch);
734 assert (major == CZMQ_VERSION_MAJOR);
735 assert (minor == CZMQ_VERSION_MINOR);
736 assert (patch == CZMQ_VERSION_PATCH);
737 string = zsys_sprintf ("%s %02x", "Hello", 16);
739 assert (streq (string, "Hello 10"));
740 freen (string);
741 char *str64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890,.";
743 int num10 = 1234567890;
744 string = zsys_sprintf ("%s%s%s%s%d", str64, str64, str64, str64, num10);
745 assert (strlen (string) == (4 * 64 + 10));
746 freen (string);
747 // Test logging system
749 zsys_set_logident ("czmq_selftest");
750 zsys_set_logsender ("inproc://logging");
751 void *logger = zsys_socket (ZMQ_SUB, NULL, 0);
752 assert (logger);
753 rc = zmq_connect (logger, "inproc://logging");
754 assert (rc == 0);
755 rc = zmq_setsockopt (logger, ZMQ_SUBSCRIBE, "", 0);
756 assert (rc == 0);
757 if (verbose) {
759 zsys_error ("This is an %s message", "error");
760 zsys_warning ("This is a %s message", "warning");
761 zsys_notice ("This is a %s message", "notice");
762 zsys_info ("This is a %s message", "info");
763 zsys_debug ("This is a %s message", "debug");
764 zsys_set_logident ("hello, world");
765 zsys_info ("This is a %s message", "info");
766 zsys_debug ("This is a %s message", "debug");
767 // Check that logsender functionality is working
769 char *received = zstr_recv (logger);
770 assert (received);
771 zstr_free (&received);
772 }
773 zsys_close (logger, NULL, 0);
774 {
776 // zhash based printf
777 zhash_t *args = zhash_new ();
778 zhash_insert (args, "key", "value");
779 zhash_insert (args, "ham", "spam");
780 char *str = zsys_zprintf ("plain string", args);
782 assert (streq (str, "plain string"));
783 zstr_free (&str);
784 str = zsys_zprintf ("%%a%%", args);
786 assert (streq (str, "%a%"));
787 zstr_free (&str);
788 str = zsys_zprintf ("VALUE=%(key)s123", args);
790 assert (streq (str, "VALUE=value123"));
791 zstr_free (&str);
792 str = zsys_zprintf ("VALUE=%(key)s123, %(ham)s, %(ham)s, %%(nospam)s!!!", args);
794 assert (streq (str, "VALUE=value123, spam, spam, %(nospam)s!!!"));
795 zstr_free (&str);
796 str = zsys_zprintf ("VALUE=%(nokey)s123, %(ham)s, %(ham)s, %%(nospam)s!!!", args);
798 assert (!str);
799 str = zsys_zprintf_error ("VALUE=%(nokey)s123, %(ham)s, %(ham)s, %%(nospam)s!!!", args);
801 assert (streq (str, "Key 'nokey' not found in hash"));
802 zstr_free (&str);
803 str = zsys_zprintf ("VALUE=%(key)s/%%S", args);
805 assert (streq (str, "VALUE=value/%S"));
806 zstr_free (&str);
807 zhash_destroy (&args);
809 //ZPL based printf
811 zconfig_t *root = zconfig_new ("root", NULL);
812 zconfig_put (root, "zsp", "");
813 zconfig_put (root, "zsp/return_code", "0");
814 str = zsys_zplprintf ("return_code=%(zsp/return_code)s", root);
816 assert (streq (str, "return_code=0"));
817 zstr_free (&str);
818 zconfig_destroy (&root);
820 }
821
824 The czmq manual was written by the authors in the AUTHORS file.
825
827 Main web site:
828 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
830
832 Copyright (c) the Contributors as noted in the AUTHORS file. This file
833 is part of CZMQ, the high-level C binding for 0MQ:
834 http://czmq.zeromq.org. This Source Code Form is subject to the terms
835 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
836 distributed with this file, You can obtain one at
837 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
838 distribution.
839
841 1. zeromq-dev@lists.zeromq.org
842 mailto:zeromq-dev@lists.zeromq.org
843CZMQ 4.2.1 07/19/2023 ZSYS(3)