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

NAME

6       zsys - Class for system-level methods
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       // Callback for interrupt signal handler
14       typedef void (zsys_handler_fn) (
15           int signal_value);
16
17       //  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
25       //  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
32       //  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
40       //  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
46       //  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
51       //  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
57       //  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
64       //  Reset interrupt handler, call this at exit if needed
65       CZMQ_EXPORT void
66           zsys_handler_reset (void);
67
68       //  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
75       //  Return 1 if file exists, else zero
76       CZMQ_EXPORT bool
77           zsys_file_exists (const char *filename);
78
79       //  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
83       //  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
89       //  Delete file. Does not complain if the file is absent
90       CZMQ_EXPORT int
91           zsys_file_delete (const char *filename);
92
93       //  Check if file is 'stable'
94       CZMQ_EXPORT bool
95           zsys_file_stable (const char *filename);
96
97       //  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
102       //  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
106       //  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
110       //  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
115       //  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
120       //  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
125       //  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
131       //  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
137       //  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
144       //  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
149       //  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
155       //  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
162       //  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
168       //  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
174       //  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
182       //  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
190       //  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
195       //  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
203       //  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
211       //  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
219       //  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
227       //  Return thread name prefix.
228       CZMQ_EXPORT int
229           zsys_thread_name_prefix (void);
230
231       //  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
237       //  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
243       //  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
250       //  Return maximum number of ZeroMQ sockets that the system will support.
251       CZMQ_EXPORT size_t
252           zsys_socket_limit (void);
253
254       //  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
259       //  Return maximum message size.
260       CZMQ_EXPORT int
261           zsys_max_msgsz (void);
262
263       //  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
271       //  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
279       //  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
287       //  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
295       //  Return the HWM for zactor internal pipes.
296       CZMQ_EXPORT size_t
297           zsys_pipehwm (void);
298
299       //  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
308       //  Return use of IPv6 for zsock instances.
309       CZMQ_EXPORT int
310           zsys_ipv6 (void);
311
312       //  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
321       //  Return network interface to use for broadcasts, or "" if none was set.
322       CZMQ_EXPORT const char *
323           zsys_interface (void);
324
325       //  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
332       //  Return IPv6 address to use for zbeacon reception, or "" if none was set.
333       CZMQ_EXPORT const char *
334           zsys_ipv6_address (void);
335
336       //  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
343       //  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
348       //  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
357       //  Return use of automatic pre-allocated FDs for zsock instances.
358       CZMQ_EXPORT int
359           zsys_auto_use_fd (void);
360
361       //  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
367       //  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
373       //  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
383       //  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
388       //  Log error condition - highest priority
389       CZMQ_EXPORT void
390           zsys_error (const char *format, ...);
391
392       //  Log warning condition - high priority
393       CZMQ_EXPORT void
394           zsys_warning (const char *format, ...);
395
396       //  Log normal, but significant, condition - normal priority
397       CZMQ_EXPORT void
398           zsys_notice (const char *format, ...);
399
400       //  Log informational message - low priority
401       CZMQ_EXPORT void
402           zsys_info (const char *format, ...);
403
404       //  Log debug-level message - lowest priority
405       CZMQ_EXPORT void
406           zsys_debug (const char *format, ...);
407
408       //  Self test of this class.
409       CZMQ_EXPORT void
410           zsys_test (bool verbose);
411
412       #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
420       //  *** 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
427       //  *** 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
436       //  *** 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
445       //  *** 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
450       //  *** 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
457       //  *** 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
462       //  *** 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
471       //  *** 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
478       //  *** 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
485       //  *** 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
494       //  *** 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
500       //  *** 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
505       //  *** Draft method, for development use, may change without warning ***
506       //  Get multicast TTL
507       CZMQ_EXPORT byte
508           zsys_mcast_ttl (void);
509
510       //  *** 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
524       //  *** 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
530       //  *** 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
544       //  *** 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
550       #endif // CZMQ_BUILD_DRAFT_API
551       Please add '@interface' section in './../src/zsys.c'.
552

DESCRIPTION

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
558       Please add @discuss section in ./../src/zsys.c.
559

EXAMPLE

561       From zsys_test method.
562
563           zsys_catch_interrupts ();
564
565           //  Check capabilities without using the return value
566           int rc = zsys_has_curve ();
567
568           const char *SELFTEST_DIR_RW = "src/selftest-rw";
569
570           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
600           //  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
610           //  Test file manipulation
611
612           // 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
618           rc = zsys_file_delete ("nosuchfile");
619           assert (rc == -1);
620
621           bool rc_bool = zsys_file_exists ("nosuchfile");
622           assert (rc_bool != true);
623
624           rc = (int) zsys_file_size ("nosuchfile");
625           assert (rc == -1);
626
627           time_t when = zsys_file_modified (".");
628           assert (when > 0);
629
630           int mode = zsys_file_mode (".");
631           assert (S_ISDIR (mode));
632           assert (mode & S_IRUSR);
633           assert (mode & S_IWUSR);
634
635           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
641           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
648           // 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
664           // 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
698           #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
727           zstr_free (&basedirpath);
728           zstr_free (&dirpath);
729           zstr_free (&relsubdir);
730
731           // 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
738           string = zsys_sprintf ("%s %02x", "Hello", 16);
739           assert (streq (string, "Hello 10"));
740           freen (string);
741
742           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
748           //  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
758           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
768               //  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
775           {
776               // zhash based printf
777               zhash_t *args = zhash_new ();
778               zhash_insert (args, "key", "value");
779               zhash_insert (args, "ham", "spam");
780
781               char *str = zsys_zprintf ("plain string", args);
782               assert (streq (str, "plain string"));
783               zstr_free (&str);
784
785               str = zsys_zprintf ("%%a%%", args);
786               assert (streq (str, "%a%"));
787               zstr_free (&str);
788
789               str = zsys_zprintf ("VALUE=%(key)s123", args);
790               assert (streq (str, "VALUE=value123"));
791               zstr_free (&str);
792
793               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
797               str = zsys_zprintf ("VALUE=%(nokey)s123, %(ham)s, %(ham)s, %%(nospam)s!!!", args);
798               assert (!str);
799
800               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
804               str = zsys_zprintf ("VALUE=%(key)s/%%S", args);
805               assert (streq (str, "VALUE=value/%S"));
806               zstr_free (&str);
807
808               zhash_destroy (&args);
809
810               //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
815               str = zsys_zplprintf ("return_code=%(zsp/return_code)s", root);
816               assert (streq (str, "return_code=0"));
817               zstr_free (&str);
818
819               zconfig_destroy (&root);
820           }
821
822

AUTHORS

824       The czmq manual was written by the authors in the AUTHORS file.
825

RESOURCES

827       Main web site:
828
829       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

NOTES

841        1. zeromq-dev@lists.zeromq.org
842           mailto:zeromq-dev@lists.zeromq.org
843
844
845
846CZMQ 4.2.1                        07/19/2023                           ZSYS(3)
Impressum