1.Dd January 24, 2024 2.Dt SQLITE3_COLLATION_NEEDED 3 3.Os 4.Sh NAME 5.Nm sqlite3_collation_needed , 6.Nm sqlite3_collation_needed16 7.Nd collation needed callbacks 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft int 11.Fo sqlite3_collation_needed 12.Fa "sqlite3*" 13.Fa "void*" 14.Fa "void(*)(void*,sqlite3*,int eTextRep,const char*)" 15.Fc 16.Ft int 17.Fo sqlite3_collation_needed16 18.Fa "sqlite3*" 19.Fa "void*" 20.Fa "void(*)(void*,sqlite3*,int eTextRep,const void*)" 21.Fc 22.Sh DESCRIPTION 23To avoid having to register all collation sequences before a database 24can be used, a single callback function may be registered with the 25database connection to be invoked whenever an undefined 26collation sequence is required. 27.Pp 28If the function is registered using the sqlite3_collation_needed() 29API, then it is passed the names of undefined collation sequences as 30strings encoded in UTF-8. 31If sqlite3_collation_needed16() is used, the names are passed as UTF-16 32in machine native byte order. 33A call to either function replaces the existing collation-needed callback. 34.Pp 35When the callback is invoked, the first argument passed is a copy of 36the second argument to sqlite3_collation_needed() or sqlite3_collation_needed16(). 37The second argument is the database connection. 38The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE, 39or SQLITE_UTF16LE, indicating the most desirable form 40of the collation sequence function required. 41The fourth parameter is the name of the required collation sequence. 42.Pp 43The callback function should register the desired collation using 44.Fn sqlite3_create_collation , 45.Fn sqlite3_create_collation16 , 46or 47.Fn sqlite3_create_collation_v2 . 48.Sh IMPLEMENTATION NOTES 49These declarations were extracted from the 50interface documentation at line 6350. 51.Bd -literal 52SQLITE_API int sqlite3_collation_needed( 53 sqlite3*, 54 void*, 55 void(*)(void*,sqlite3*,int eTextRep,const char*) 56); 57SQLITE_API int sqlite3_collation_needed16( 58 sqlite3*, 59 void*, 60 void(*)(void*,sqlite3*,int eTextRep,const void*) 61); 62.Ed 63.Sh SEE ALSO 64.Xr sqlite3 3 , 65.Xr sqlite3_create_collation 3 , 66.Xr SQLITE_UTF8 3 67