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 ar-
       ray, 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 de-
       termining 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 program-
       matic errors.  In practice, the macros allow the	compiler to catch pro-
       gramming	 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_ER-
       RNO_*,  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 re-
       quired 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