Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZSYS(3)				  CZMQ Manual			       ZSYS(3)

NAME
       zsys - system-level methods

SYNOPSIS
       #define UDP_FRAME_MAX   255	   //  Max size	of UDP frame

       //  Callback for	interrupt signal handler
       typedef void (zsys_handler_fn) (int signal_value);

       //  Initialize CZMQ zsys	layer; this happens automatically when you create
       //  a socket or an actor; however this call lets	you force initialization
       //  earlier, so e.g. logging is properly	set-up before you start	working.
       //  Not threadsafe, so call only	from main thread. Safe to call multiple
       //  times. Returns global CZMQ context.
       CZMQ_EXPORT void	*
	   zsys_init (void);

       //  Optionally shut down	the CZMQ zsys layer; this normally happens automatically
       //  when	the process exits; however this	call lets you force a shutdown
       //  earlier, avoiding any potential problems with atexit() ordering, especially
       //  with	Windows	dlls.
       CZMQ_EXPORT void
	   zsys_shutdown (void);

       //  Get a new ZMQ socket, automagically creating	a ZMQ context if this is
       //  the first time. Caller is responsible for destroying	the ZMQ	socket
       //  before process exits, to avoid a ZMQ	deadlock. Note:	you should not use
       //  this	method in CZMQ apps, use zsock_new() instead.
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT void	*
	   zsys_socket (int type, const	char *filename,	size_t line_nbr);

       //  Destroy/close a ZMQ socket. You should call this for	every socket you
       //  create using	zsys_socket().
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT int
	   zsys_close (void *handle, const char	*filename, size_t line_nbr);

       //  Return ZMQ socket name for socket type
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT char	*
	   zsys_sockname (int socktype);

       //  Create a pipe, which	consists of two	PAIR sockets connected over inproc.
       //  The pipe is configured to use the zsys_pipehwm setting. Returns the
       //  frontend socket successful, NULL if failed.
       CZMQ_EXPORT zsock_t *
	   zsys_create_pipe (zsock_t **backend_p);

       //  Set interrupt handler; this saves the default handlers so that a
       //  zsys_handler_reset () can restore them. If you call this multiple times
       //  then	the last handler will take affect. If handler_fn is NULL, disables
       //  default SIGINT/SIGTERM handling in CZMQ.
       CZMQ_EXPORT void
	   zsys_handler_set (zsys_handler_fn *handler_fn);

       //  Reset interrupt handler, call this at exit if needed
       CZMQ_EXPORT void
	   zsys_handler_reset (void);

       //  Set default interrupt handler, so Ctrl-C or SIGTERM will set
       //  zsys_interrupted. Idempotent; safe to call multiple times.
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT void
	   zsys_catch_interrupts (void);

       //  Return 1 if file exists, else zero
       CZMQ_EXPORT bool
	   zsys_file_exists (const char	*filename);

       //  Return size of file,	or -1 if not found
       CZMQ_EXPORT ssize_t
	   zsys_file_size (const char *filename);

       //  Return file modification time. Returns 0 if the file	does not exist.
       CZMQ_EXPORT time_t
	   zsys_file_modified (const char *filename);

       //  Return file mode; provides at least support for the POSIX S_ISREG(m)
       //  and S_ISDIR(m) macros and the S_IRUSR and S_IWUSR bits, on all boxes.
       //  Returns a mode_t cast to int, or -1 in case of error.
       CZMQ_EXPORT int
	   zsys_file_mode (const char *filename);

       //  Delete file.	Does not complain if the file is absent
       CZMQ_EXPORT int
	   zsys_file_delete (const char	*filename);

       //  Check if file is 'stable'
       CZMQ_EXPORT bool
	   zsys_file_stable (const char	*filename);

       //  Create a file path if it doesn't exist. The file path is treated as a
       //  printf format.
       CZMQ_EXPORT int
	   zsys_dir_create (const char *pathname, ...);

       //  Remove a file path if empty;	the pathname is	treated	as printf format.
       CZMQ_EXPORT int
	   zsys_dir_delete (const char *pathname, ...);

       //  Move	to a specified working directory. Returns 0 if OK, -1 if this failed.
       CZMQ_EXPORT int
	   zsys_dir_change (const char *pathname);

       //  Set private file creation mode; all files created from here will be
       //  readable/writable by	the owner only.
       CZMQ_EXPORT void
	   zsys_file_mode_private (void);

       //  Reset default file creation mode; all files created from here will use
       //  process file	mode defaults.
       CZMQ_EXPORT void
	   zsys_file_mode_default (void);

       //  Return the CZMQ version for run-time	API detection; returns version
       //  number into provided	fields,	providing reference isn't null in each case.
       CZMQ_EXPORT void
	   zsys_version	(int *major, int *minor, int *patch);

       //  Format a string using printf	formatting, returning a	freshly	allocated
       //  buffer. If there was	insufficient memory, returns NULL. Free	the returned
       //  string using	zstr_free().
       CZMQ_EXPORT char	*
	   zsys_sprintf	(const char *format, ...);

       //  Format a string with	a va_list argument, returning a	freshly	allocated
       //  buffer. If there was	insufficient memory, returns NULL. Free	the returned
       //  string using	zstr_free().
       CZMQ_EXPORT char	*
	   zsys_vprintf	(const char *format, va_list argptr);

       //  Create UDP beacon socket; if	the routable option is true, uses
       //  multicast (not yet implemented), else uses broadcast. This method
       //  and related ones might _eventually_ be moved	to a zudp class.
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT SOCKET
	   zsys_udp_new	(bool routable);

       //  Close a UDP socket
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT int
	   zsys_udp_close (SOCKET handle);

       //  Send	zframe to UDP socket, return -1	if sending failed due to
       //  interface having disappeared	(happens easily	with WiFi)
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT int
	   zsys_udp_send (SOCKET udpsock, zframe_t *frame, inaddr_t *address);

       //  Receive zframe from UDP socket, and set address of peer that	sent it
       //  The peername	must be	a char [INET_ADDRSTRLEN] array.
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT zframe_t *
	   zsys_udp_recv (SOCKET udpsock, char *peername);

       //  Handle an I/O error on some socket operation; will report and die on
       //  fatal errors, and continue silently on "try again" errors.
       //  *** This is for CZMQ	internal use only and may change arbitrarily ***
       CZMQ_EXPORT void
	   zsys_socket_error (const char *reason);

       //  Return current host name, for use in	public tcp:// endpoints. Caller	gets
       //  a freshly allocated string, should free it using zstr_free(). If the	host
       //  name	is not resolvable, returns NULL.
       CZMQ_EXPORT char	*
	   zsys_hostname (void);

       //  Move	the current process into the background. The precise effect depends
       //  on the operating system. On POSIX boxes, moves to a specified working
       //  directory (if specified), closes all	file handles, reopens stdin, stdout,
       //  and stderr to the null device, and sets the process to ignore SIGHUP. On
       //  Windows, does nothing. Returns 0 if OK, -1 if there was an error.
       CZMQ_EXPORT int
	   zsys_daemonize (const char *workdir);

       //  Drop	the process ID into the	lockfile, with exclusive lock, and switch
       //  the process to the specified	group and/or user. Any of the arguments
       //  may be null,	indicating a no-op. Returns 0 on success, -1 on	failure.
       //  Note	if you combine this with zsys_daemonize, run after, not	before
       //  that	method,	or the lockfile	will hold the wrong process ID.
       CZMQ_EXPORT int
	   zsys_run_as (const char *lockfile, const char *group, const char *user);

       //  Returns true	if the underlying libzmq supports CURVE	security.
       //  Uses	a heuristic probe according to the version of libzmq being used.
       CZMQ_EXPORT bool
	   zsys_has_curve (void);

       //  Configure the number	of I/O threads that ZeroMQ will	use. A good
       //  rule	of thumb is one	thread per gigabit of traffic in or out. The
       //  default is 1, sufficient for	most applications. If the environment
       //  variable ZSYS_IO_THREADS is defined,	that provides the default.
       //  Note	that this method is valid only before any socket is created.
       CZMQ_EXPORT void
	   zsys_set_io_threads (size_t io_threads);

       //  Configure the number	of sockets that	ZeroMQ will allow. The default
       //  is 1024. The	actual limit depends on	the system, and	you can	query it
       //  by using zsys_socket_limit (). A value of zero means	"maximum".
       //  Note	that this method is valid only before any socket is created.
       CZMQ_EXPORT void
	   zsys_set_max_sockets	(size_t	max_sockets);

       //  Return maximum number of ZeroMQ sockets that	the system will	support.
       CZMQ_EXPORT size_t
	   zsys_socket_limit (void);

       //  Configure the default linger	timeout	in msecs for new zsock instances.
       //  You can also	set this separately on each zsock_t instance. The default
       //  linger time is zero,	i.e. any pending messages will be dropped. If the
       //  environment variable	ZSYS_LINGER is defined,	that provides the default.
       //  Note	that process exit will typically be delayed by the linger time.
       CZMQ_EXPORT void
	   zsys_set_linger (size_t linger);

       //  Configure the default outgoing pipe limit (HWM) for new zsock instances.
       //  You can also	set this separately on each zsock_t instance. The default
       //  HWM is 1,000, on all	versions of ZeroMQ. If the environment variable
       //  ZSYS_SNDHWM is defined, that	provides the default. Note that	a value	of
       //  zero	means no limit,	i.e. infinite memory consumption.
       CZMQ_EXPORT void
	   zsys_set_sndhwm (size_t sndhwm);

       //  Configure the default incoming pipe limit (HWM) for new zsock instances.
       //  You can also	set this separately on each zsock_t instance. The default
       //  HWM is 1,000, on all	versions of ZeroMQ. If the environment variable
       //  ZSYS_RCVHWM is defined, that	provides the default. Note that	a value	of
       //  zero	means no limit,	i.e. infinite memory consumption.
       CZMQ_EXPORT void
	   zsys_set_rcvhwm (size_t rcvhwm);

       //  Configure the default HWM for zactor	internal pipes;	this is	set on both
       //  ends	of the pipe, for outgoing messages only	(sndhwm). The default HWM is
       //  1,000, on all versions of ZeroMQ. If	the environment	var ZSYS_ACTORHWM is
       //  defined, that provides the default. Note that a value of zero means no
       //  limit, i.e. infinite	memory consumption.
       CZMQ_EXPORT void
	   zsys_set_pipehwm (size_t pipehwm);

       //  Return the HWM for zactor internal pipes.
       CZMQ_EXPORT size_t
	   zsys_pipehwm	(void);

       //  Configure use of IPv6 for new zsock instances. By default sockets accept
       //  and make only IPv4 connections. When	you enable IPv6, sockets will accept
       //  and connect to both IPv4 and	IPv6 peers. You	can override the setting on
       //  each	zsock_t	instance. The default is IPv4 only (ipv6 set to	0). If the
       //  environment variable	ZSYS_IPV6 is defined (as 1 or 0), this provides	the
       //  default. Note: has no effect	on ZMQ v2.
       CZMQ_EXPORT void
	   zsys_set_ipv6 (int ipv6);

       //  Set network interface name to use for broadcasts, particularly zbeacon.
       //  This	lets the interface be configured for test environments where required.
       //  For example,	on Mac OS X, zbeacon cannot bind to 255.255.255.255 which is
       //  the default when there is no	specified interface. If	the environment
       //  variable ZSYS_INTERFACE is set, use that as the default interface name.
       //  Setting the interface to "*"	means "use all available interfaces".
       CZMQ_EXPORT void
	   zsys_set_interface (const char *value);

       //  Return network interface to use for broadcasts, or "" if none was set.
       CZMQ_EXPORT const char *
	   zsys_interface (void);

       //  Set log identity, which is a	string that prefixes all log messages sent
       //  by this process. The	log identity defaults to the environment variable
       //  ZSYS_LOGIDENT, if that is set.
       CZMQ_EXPORT void
	   zsys_set_logident (const char *value);

       //  Set stream to receive log traffic. By default, log traffic is sent to
       //  stdout. If you set the stream to NULL, no stream will receive the log
       //  traffic (it may still be sent to the	system facility).
       CZMQ_EXPORT void
	   zsys_set_logstream (FILE *stream);

       //  Sends log output to a PUB socket bound to the specified endpoint. To
       //  collect such	log output, create a SUB socket, subscribe to the traffic
       //  you care about, and connect to the endpoint.	Log traffic is sent as a
       //  single string frame,	in the same format as when sent	to stdout. The
       //  log system supports a single	sender;	multiple calls to this method will
       //  bind	the same sender	to multiple endpoints. To disable the sender, call
       //  this	method with a null argument.
       CZMQ_EXPORT void
	   zsys_set_logsender (const char *endpoint);

       //  Enable or disable logging to	the system facility (syslog on POSIX boxes,
       //  event log on	Windows). By default this is disabled.
       CZMQ_EXPORT void
	   zsys_set_logsystem (bool logsystem);

       //  Log error condition - highest priority
       CZMQ_EXPORT void
	   zsys_error (const char *format, ...);

       //  Log warning condition - high	priority
       CZMQ_EXPORT void
	   zsys_warning	(const char *format, ...);

       //  Log normal, but significant,	condition - normal priority
       CZMQ_EXPORT void
	   zsys_notice (const char *format, ...);

       //  Log informational message - low priority
       CZMQ_EXPORT void
	   zsys_info (const char *format, ...);

       //  Log debug-level message - lowest priority
       CZMQ_EXPORT void
	   zsys_debug (const char *format, ...);

       //  Self	test of	this class
       CZMQ_EXPORT void
	   zsys_test (bool verbose);

       //  Global signal indicator, TRUE when user presses Ctrl-C or the process
       //  gets	a SIGTERM signal.
       CZMQ_EXPORT extern volatile int zsys_interrupted;
       //  Deprecated name for this variable
       CZMQ_EXPORT extern volatile int zctx_interrupted;

