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

FreeBSD Manual Pages

  
 
  

home | help
LIBPMEMLOG(7)		   PMDK	Programmer's Manual		 LIBPMEMLOG(7)

NAME
       libpmemlog - persistent memory resident log file

SYNOPSIS
	      #include <libpmemlog.h>
	      cc ... -lpmemlog -lpmem

   Library API versioning:
	      const char *pmemlog_check_version(
		  unsigned major_required,
		  unsigned minor_required);

   Managing library behavior:
	      void pmemlog_set_funcs(
		  void *(*malloc_func)(size_t size),
		  void (*free_func)(void *ptr),
		  void *(*realloc_func)(void *ptr, size_t size),
		  char *(*strdup_func)(const char *s));

   Error handling:
	      int pmemlog_check(const char *path);

   Other library functions:
       A description of	other libpmemlog functions can be found	on the follow-
       ing manual pages:

       pmemlog_append(3),   pmemlog_create(3),	 pmemlog_ctl_exec(3),	 pmem-
       log_ctl_get(3), pmemlog_ctl_set(3), pmemlog_nbyte(3), pmemlog_tell(3)

DESCRIPTION
       libpmemlog  provides  a	log file in persistent memory (pmem) such that
       additions to the	log are	appended atomically.  This library is intended
       for  applications  using	 direct	access storage (DAX), which is storage
       that supports load/store	access without	paging	blocks	from  a	 block
       storage device.	Some types of non-volatile memory DIMMs	(NVDIMMs) pro-
       vide this type of byte addressable access  to  storage.	 A  persistent
       memory  aware file system is typically used to expose the direct	access
       to applications.	 Memory	mapping	a file from this type of  file	system
       results in the load/store, non-paged access to pmem.  libpmemlog	builds
       on thistype of memory mapped file.

       This library is for applications	that need a persistent log file	updat-
       ed  atomically (the updates cannot be torn by program interruption such
       as power	failures).  This library builds	on the low-level pmem  support
       provided	 by  libpmem(7), handling the transactional update of the log,
       flushing	to persistence,	and recovery for the application.

       libpmemlog is one of a collection of persistent memory libraries	avail-
       able.  The others are:

       o libpmemobj(7),	 a general use persistent memory API, providing	memory
	 allocation and	transactional operations on variable-sized objects.

       o libpmemblk(7),	providing pmem-resident	arrays of  fixed-sized	blocks
	 with atomic updates.

       o libpmem(7), low-level persistent memory support.

       Under  normal usage, libpmemlog will never print	messages or intention-
       ally cause the process to exit.	The only exception to this is the  de-
       bugging information, when enabled, as described under DEBUGGING AND ER-
       ROR HANDLING below.

       To use the pmem-resident	log file provided by libpmemlog, a memory pool
       is  first  created.   This is done with the pmemlog_create(3) function.
       The other functions mentioned above in SYNOPSIS section then operate on
       the resulting log memory	pool.

       Once  created,  the  memory pool	is represented by an opaque handle, of
       type PMEMlogpool*, which	is passed to most of the other functions  from
       libpmemlog.   Internally, libpmemlog will use either pmem_persist(3) or
       msync(2)	when it	needs to flush changes,	depending on whether the memo-
       ry  pool	 appears  to  be  persistent memory or a regular file (see the
       pmem_is_pmem(3) function	in libpmem(7) for more information).  There is
       no  need	 for applications to flush changes directly when using the log
       memory API provided by libpmemlog.

CAVEATS
       libpmemlog relies on the	library	destructor being called	from the  main
       thread.	 For this reason, all functions	that might trigger destruction
       (e.g.  dlclose(3)) should be called in the main thread.	Otherwise some
       of  the	resources  associated with that	thread might not be cleaned up
       properly.

LIBRARY	API VERSIONING
       This section describes how the library API is versioned,	 allowing  ap-
       plications to work with an evolving API.

       The  pmemlog_check_version()  function is used to determine whether the
       installed libpmemlog supports the version of the	library	 API  required
       by  an  application.  The easiest way to	do this	is for the application
       to supply the compile-time version information provided by  defines  in
       <libpmemlog.h>, like this:

	      reason = pmemlog_check_version(PMEMLOG_MAJOR_VERSION,
					     PMEMLOG_MINOR_VERSION);
	      if (reason != NULL) {
		  /* version check failed, reason string tells you why */
	      }

       Any mismatch in the major version number	is considered a	failure, but a
       library with a newer minor version number will pass  this  check	 since
       increasing minor	versions imply backwards compatibility.

       An  application can also	check specifically for the existence of	an in-
       terface by checking for the version where  that	interface  was	intro-
       duced.	These versions are documented in this man page as follows: un-
       less otherwise specified, all interfaces	described here	are  available
       in version 1.0 of the library.  Interfaces added	after version 1.0 will
       contain the text	introduced in version x.y in the section of this manu-
       al describing the feature.

       On  success,  pmemlog_check_version() returns NULL.  Otherwise, the re-
       turn value is a static string describing	the reason the	version	 check
       failed.	 The  string  returned	by pmemlog_check_version() must	not be
       modified	or freed.

MANAGING LIBRARY BEHAVIOR
       The pmemlog_set_funcs() function	allows an application to override mem-
       ory  allocation	calls  used internally by libpmemlog.  Passing in NULL
       for any of the handlers will cause the libpmemlog default  function  to
       be  used.   The	library	 does  not make	heavy use of the system	malloc
       functions, but it does allocate approximately 4-8  kilobytes  for  each
       memory pool in use.

