1LIBPSL(3)                       LIBPSL Library                       LIBPSL(3)
2
3
4

NAME

6       libpsl - Public Suffix List library functions
7

STABILITY LEVEL

9       Stable, unless otherwise indicated
10

FUNCTIONS

12       psl_ctx_t *                          psl_load_file ()
13       psl_ctx_t *                          psl_load_fp ()
14       psl_ctx_t *                          psl_latest ()
15       const psl_ctx_t *                    psl_builtin ()
16       void                                 psl_free ()
17       int                                  psl_is_public_suffix ()
18       int                                  psl_is_public_suffix2 ()
19       const char *                         psl_unregistrable_domain ()
20       const char *                         psl_registrable_domain ()
21       int                                  psl_suffix_count ()
22       int                                  psl_suffix_exception_count ()
23       int                                  psl_suffix_wildcard_count ()
24       time_t                               psl_builtin_file_time ()
25       const char *                         psl_builtin_sha1sum ()
26       const char *                         psl_builtin_filename ()
27       int                                  psl_builtin_outdated ()
28       int                                  psl_is_cookie_domain_acceptable ()
29       const char *                         psl_dist_filename ()
30       const char *                         psl_get_version ()
31       int                                  psl_check_version_number ()
32       psl_error_t                          psl_str_to_utf8lower ()
33       void                                 psl_free_string ()
34
35

TYPES AND VALUES

37       #define                                           PSL_API
38       #define                                           PSL_VERSION
39       #define                                           PSL_VERSION_MAJOR
40       #define                                           PSL_VERSION_MINOR
41       #define                                           PSL_VERSION_NUMBER
42       #define                                           PSL_VERSION_PATCH
43       #define                                           PSL_TYPE_ICANN
44       #define                                           PSL_TYPE_PRIVATE
45       #define                                           PSL_TYPE_NO_STAR_RULE
46       #define                                           PSL_TYPE_ANY
47       enum                                              psl_error_t
48       typedef                                           psl_ctx_t
49
50

INCLUDES

52           #include <libpsl.h>
53

DESCRIPTION

55       Public Suffix List[1] library functions.
56

FUNCTIONS

