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

FreeBSD Manual Pages

  
 
  

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

NAME
       zfile - provides	methods	to work	with files in a	portable fashion.

SYNOPSIS
       //  If file exists, populates properties. CZMQ supports portable	symbolic
       //  links, which	are files with the extension ".ln". A symbolic link is a
       //  text	file containing	one line, the filename of a target file. Reading
       //  data	from the symbolic link actually	reads from the target file. Path
       //  may be NULL,	in which case it is not	used.
       CZMQ_EXPORT zfile_t *
	   zfile_new (const char *path,	const char *name);

       //  Destroy a file item
       CZMQ_EXPORT void
	   zfile_destroy (zfile_t **self_p);

       //  Duplicate a file item, returns a newly constructed item. If the file
       //  is null, or memory was exhausted, returns null.
       //  The caller is responsible for destroying the	return value when finished with	it.
       CZMQ_EXPORT zfile_t *
	   zfile_dup (zfile_t *self);

       //  Return file name, remove path if provided
       CZMQ_EXPORT const char *
	   zfile_filename (zfile_t *self, const	char *path);

       //  Refresh file	properties from	disk; this is not done automatically
       //  on access methods, otherwise	it is not possible to compare directory
       //  snapshots.
       CZMQ_EXPORT void
	   zfile_restat	(zfile_t *self);

       //  Return when the file	was last modified. If you want this to reflect the
       //  current situation, call zfile_restat	before checking	this property.
       CZMQ_EXPORT time_t
	   zfile_modified (zfile_t *self);

       //  Return the last-known size of the file. If you want this to reflect the
       //  current situation, call zfile_restat	before checking	this property.
       CZMQ_EXPORT off_t
	   zfile_cursize (zfile_t *self);

       //  Return true if the file is a	directory. If you want this to reflect
       //  any external	changes, call zfile_restat before checking this	property.
       CZMQ_EXPORT bool
	   zfile_is_directory (zfile_t *self);

       //  Return true if the file is a	regular	file. If you want this to reflect
       //  any external	changes, call zfile_restat before checking this	property.
       CZMQ_EXPORT bool
	   zfile_is_regular (zfile_t *self);

       //  Return true if the file is readable by this process.	If you want this to
       //  reflect any external	changes, call zfile_restat before checking this
       //  property.
       CZMQ_EXPORT bool
	   zfile_is_readable (zfile_t *self);

       //  Return true if the file is writeable	by this	process. If you	want this
       //  to reflect any external changes, call zfile_restat before checking this
       //  property.
       CZMQ_EXPORT bool
	   zfile_is_writeable (zfile_t *self);

       //  Check if file has stopped changing and can be safely	processed.
       //  Updates the file statistics from disk at every call.
       CZMQ_EXPORT bool
	   zfile_is_stable (zfile_t *self);

       //  Return true if the file was changed on disk since the zfile_t object
       //  was created,	or the last zfile_restat() call	made on	it.
       CZMQ_EXPORT bool
	   zfile_has_changed (zfile_t *self);

       //  Remove the file from	disk
       CZMQ_EXPORT void
	   zfile_remove	(zfile_t *self);

       //  Open	file for reading
       //  Returns 0 if	OK, -1 if not found or not accessible
       CZMQ_EXPORT int
	   zfile_input (zfile_t	*self);

       //  Open	file for writing, creating directory if	needed
       //  File	is created if necessary; chunks	can be written to file at any
       //  location. Returns 0 if OK, -1 if error.
       CZMQ_EXPORT int
	   zfile_output	(zfile_t *self);

       //  Read	chunk from file	at specified position. If this was the last chunk,
       //  sets	the eof	property. Returns a null chunk in case of error.
       //  The caller is responsible for destroying the	return value when finished with	it.
       CZMQ_EXPORT zchunk_t *
	   zfile_read (zfile_t *self, size_t bytes, off_t offset);

       //  Returns true	if zfile_read()	just read the last chunk in the	file.
       CZMQ_EXPORT bool
	   zfile_eof (zfile_t *self);

       //  Write chunk to file at specified position
       //  Return 0 if OK, else	-1
       CZMQ_EXPORT int
	   zfile_write (zfile_t	*self, zchunk_t	*chunk,	off_t offset);

       //  Read	next line of text from file. Returns a pointer to the text line,
       //  or NULL if there was	nothing	more to	read from the file.
       CZMQ_EXPORT const char *
	   zfile_readln	(zfile_t *self);

       //  Close file, if open
       CZMQ_EXPORT void
	   zfile_close (zfile_t	*self);

       //  Return file handle, if opened
       CZMQ_EXPORT FILE	*
	   zfile_handle	(zfile_t *self);

       //  Calculate SHA1 digest for file, using zdigest class.
       CZMQ_EXPORT const char *
	   zfile_digest	(zfile_t *self);

       //  Self	test of	this class.
       CZMQ_EXPORT void
	   zfile_test (bool verbose);
       //  These methods are deprecated, and now moved to zsys class.
       CZMQ_EXPORT bool
	   zfile_exists	(const char *filename);
       CZMQ_EXPORT ssize_t
	   zfile_size	(const char *filename);
       CZMQ_EXPORT mode_t
	   zfile_mode	(const char *filename);
       CZMQ_EXPORT int
	   zfile_delete	(const char *filename);
       CZMQ_EXPORT bool
	   zfile_stable	(const char *filename);
       CZMQ_EXPORT int
	   zfile_mkdir	(const char *pathname);
       CZMQ_EXPORT int
	   zfile_rmdir	(const char *pathname);
       CZMQ_EXPORT void
	   zfile_mode_private (void);
       CZMQ_EXPORT void
	   zfile_mode_default (void);