DEBUGGING AND ERROR HANDLING
       The  pmemlog_errormsg()	function  returns a pointer to a static	buffer
       containing the last error message logged	for the	 current  thread.   If
       errno  was set, the error message may include a description of the cor-
       responding error	code as	returned by strerror(3).   The	error  message
       buffer  is thread-local;	errors encountered in one thread do not	affect
       its value in other threads.  The	buffer is never	cleared	by any library
       function;  its content is significant only when the return value	of the
       immediately preceding call to a libpmemlog function indicated an	error,
       or if errno was set.  The application must not modify or	free the error
       message string, but it may be modified by subsequent calls to other li-
       brary functions.

       Two  versions  of  libpmemlog  are typically available on a development
       system.	The normal version, accessed when a program  is	 linked	 using
       the -lpmemlog option, is	optimized for performance.  That version skips
       checks that impact performance and never	logs any trace information  or
       performs	any run-time assertions.

       A  second  version  of libpmemlog, accessed when	a program uses the li-
       braries under /usr/lib/pmdk_debug,  contains  run-time  assertions  and
       trace  points.	The  typical way to access the debug version is	to set
       the environment	variable  LD_LIBRARY_PATH  to  /usr/lib/pmdk_debug  or
       /usr/lib64/pmdk_debug,  as appropriate.	Debugging output is controlled
       using the following environment variables.  These variables have	no ef-
       fect on the non-debug version of	the library.

       o PMEMLOG_LOG_LEVEL

       The  value  of PMEMLOG_LOG_LEVEL	enables	trace points in	the debug ver-
       sion of the library, as follows:

       o 0 - This is the default level when PMEMLOG_LOG_LEVEL is not set.   No
	 log messages are emitted at this level.

       o 1 - Additional	details	on any errors detected are logged, in addition
	 to returning the errno-based errors as	usual.	The  same  information
	 may be	retrieved using	pmemlog_errormsg().

       o 2 - A trace of	basic operations is logged.

       o 3 - Enables a very verbose amount of function call tracing in the li-
	 brary.

       o 4 - Enables voluminous	and fairly obscure tracing information that is
	 likely	only useful to the libpmemlog developers.

       Unless PMEMLOG_LOG_FILE is set, debugging output	is written to stderr.

       o PMEMLOG_LOG_FILE

       Specifies  the name of a	file name where	all logging information	should
       be written.  If the last	character in the name is "-", the PID  of  the
       current	process	will be	appended to the	file name when the log file is
       created.	 If PMEMLOG_LOG_FILE is	not set, logging output	is written  to
       stderr.

       See  also  libpmem(7) for information about other environment variables
       affecting libpmemlog behavior.

EXAMPLE
       The following example illustrates how the libpmemlog API	is used.

	      #include <stdio.h>
	      #include <fcntl.h>
	      #include <errno.h>
	      #include <stdlib.h>
	      #include <unistd.h>
	      #include <string.h>
	      #include <libpmemlog.h>

	      /* size of the pmemlog pool -- 1 GB */
	      #define POOL_SIZE	((size_t)(1 << 30))

	      /*
	       * printit -- log	processing callback for	use with pmemlog_walk()
	       */
	      int
	      printit(const void *buf, size_t len, void	*arg)
	      {
		  fwrite(buf, len, 1, stdout);
		  return 0;
	      }

	      int
	      main(int argc, char *argv[])
	      {
		  const	char path[] = "/pmem-fs/myfile";
		  PMEMlogpool *plp;
		  size_t nbyte;
		  char *str;

		  /* create the	pmemlog	pool or	open it	if it already exists */
		  plp =	pmemlog_create(path, POOL_SIZE,	0666);

		  if (plp == NULL)
		      plp = pmemlog_open(path);

		  if (plp == NULL) {
		      perror(path);
		      exit(1);
		  }

		  /* how many bytes does the log hold? */
		  nbyte	= pmemlog_nbyte(plp);
		  printf("log holds %zu	bytes",	nbyte);

		  /* append to the log... */
		  str =	"This is the first string appended";
		  if (pmemlog_append(plp, str, strlen(str)) < 0) {
		      perror("pmemlog_append");
		      exit(1);
		  }
		  str =	"This is the second string appended";
		  if (pmemlog_append(plp, str, strlen(str)) < 0) {
		      perror("pmemlog_append");
		      exit(1);
		  }

		  /* print the log contents */
		  printf("log contains:");
		  pmemlog_walk(plp, 0, printit,	NULL);

		  pmemlog_close(plp);
	      }

       See <http://pmem.io/pmdk/libpmemlog> for	more examples using the	 libp-
       memlog API.

BUGS
       Unlike  libpmemobj(7), data replication is not supported	in libpmemlog.
       Thus, specifying	replica	sections in pool set files is not allowed.

ACKNOWLEDGEMENTS
       libpmemlog builds on the	persistent memory programming model recommend-
       ed    by	   the	  SNIA	 NVM   Programming   Technical	 Work	Group:
       <http://snia.org/nvmp>

SEE ALSO
       msync(2),  pmemlog_append(3),  pmemlog_create(3),  pmemlog_ctl_exec(3),
       pmemlog_ctl_get(3),    pmemlog_ctl_set(3),    pmemlog_nbyte(3),	 pmem-
       log_tell(3), strerror(3), libpmem(7), libpmemblk(7), libpmemobj(7)  and
       <http://pmem.io>

PMDK - pmemlog API version 1.1	  2019-07-10			 LIBPMEMLOG(7)

NAME | SYNOPSIS | DESCRIPTION | CAVEATS | LIBRARY API VERSIONING | MANAGING LIBRARY BEHAVIOR | DEBUGGING AND ERROR HANDLING | EXAMPLE | BUGS | ACKNOWLEDGEMENTS | SEE ALSO

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

home | help