58   psl_load_file ()
59           psl_ctx_t *
60           psl_load_file (const char *fname);
61
62       This function loads the public suffixes file named fname . To free the
63       allocated resources, call psl_free().
64
65       The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
66       they are international.
67
68       Parameters
69                      fname                          Name of
70                                                     PSL file
71
72
73       Returns
74           Pointer to a PSL context or NULL on failure.
75
76       Since: 0.1
77
78   psl_load_fp ()
79           psl_ctx_t *
80           psl_load_fp (FILE *fp);
81
82       This function loads the public suffixes from a FILE pointer. To free
83       the allocated resources, call psl_free().
84
85       The suffixes are expected to be UTF-8 encoded (lowercase + NFKC) if
86       they are international.
87
88       Parameters
89                      fp                            FILE
90                                                    pointer
91
92
93       Returns
94           Pointer to a PSL context or NULL on failure.
95
96       Since: 0.1
97
98   psl_latest ()
99           psl_ctx_t *
100           psl_latest (const char *fname);
101
102       This function loads the the latest available PSL data from either
103
104fname (application specific filename, may be NULL)
105
106       •   location specified during built-time (filename from ./configure
107           --with-psl-distfile)
108
109       •   built-in PSL data (generated from ./configure --with-psl-file)
110
111       •   location of built-in data (filename from ./configure
112           --with-psl-file)
113
114       If none of the above is available, the function returns NULL.
115
116       To free the allocated resources, call psl_free().
117
118       Parameters
119                      fname                          Name of
120                                                     PSL file
121                                                     or NULL
122
123
124       Returns
125           Pointer to a PSL context or NULL on failure.
126
127       Since: 0.16
128
129   psl_builtin ()
130           const psl_ctx_t *
131           psl_builtin (void);
132
133       This function returns the PSL context that has been generated and built
134       in at compile-time. You don't have to free the returned context
135       explicitly.
136
137       The builtin data also contains punycode entries, one for each
138       international domain name.
139
140       If the generation of built-in data has been disabled during
141       compilation, NULL will be returned. When using the builtin psl context,
142       you can provide UTF-8 (lowercase + NFKC) or ASCII/ACE (punycode)
143       representations of domains to functions like psl_is_public_suffix().
144
145       Returns
146           Pointer to the built in PSL data or NULL if this data is not
147           available.
148
149       Since: 0.1
150
151   psl_free ()
152           void
153           psl_free (psl_ctx_t *psl);
154
155       This function frees the the PSL context that has been retrieved via
156       psl_load_fp() or psl_load_file().
157
158       Parameters
159                      psl                            PSL
160                                                     context
161                                                     pointer
162
163
164       Since: 0.1
165
166   psl_is_public_suffix ()
167           int
168           psl_is_public_suffix (const psl_ctx_t *psl,
169                                 const char *domain);
170
171       This function checks if domain is a public suffix by the means of the
172       Mozilla Public Suffix List[2].
173
174       For cookie domain checking see psl_is_cookie_domain_acceptable().
175
176       International domain names have to be either in UTF-8 (lowercase +
177       NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
178       in incorrect return values. Use helper function psl_str_to_utf8lower()
179       for normalization domain .
180
181       psl is a context returned by either psl_load_file(), psl_load_fp() or
182       psl_builtin().
183
184       Parameters
185                      psl                             PSL
186                                                      context
187
188                      domain                          Domain
189                                                      string
190
191
192       Returns
193           1 if domain is a public suffix, 0 if not.
194
195       Since: 0.1
196
197   psl_is_public_suffix2 ()
198           int
199           psl_is_public_suffix2 (const psl_ctx_t *psl,
200                                  const char *domain,
201                                  int type);
202
203       This function checks if domain is a public suffix by the means of the
204       Mozilla Public Suffix List[2].
205
206       type specifies the PSL section where to perform the lookup. Valid
207       values are PSL_TYPE_PRIVATE, PSL_TYPE_ICANN, PSL_TYPE_NO_STAR_RULE, and
208       PSL_TYPE_ANY.
209
210       PSL_TYPE_NO_STAR_RULE switches of the 'prevailing star rule' (see
211       List[3] under 'Algorithm' 2.). Applying the flag means that TLDs not
212       explicitly listed in the PSL are *not* treated as public suffixes.
213
214       International domain names have to be either in UTF-8 (lowercase +
215       NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
216       in incorrect return values. Use helper function psl_str_to_utf8lower()
217       for normalization domain .
218
219       psl is a context returned by either psl_load_file(), psl_load_fp() or
220       psl_builtin().
221
222       Parameters
223                      psl                             PSL
224                                                      context
225
226                      domain                          Domain
227                                                      string
228
229                      type                            Domain
230                                                      type
231
232
233       Returns
234           1 if domain is a public suffix, 0 if not.
235
236       Since: 0.1
237
238   psl_unregistrable_domain ()
239           const char *
240           psl_unregistrable_domain (const psl_ctx_t *psl,
241                                     const char *domain);
242
243       This function finds the longest public suffix part of domain by the
244       means of the Mozilla Public Suffix List[2].
245
246       International domain names have to be either in UTF-8 (lowercase +
247       NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
248       in incorrect return values. Use helper function psl_str_to_utf8lower()
249       for normalization domain .
250
251       psl is a context returned by either psl_load_file(), psl_load_fp() or
252       psl_builtin().
253
254       Parameters
255                      psl                             PSL
256                                                      context
257
258                      domain                          Domain
259                                                      string
260
261
262       Returns
263           Pointer to longest public suffix part of domain or NULL if domain
264           does not contain a public suffix (or if psl is NULL).
265
266       Since: 0.1
267
268   psl_registrable_domain ()
269           const char *
270           psl_registrable_domain (const psl_ctx_t *psl,
271                                   const char *domain);
272
273       This function finds the shortest private suffix part of domain by the
274       means of the Mozilla Public Suffix List[2].
275
276       International domain names have to be either in UTF-8 (lowercase +
277       NFKC) or in ASCII/ACE format (punycode). Other encodings likely result
278       in incorrect return values. Use helper function psl_str_to_utf8lower()
279       for normalization domain .
280
281       psl is a context returned by either psl_load_file(), psl_load_fp() or
282       psl_builtin().
283
284       Parameters
285                      psl                             PSL
286                                                      context
287
288                      domain                          Domain
289                                                      string
290
291
292       Returns
293           Pointer to shortest private suffix part of domain or NULL if domain
294           does not contain a private suffix (or if psl is NULL).
295
296       Since: 0.1
297
298   psl_suffix_count ()
299           int
300           psl_suffix_count (const psl_ctx_t *psl);
301
302       This function returns number of public suffixes maintained by psl . The
303       number of exceptions within the Public Suffix List are not included.
304
305       If the information is not available, the return value is -1 (since
306       0.19). This is the case with DAFSA blobs or if psl is NULL.
307
308       Parameters
309                      psl                            PSL
310                                                     context
311                                                     pointer
312
313
314       Returns
315           Number of public suffixes entries in PSL context or -1 if this
316           information is not available.
317
318       Since: 0.1
319
320   psl_suffix_exception_count ()
321           int
322           psl_suffix_exception_count (const psl_ctx_t *psl);
323
324       This function returns number of public suffix exceptions maintained by
325       psl .
326
327       If the information is not available, the return value is -1 (since
328       0.19). This is the case with DAFSA blobs or if psl is NULL.
329
330       Parameters
331                      psl                            PSL
332                                                     context
333                                                     pointer
334
335
336       Returns
337           Number of public suffix exceptions in PSL context or -1 if this
338           information is not available.
339
340       Since: 0.1
341
342   psl_suffix_wildcard_count ()
343           int
344           psl_suffix_wildcard_count (const psl_ctx_t *psl);
345
346       This function returns number of public suffix wildcards maintained by
347       psl .
348
349       If the information is not available, the return value is -1 (since
350       0.19). This is the case with DAFSA blobs or if psl is NULL.
351
352       Parameters
353                      psl                            PSL
354                                                     context
355                                                     pointer
356
357
358       Returns
359           Number of public suffix wildcards in PSL context or -1 if this
360           information is not available.
361
362       Since: 0.10.0
363
364   psl_builtin_file_time ()
365           time_t
366           psl_builtin_file_time (void);
367
368       This function returns the mtime of the Public Suffix List file that has
369       been built in.
370
371       If the generation of built-in data has been disabled during
372       compilation, 0 will be returned.
373
374       Returns
375           time_t value or 0.
376
377       Since: 0.1
378
379   psl_builtin_sha1sum ()
380           const char *
381           psl_builtin_sha1sum (void);
382
383       This function returns the SHA1 checksum of the Public Suffix List file
384       that has been built in. The returned string is in lowercase hex
385       encoding, e.g. "2af1e9e3044eda0678bb05949d7cca2f769901d8".
386
387       If the generation of built-in data has been disabled during
388       compilation, an empty string will be returned.
389
390       Returns
391           String containing SHA1 checksum or an empty string.
392
393       Since: 0.1
394
395   psl_builtin_filename ()
396           const char *
397           psl_builtin_filename (void);
398
399       This function returns the file name of the Public Suffix List file that
400       has been built in.
401
402       If the generation of built-in data has been disabled during
403       compilation, an empty string will be returned.
404
405       Returns
406           String containing the PSL file name or an empty string.
407
408       Since: 0.1
409
410   psl_builtin_outdated ()
411           int
412           psl_builtin_outdated (void);
413
414       This function checks if the built-in data is older than the file it has
415       been created from. If it is, it might be a good idea for the
416       application to reload the PSL. The mtime is taken as reference.
417
418       If the PSL file does not exist, it is assumed that the built-in data is
419       not outdated.
420
421       Returns
422           1 if the built-in is outdated, 0 otherwise.
423
424       Since: 0.10.0
425
426   psl_is_cookie_domain_acceptable ()
427           int
428           psl_is_cookie_domain_acceptable (const psl_ctx_t *psl,
429                                            const char *hostname,
430                                            const char *cookie_domain);
431
432       This helper function checks whether cookie_domain is an acceptable
433       cookie domain value for the request hostname .
434
435       For international domain names both, hostname and cookie_domain , have
436       to be either in UTF-8 (lowercase + NFKC) or in ASCII/ACE (punycode)
437       format. Other encodings or mixing UTF-8 and punycode likely result in
438       incorrect return values.
439
440       Use helper function psl_str_to_utf8lower() for normalization of
441       hostname and cookie_domain .
442
443       Examples:
444
445        1. Cookie domain 'example.com' would be acceptable for hostname
446           'www.example.com', but '.com' or 'com' would NOT be acceptable
447           since 'com' is a public suffix.
448
449        2. Cookie domain 'his.name' would be acceptable for hostname
450           'remember.his.name', but NOT for 'forgot.his.name' since
451           'forgot.his.name' is a public suffix.
452
453       Parameters
454                      psl                                PSL
455                                                         context
456                                                         pointer
457
458                      hostname                           The
459                                                         request
460                                                         hostname.
461
462                      cookie_domain                      The
463                                                         domain
464                                                         value
465                                                         from a
466                                                         cookie
467
468
469       Returns
470           1 if acceptable, 0 if not acceptable.
471
472       Since: 0.1
473
474   psl_dist_filename ()
475           const char *
476           psl_dist_filename (void);
477
478       This function returns the file name of the distribution/system PSL data
479       file. This file will be considered by psl_latest().
480
481       Return the filename that is set by ./configure --with-psl-distfile, or
482       an empty string.
483
484       Returns
485           String containing a PSL file name or an empty string.
486
487       Since: 0.16
488
489   psl_get_version ()
490           const char *
491           psl_get_version (void);
492
493       Get libpsl version.
494
495       Returns
496           String containing version of libpsl.
497
498       Since: 0.2.5
499
500   psl_check_version_number ()
501           int
502           psl_check_version_number (int version);
503
504       Check the given version number is at minimum the current library
505       version number. The version number must be a hexadecimal number like
506       0x000a01 (V0.10.1).
507
508       Parameters
509                      version                         Version
510                                                      number
511                                                      (hex) to
512                                                      check
513                                                      against.
514
515
516       Returns
517           Returns the library version number if the given version number is
518           at least the version of the library, else return 0; If the argument
519           is 0, the function returns the library version number without
520           performing a check.
521
522       Since: 0.11.0
523
524   psl_str_to_utf8lower ()
525           psl_error_t
526           psl_str_to_utf8lower (const char *str,
527                                 const char *encoding,
528                                 const char *locale,
529                                 char **lower);
530
531       This helper function converts a string to UTF-8 lowercase + NFKC
532       representation. Lowercase + NFKC UTF-8 is needed as input to the domain
533       checking functions.
534
535       lower stays unchanged on error.
536
537       When returning PSL_SUCCESS, the return value 'lower' must be freed
538       after usage.
539
540       Parameters
541                      str                            string
542                                                     to
543                                                     convert
544
545                      encoding                       charset
546                                                     encoding
547                                                     of str ,
548                                                     e.g.
549                                                     'iso-8859-1'
550                                                     or NULL
551
552                      locale                         locale of
553                                                     str for to
554                                                     lowercase
555                                                     conversion,
556                                                     e.g. 'de' or
557                                                     NULL
558
559                      lower                          return value
560                                                     containing
561                                                     the
562                                                     converted
563                                                     string
564
565
566       Returns
567           psl_error_t value. PSL_SUCCESS: Success PSL_ERR_INVALID_ARG: str is
568           a NULL value. PSL_ERR_CONVERTER: Failed to open the unicode
569           converter with name encoding PSL_ERR_TO_UTF16: Failed to convert
570           str to unicode PSL_ERR_TO_LOWER: Failed to convert unicode to
571           lowercase PSL_ERR_TO_UTF8: Failed to convert unicode to UTF-8
572           PSL_ERR_NO_MEM: Failed to allocate memory
573
574       Since: 0.4
575
576   psl_free_string ()
577           void
578           psl_free_string (char *str);
579
580       This function free()'s the memory allocated by psl_str_to_utf8lower()
581       when returning a lowercase string
582
583       Parameters
584                      str                    pointer
585                                             to
586                                             lowercase
587                                             string
588                                             returned
589                                             by
590                                             psl_str_to_utf8lower()
591
592
593       Since: 0.19
594

TYPES AND VALUES

596   PSL_API
597           #  define PSL_API __attribute__ ((__visibility__("default")))
598
599   PSL_VERSION
600           #define PSL_VERSION "0.21.1"
601
602   PSL_VERSION_MAJOR
603           #define PSL_VERSION_MAJOR 0
604
605   PSL_VERSION_MINOR
606           #define PSL_VERSION_MINOR 21
607
608   PSL_VERSION_NUMBER
609           #define PSL_VERSION_NUMBER 0x001501
610
611   PSL_VERSION_PATCH
612           #define PSL_VERSION_PATCH 1
613
614   PSL_TYPE_ICANN
615           #define PSL_TYPE_ICANN        (1<<0)
616
617   PSL_TYPE_PRIVATE
618           #define PSL_TYPE_PRIVATE      (1<<1)
619
620   PSL_TYPE_NO_STAR_RULE
621           #define PSL_TYPE_NO_STAR_RULE (1<<2)
622
623   PSL_TYPE_ANY
624           #define PSL_TYPE_ANY          (PSL_TYPE_ICANN | PSL_TYPE_PRIVATE)
625
626   enum psl_error_t
627       Return codes for PSL functions. Negative return codes mean failure.
628       Positive values are reserved for non-error return codes.
629
630       Members
631                      PSL_SUCCESS                          Successful
632                                                           return.
633
634                      PSL_ERR_INVALID_ARG                  Invalid
635                                                           argument.
636
637                      PSL_ERR_CONVERTER                    Failed to
638                                                           open
639                                                           libicu
640                                                           utf-16
641                                                           converter.
642
643                      PSL_ERR_TO_UTF16                     Failed to
644                                                           convert to
645                                                           utf-16.
646
647                      PSL_ERR_TO_LOWER                     Failed to
648                                                           convert
649                                                           utf-16 to
650                                                           lowercase.
651
652                      PSL_ERR_TO_UTF8                      Failed to
653                                                           convert
654                                                           utf-16 to
655                                                           utf-8.
656
657                      PSL_ERR_NO_MEM                       Failed to
658                                                           allocate
659                                                           memory.
660
661
662   psl_ctx_t
663           typedef struct psl_ctx_st psl_ctx_t;
664

NOTES

666        1. Public Suffix List
667           https://publicsuffix.org/
668
669        2. Mozilla Public Suffix List
670           https://publicsuffix.org
671
672        3. List
673           https://publicsuffix.org/list
674
675
676
677LIBPSL Library                    07/21/2022                         LIBPSL(3)
Impressum