DESCRIPTION
       The zsys	class provides a portable wrapper for system calls. We collect
       them here to reduce the number of weird #ifdefs in other	classes. As
       far as possible,	the bulk of CZMQ classes are fully portable.

       Please add @discuss section in ../src/zsys.c.

EXAMPLE
       From zsys_test method.

	   zsys_catch_interrupts ();

	   //  Check capabilities without using	the return value
	   int rc = zsys_has_curve ();

	   if (verbose)	{
	       char *hostname =	zsys_hostname ();
	       zsys_info ("host	name is	%s", hostname);
	       free (hostname);
	       zsys_info ("system limit	is %zu ZeroMQ sockets",	zsys_socket_limit ());
	   }
	   zsys_set_io_threads (1);
	   zsys_set_max_sockets	(0);
	   zsys_set_linger (0);
	   zsys_set_sndhwm (1000);
	   zsys_set_rcvhwm (1000);
	   zsys_set_pipehwm (2500);
	   assert (zsys_pipehwm	() == 2500);
	   zsys_set_ipv6 (0);

	   //  Test pipe creation
	   zsock_t *pipe_back;
	   zsock_t *pipe_front = zsys_create_pipe (&pipe_back);
	   zstr_send (pipe_front, "Hello");
	   char	*string	= zstr_recv (pipe_back);
	   assert (streq (string, "Hello"));
	   free	(string);
	   zsock_destroy (&pipe_back);
	   zsock_destroy (&pipe_front);

	   //  Test file manipulation
	   rc =	zsys_file_delete ("nosuchfile");
	   assert (rc == -1);

	   bool	rc_bool	= zsys_file_exists ("nosuchfile");
	   assert (rc_bool != true);

	   rc =	(int) zsys_file_size ("nosuchfile");
	   assert (rc == -1);

	   time_t when = zsys_file_modified (".");
	   assert (when	> 0);

	   int mode = zsys_file_mode (".");
	   assert (S_ISDIR (mode));
	   assert (mode	& S_IRUSR);
	   assert (mode	& S_IWUSR);

	   zsys_file_mode_private ();
	   rc =	zsys_dir_create	("%s/%s", ".", ".testsys/subdir");
	   assert (rc == 0);
	   when	= zsys_file_modified ("./.testsys/subdir");
	   assert (when	> 0);
	   assert (!zsys_file_stable ("./.testsys/subdir"));
	   rc =	zsys_dir_delete	("%s/%s", ".", ".testsys/subdir");
	   assert (rc == 0);
	   rc =	zsys_dir_delete	("%s/%s", ".", ".testsys");
	   assert (rc == 0);
	   zsys_file_mode_default ();
	   assert (zsys_dir_change (".") == 0);

	   int major, minor, patch;
	   zsys_version	(&major, &minor, &patch);
	   assert (major == CZMQ_VERSION_MAJOR);
	   assert (minor == CZMQ_VERSION_MINOR);
	   assert (patch == CZMQ_VERSION_PATCH);

	   string = zsys_sprintf ("%s %02x", "Hello", 16);
	   assert (streq (string, "Hello 10"));
	   free	(string);

	   char	*str64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890,.";
	   int num10 = 1234567890;
	   string = zsys_sprintf ("%s%s%s%s%d",	str64, str64, str64, str64, num10);
	   assert (strlen (string) == (4 * 64 +	10));
	   free	(string);

	   //  Test logging system
	   zsys_set_logident ("czmq_selftest");
	   zsys_set_logsender ("inproc://logging");
	   void	*logger	= zsys_socket (ZMQ_SUB,	NULL, 0);
	   assert (logger);
	   rc =	zmq_connect (logger, "inproc://logging");
	   assert (rc == 0);
	   rc =	zmq_setsockopt (logger,	ZMQ_SUBSCRIBE, "", 0);
	   assert (rc == 0);

	   if (verbose)	{
	       zsys_error ("This is an %s message", "error");
	       zsys_warning ("This is a	%s message", "warning");
	       zsys_notice ("This is a %s message", "notice");
	       zsys_info ("This	is a %s	message", "info");
	       zsys_debug ("This is a %s message", "debug");
	       zsys_set_logident ("hello, world");
	       zsys_info ("This	is a %s	message", "info");
	       zsys_debug ("This is a %s message", "debug");

	       //  Check that logsender	functionality is working
	       char *received =	zstr_recv (logger);
	       assert (received);
	       zstr_free (&received);
	   }
	   zsys_close (logger, NULL, 0);

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

RESOURCES
       Main web	site:

       Report bugs to the email	<zeromq-dev@lists.zeromq.org[1]>

COPYRIGHT
       Copyright (c) 1991-2012 iMatix Corporation -- http://www.imatix.com
       Copyright other contributors as noted in	the AUTHORS file. This file is
       part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org
       This Source Code	Form is	subject	to the terms of	the Mozilla Public
       License,	v. 2.0.	If a copy of the MPL was not distributed with this
       file, You can obtain one	at http://mozilla.org/MPL/2.0/.	LICENSE
       included	with the czmq distribution.

NOTES
	1. zeromq-dev@lists.zeromq.org
	   mailto:zeromq-dev@lists.zeromq.org

CZMQ 3.0.1			  06/01/2015			       ZSYS(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHORS | RESOURCES | COPYRIGHT | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zsys&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help