DESCRIPTION
       The zfile class provides	methods	to work	with disk files. A file	object
       provides	the modified date, current size, and type of the file. You can
       create a	file object for	a filename that	does not yet exist. To read or
       write data from the file, use the input and output methods, and then
       read and	write chunks. The output method	lets you both read and write
       chunks, at any offset. Finally, this class provides portable symbolic
       links. If a filename ends in ".ln", the first line of text in the file
       is read,	and used as the	underlying file	for read/write operations.
       This lets you manipulate	(e.g.) copy symbolic links without copying the
       perhaps very large files	they point to.

       This class is a new API,	deprecating the	old zfile class	(which still
       exists but is implemented in zsys now).

EXAMPLE
       From zfile_test method.

	   zfile_t *file = zfile_new (NULL, "bilbo");
	   assert (file);
	   assert (streq (zfile_filename (file,	"."), "bilbo"));
	   assert (zfile_is_readable (file) == false);
	   zfile_destroy (&file);

	   //  Create a	test file in some random subdirectory
	   file	= zfile_new ("./this/is/a/test", "bilbo");
	   assert (file);
	   int rc = zfile_output (file);
	   assert (rc == 0);
	   zchunk_t *chunk = zchunk_new	(NULL, 100);
	   assert (chunk);
	   zchunk_fill (chunk, 0, 100);

	   //  Write 100 bytes at position 1,000,000 in	the file
	   rc =	zfile_write (file, chunk, 1000000);
	   assert (rc == 0);
	   zchunk_destroy (&chunk);
	   zfile_close (file);
	   assert (zfile_is_readable (file));
	   assert (zfile_cursize (file)	== 1000100);
	   assert (!zfile_is_stable (file));
	   assert (zfile_digest	(file));

	   //  Now truncate file from outside
	   int handle =	open ("./this/is/a/test/bilbo",	O_WRONLY | O_TRUNC | O_BINARY, 0);
	   assert (handle >= 0);
	   rc =	write (handle, "Hello, World\n", 13);
	   assert (rc == 13);
	   close (handle);
	   assert (zfile_has_changed (file));
	   zclock_sleep	(1001);
	   assert (zfile_has_changed (file));

	   assert (!zfile_is_stable (file));
	   zfile_restat	(file);
	   assert (zfile_is_stable (file));
	   assert (streq (zfile_digest (file), "4AB299C8AD6ED14F31923DD94F8B5F5CB89DFB54"));

	   //  Check we	can read from file
	   rc =	zfile_input (file);
	   assert (rc == 0);
	   chunk = zfile_read (file, 1000100, 0);
	   assert (chunk);
	   assert (zchunk_size (chunk) == 13);
	   zchunk_destroy (&chunk);
	   zfile_close (file);

	   //  Check we	can read lines from file
	   rc =	zfile_input (file);
	   assert (rc == 0);
	   const char *line = zfile_readln (file);
	   assert (streq (line,	"Hello,	World"));
	   line	= zfile_readln (file);
	   assert (line	== NULL);
	   zfile_close (file);

	   //  Try some	fun with symbolic links
	   zfile_t *link = zfile_new ("./this/is/a/test", "bilbo.ln");
	   assert (link);
	   rc =	zfile_output (link);
	   assert (rc == 0);
	   fprintf (zfile_handle (link), "./this/is/a/test/bilbo\n");
	   zfile_destroy (&link);

	   link	= zfile_new ("./this/is/a/test", "bilbo.ln");
	   assert (link);
	   rc =	zfile_input (link);
	   assert (rc == 0);
	   chunk = zfile_read (link, 1000100, 0);
	   assert (chunk);
	   assert (zchunk_size (chunk) == 13);
	   zchunk_destroy (&chunk);
	   zfile_destroy (&link);

	   //  Remove file and directory
	   zdir_t *dir = zdir_new ("./this", NULL);
	   assert (dir);
	   assert (zdir_cursize	(dir) == 26);
	   zdir_remove (dir, true);
	   assert (zdir_cursize	(dir) == 0);
	   zdir_destroy	(&dir);

	   //  Check we	can no longer read from	file
	   assert (zfile_is_readable (file));
	   zfile_restat	(file);
	   assert (!zfile_is_readable (file));
	   rc =	zfile_input (file);
	   assert (rc == -1);
	   zfile_destroy (&file);

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			      ZFILE(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=zfile&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help