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_VERSION
38       #define                                           PSL_VERSION_MAJOR
39       #define                                           PSL_VERSION_MINOR
40       #define                                           PSL_VERSION_NUMBER
41       #define                                           PSL_VERSION_PATCH
42       #define                                           PSL_TYPE_ICANN
43       #define                                           PSL_TYPE_PRIVATE
44       #define                                           PSL_TYPE_NO_STAR_RULE
45       #define                                           PSL_TYPE_ANY
46       enum                                              psl_error_t
47       typedef                                           psl_ctx_t
48
49

INCLUDES

51           #include <libpsl.h>
52

DESCRIPTION

54       Public Suffix List[1] library functions.
55

FUNCTIONS

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

TYPES AND VALUES

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

NOTES

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