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

FreeBSD Manual Pages


home | help
JudyHS_funcs(3)		   Library Functions Manual	       JudyHS_funcs(3)

       JudyHS  functions  -  C	library	 for  creating and accessing a dynamic
       array, using an array-of-bytes of a length: Length as an	 Index	and  a
       word as a Value.

       PPvoid_t	JudyHSIns(PPvoid_t PPJHS, void *Index, Word_t Length, PJError_t	PJError);
       int	JudyHSDel(PPvoid_t PPJHS, void *Index, Word_t Length, PJError_t	PJError);
       PPvoid_t	JudyHSGet(Pcvoid_t  PJHS, void *Index, Word_t Length, PJError_t	PJError);
       Word_t	JudyHSFreeArray(PPvoid_t PPJHS,	PJError_t PJError);

       A  macro	 equivalent  exists for	each function call.  Because the macro
       forms are sometimes faster and have a simpler error handling  interface
       than  the  equivalent  functions, they are the preferred	way of calling
       the JudyHS functions.  See JudyHS(3) for	more information.   The	 func-
       tion call definitions are included here for completeness.

       One  of	the  difficulties  in  using the JudyHS	function calls lies in
       determining whether to pass a pointer or	 the  address  of  a  pointer.
       Since  the  functions that modify the JudyHS array must also modify the
       pointer to the JudyHS array, you	must pass the address of  the  pointer
       rather than the pointer itself.	This often leads to hard-to-debug pro-
       grammatic errors.  In practice, the macros allow	the compiler to	 catch
       programming  errors  when pointers instead of addresses of pointers are

       The JudyHS function calls have an  additional  parameter	 beyond	 those
       specified in the	macro calls.  This parameter is	either a pointer to an
       error structure,	or NULL	(in which case the error  information  is  not
       returned	-- only	PJERR in the return parameter).

       In  the following descriptions, the functions are described in terms of
       how the macros use them.	 This is the suggested use of the macros after
       your  program has been fully debugged.  When the	JUDYERROR_NOTEST macro
       is not specified, an error structure is declared	to store error	infor-
       mation returned from the	JudyHS functions when an error occurs.

       Notice the placement of the & in	the different functions.

	JudyHSIns(&PJHS, Index,	Length,	&JError)

		      #define JHSI(PValue, PJHS, Index)	\
			 PValue	= JudyLIns(&PJHS, Index, PJE0)

	JudyHSDel(&PJHS, Index,	Length,	&JError)

		      #define JHSD(Rc_int, PJHS, Index,	Length)	\
			 Rc_int	= JudyHSDel(&PJHS, Index, Length, PJE0)

	JudyHSGet(PJHS,	Index, Length)

		      #define JHSG(PValue, PJHS, Index,	Length)	\
			 PValue	= JudyHSIns(PJHS, Index, Length)

	JudyHSFreeArray(&PJHS, &JError)

		      #define JHSFA(Rc_word, PJHS) \
			 Rc_word = JudyHSFreeArray(&PJHS, PJE0)

       Definitions  for	 all  the Judy functions, the types Pvoid_t, Pcvoid_t,
       PPvoid_t,  Word_t  ,  JError_t,	and  PJError_t,	 the  constants	 NULL,
       JU_ERRNO_*,  JERR,  PPJERR,  and	PJE0 are provided in the Judy.h	header
       file (/usr/include/Judy.h).  Note:  Callers should define JudyHS	arrays
       as  type	 Pvoid_t,  which can be	passed by value	to functions that take
       Pcvoid_t	(constant Pvoid_t), and	also by	address	to functions that take

       The return type from most JudyHS	functions is PPvoid_t so that the val-
       ues stored in the array can be pointers to other	objects,  which	 is  a
       typical	usage,	or  cast  to  a	 Word_t	* when a pointer to a value is
       required	instead	of a pointer to	a pointer.

       JudyHS was invented and implemented by Doug Baskins after retiring from

       Judy(3),	Judy1(3), JudyL(3), JudySL(3), JudyHS(3),
       the Judy	website,, for more information and
       Application Notes.



Want to link to this manual page? Use this URL:

home | help