1 /* 2 Copyright (C) 2015-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4fs.ctr 12 */ 13 14 #ifndef DK4FS_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4FS_H_INCLUDED 1 17 18 19 /** @file 20 File search for configuration and data files. 21 Specify short file name and a number of directories: 22 - shared data directory (i.e. /usr/share) or system 23 configuration directory (i.e. /etc), 24 - users home directory, 25 - program name, 26 - program group name, 27 - language, 28 - region 29 30 Use dk4fs_config_one() or dk4fs_data_one() multiple times to 31 find the file best matching 32 program name, group name, language and region. See below. 33 34 CRT on Windows: Optional. 35 */ 36 37 #ifndef DK4CONF_H_INCLUDED 38 #if DK4_BUILDING_DKTOOLS4 39 #include "dk4conf.h" 40 #else 41 #include <dktools-4/dk4conf.h> 42 #endif 43 #endif 44 45 #ifndef DK4TYPES_H_INCLUDED 46 #if DK4_BUILDING_DKTOOLS4 47 #include <libdk4base/dk4types.h> 48 #else 49 #include <dktools-4/dk4types.h> 50 #endif 51 #endif 52 53 #ifndef DK4ERROR_H_INCLUDED 54 #if DK4_BUILDING_DKTOOLS4 55 #include <libdk4base/dk4error.h> 56 #else 57 #include <dktools-4/dk4error.h> 58 #endif 59 #endif 60 61 62 63 /** Pass numbers for configuration file search. 64 65 The group name passed as name_group is used instead of group, 66 the program name passed as name_prog is used instead of prog. 67 */ 68 enum { 69 DK4_FS_CONF_SHARE_LIB = 0, /**< /usr/share/dk4app */ 70 DK4_FS_CONF_ETC_LIB , /**< /etc/dk4app */ 71 DK4_FS_CONF_SHARE_LIB_SITE , /**< /usr/share/dk4app-site */ 72 DK4_FS_CONF_ETC_LIB_SITE , /**< /etc/dk4app-site */ 73 DK4_FS_CONF_SHARE_GROUP , /**< /usr/share/group */ 74 DK4_FS_CONF_ETC_GROUP , /**< /etc/group */ 75 DK4_FS_CONF_SHARE_GROUP_SITE , /**< /usr/share/group-site */ 76 DK4_FS_CONF_ETC_GROUP_SITE , /**< /etc/group-site */ 77 DK4_FS_CONF_SHARE_APP , /**< /usr/share/prog */ 78 DK4_FS_CONF_ETC_APP , /**< /etc/prog */ 79 DK4_FS_CONF_SHARE_APP_SITE , /**< /usr/share/prog-site */ 80 DK4_FS_CONF_ETC_APP_SITE , /**< /etc/prog-site */ 81 DK4_FS_CONF_HOME_LIB , /**< HOME/.dk4app */ 82 DK4_FS_CONF_HOME_GROUP , /**< HOME/.dk4app/group */ 83 DK4_FS_CONF_HOME_APP , /**< HOME/.dk4app/prog */ 84 DK4_FS_CONF_CURRENT_DIR , /**< Current directory */ 85 86 /** Maximum value. 87 */ 88 DK4_FS_CONF_MAX = DK4_FS_CONF_CURRENT_DIR , 89 90 /** Maximum value to search 91 system directories only. 92 */ 93 DK4_FS_CONF_SYS_MAX = DK4_FS_CONF_ETC_APP_SITE 94 }; 95 96 97 98 /** Pass numbers for data file search. 99 100 The group name passed as name_group is used instead of group, 101 the program name passed as name_prog is used instead of prog. 102 */ 103 enum { 104 DK4_FS_DATA_SHARE_LIB = 0, /**< /usr/share/dk4app */ 105 DK4_FS_DATA_SHARE_LIB_SITE , /**< /usr/share/dk4app-site */ 106 DK4_FS_DATA_SHARE_GROUP , /**< /usr/share/group */ 107 DK4_FS_DATA_SHARE_GROUP_SITE , /**< /usr/share/group-site */ 108 DK4_FS_DATA_SHARE_APP , /**< /usr/share/prog */ 109 DK4_FS_DATA_SHARE_APP_SITE , /**< /usr/share/prog-site */ 110 DK4_FS_DATA_SHARE_LIB_LANG , /**< /usr/share/dk4app/l */ 111 DK4_FS_DATA_SHARE_LIB_SITE_LANG , /**< /usr/share/dk4app-site/l */ 112 DK4_FS_DATA_SHARE_GROUP_LANG , /**< /usr/share/group/l */ 113 DK4_FS_DATA_SHARE_GROUP_SITE_LANG , /**< /usr/share/group-site/l */ 114 DK4_FS_DATA_SHARE_APP_LANG , /**< /usr/share/prog/l */ 115 DK4_FS_DATA_SHARE_APP_SITE_LANG , /**< /usr/share/prog-site/l */ 116 DK4_FS_DATA_SHARE_LIB_REG , /**< /usr/share/dk4app */ 117 DK4_FS_DATA_SHARE_LIB_SITE_REG , /**< /usr/share/dk4app-site */ 118 DK4_FS_DATA_SHARE_GROUP_REG , /**< /usr/share/group */ 119 DK4_FS_DATA_SHARE_GROUP_SITE_REG , /**< /usr/share/group-site */ 120 DK4_FS_DATA_SHARE_APP_REG , /**< /usr/share/prog/no-language/r */ 121 DK4_FS_DATA_SHARE_APP_SITE_REG , /**< /usr/share/prog-site/no-language/r */ 122 DK4_FS_DATA_SHARE_LIB_LANG_REG , /**< /usr/share/dk4app/l/r */ 123 DK4_FS_DATA_SHARE_LIB_SITE_LANG_REG , /**< /usr/share/dk4app-site/l/r */ 124 DK4_FS_DATA_SHARE_GROUP_LANG_REG , /**< /usr/share/group/l/r */ 125 DK4_FS_DATA_SHARE_GROUP_SITE_LANG_REG , /**< /usr/share/group-site/l/r */ 126 DK4_FS_DATA_SHARE_APP_LANG_REG , /**< /usr/share/prog/l/r */ 127 DK4_FS_DATA_SHARE_APP_SITE_LANG_REG , /**< /usr/share/prog-site/l/r */ 128 DK4_FS_DATA_HOME_LIB , /**< HOME/.dk4app */ 129 DK4_FS_DATA_HOME_GROUP , /**< HOME/.dk4app/group */ 130 DK4_FS_DATA_HOME_APP , /**< HOME/.dk4app/prog */ 131 DK4_FS_DATA_CURRENT_DIR , /**< Current directory */ 132 133 /** Maximum system data file. 134 */ 135 DK4_FS_DATA_MAX_SYS = DK4_FS_DATA_SHARE_APP_SITE_LANG_REG, 136 137 /** Maximum data file. 138 */ 139 DK4_FS_DATA_MAX = DK4_FS_DATA_CURRENT_DIR 140 }; 141 142 143 /** Pass numbers for documentation and help file search. 144 */ 145 enum { 146 147 /** /usr/share/dktools/help/wxdkdraw/de/de. */ 148 149 DK4_FS_DOC_GROUP_HELP_PROG_LANG_REG = 0, 150 151 /** /usr/share/doc/dktools/help/wxdkdraw/de/de. */ 152 153 DK4_FS_DOC_DOC_GROUP_PROG_LANG_REG , 154 155 /** /usr/share/dktools/help/wxdkdraw/de. */ 156 157 DK4_FS_DOC_GROUP_HELP_PROG_LANG , 158 159 /** /usr/share/doc/dktools/help/wxdkdraw/de. */ 160 161 DK4_FS_DOC_DOC_GROUP_PROG_LANG , 162 163 /* The en subdirectory is used as fallback if no file in current 164 language is available. 165 */ 166 167 /** /usr/share/dktools/help/wxdkdraw/en. */ 168 169 DK4_FS_DOC_GROUP_HELP_PROG_EN , 170 171 /** /usr/share/doc/dktools/help/wxdkdraw/en. */ 172 173 DK4_FS_DOC_DOC_GROUP_PROG_EN , 174 175 /** /usr/share/dktools/help/wxdkdraw. */ 176 177 DK4_FS_DOC_GROUP_HELP_PROG , 178 179 /** /usr/share/doc/dktools/help/wxdkdraw. */ 180 181 DK4_FS_DOC_DOC_GROUP_PROG , 182 183 /** /usr/share/dktools/help/de/de. */ 184 185 DK4_FS_DOC_GROUP_HELP_LANG_REG , 186 187 /** /usr/share/doc/dktools/help/de/de. */ 188 189 DK4_FS_DOC_DOC_GROUP_LANG_REG , 190 191 /** /usr/share/dktools/help/de. */ 192 193 DK4_FS_DOC_GROUP_HELP_LANG , 194 195 /** /usr/share/doc/dktools/help/de. */ 196 197 DK4_FS_DOC_DOC_GROUP_LANG , 198 199 /* The en subdirectory is used as fallback if no file in current 200 language is available. 201 */ 202 203 /** /usr/share/dktools/help/en. */ 204 205 DK4_FS_DOC_GROUP_HELP_EN , 206 207 /** /usr/share/doc/dktools/help/en. */ 208 209 DK4_FS_DOC_DOC_GROUP_EN , 210 211 /** /usr/share/dktools/help. */ 212 213 DK4_FS_DOC_GROUP_HELP , 214 215 /** /usr/share/doc/dktools/help. */ 216 217 DK4_FS_DOC_DOC_GROUP , 218 219 DK4_FS_DOC_MAX = DK4_FS_DOC_DOC_GROUP /**< Maximum. */ 220 }; 221 222 223 224 #ifdef __cplusplus 225 extern "C" { 226 #endif 227 228 /** Check presence of one file, optionally with compression suffixes. 229 CRT on Windows: Optional. 230 @param dptr Buffer containing file name. 231 @param szdptr Buffer size. 232 @param compressed Flag: Search for compressed files too. 233 @param erp Error report, may be NULL. 234 @return 1 if file or optionally compressed file found, 0 otherwise. 235 236 Error codes: 237 - DK4_E_INVALID_ARGUMENTS<br> 238 if dptr is NULL or szdptr is 0, 239 - DK4_E_NOT_SUPPORTED<br> 240 if wchar_t are used as dkChar on non-Windows systems, 241 - DK4_E_NOT_FOUND<br> 242 if the file was not found. 243 */ 244 int 245 dk4fs_attempt_file_name( 246 dkChar *dptr, 247 size_t szdptr, 248 int compressed, 249 dk4_er_t *erp 250 ); 251 252 /** Attempt to construct one file name from multiple parts. 253 CRT on Windows: Optional. 254 @param dptr Destination buffer address. 255 @param szdptr Destination buffer size (number of dkChar). 256 @param comp Components array. 257 @param ncomp Number of components. 258 @param site Flag: Add -site after second component. 259 @param erp Error report, may be NULL. 260 @return 1 on success (path constructed and file exists), 0 otherwise. 261 262 Error codes: 263 - DK4_E_INVALID_ARGUMENTS<br> 264 if dptr or comp is NULL or szdptr or ncomp is 0, 265 - DK4_E_BUFFER_TOO_SMALL<br> 266 if the dptr buffer is too small, 267 - DK4_E_MATH_OVERFLOW<br> 268 if a mathematical overflow happened during 269 a size calculation. 270 */ 271 int 272 dk4fs_construct_from_parts( 273 dkChar *dptr, 274 size_t szdptr, 275 const dkChar **comp, 276 size_t ncomp, 277 int site, 278 dk4_er_t *erp 279 ); 280 281 /** Attempt to construct one path name for a configuration file. 282 CRT on Windows: Optional. 283 @param dptr Buffer for result file name. 284 @param szdptr Size of buffer (number of dkChar). 285 @param shortname Short configuration file name. 286 @param dir_share The data directory. 287 @param dir_etc The system configuration directory. 288 @param dir_home Users home directory. 289 @param name_prog Application name. 290 @param name_group Application group name. 291 @param passno Number of current pass. 292 @param co3 Flag: Compatible to DK tools 3. 293 @param erp Error report, may be NULL. 294 @return 1 on success, 0 on error. 295 296 Error codes: 297 - DK4_E_INVALID_ARGUMENTS<br> 298 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 299 number or one of the used strings (dir_share, dir_etc, dir_home, 300 name_prog, or name_group) is NULL, 301 - DK4_E_BUFFER_TOO_SMALL<br> 302 if the dptr buffer is too small, 303 - DK4_E_MATH_OVERFLOW<br> 304 if a mathematical overflow happened during a size calculation. 305 */ 306 int 307 dk4fs_config_construct_compat_one( 308 dkChar *dptr, 309 size_t szdptr, 310 const dkChar *shortname, 311 const dkChar *dir_share, 312 const dkChar *dir_etc, 313 const dkChar *dir_home, 314 const dkChar *name_prog, 315 const dkChar *name_group, 316 int passno, 317 int co3, 318 dk4_er_t *erp 319 ); 320 321 /** Attempt to construct one path name for a configuration file. 322 CRT on Windows: Optional. 323 @param dptr Buffer for result file name. 324 @param szdptr Size of buffer (number of dkChar). 325 @param shortname Short configuration file name. 326 @param dir_share The data directory. 327 @param dir_etc The system configuration directory. 328 @param dir_home Users home directory. 329 @param name_prog Application name. 330 @param name_group Application group name. 331 @param passno Number of current pass. 332 @param erp Error report, may be NULL. 333 @return 1 on success, 0 on error. 334 335 Error codes: 336 - DK4_E_INVALID_ARGUMENTS<br> 337 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 338 number or one of the used strings (dir_share, dir_etc, dir_home, 339 name_prog, or name_group) is NULL, 340 - DK4_E_BUFFER_TOO_SMALL<br> 341 if the dptr buffer is too small, 342 - DK4_E_MATH_OVERFLOW<br> 343 if a mathematical overflow happened during a size calculation. 344 */ 345 int 346 dk4fs_config_construct_one( 347 dkChar *dptr, 348 size_t szdptr, 349 const dkChar *shortname, 350 const dkChar *dir_share, 351 const dkChar *dir_etc, 352 const dkChar *dir_home, 353 const dkChar *name_prog, 354 const dkChar *name_group, 355 int passno, 356 dk4_er_t *erp 357 ); 358 359 /** Check one path candidate for configuration file name 360 (construct name and check presence of file). 361 362 To search for a file matching your needs run this function 363 multiple times with differenct passno values. 364 - To search for one file best matching: 365 - Start with pass number DK4_FS_CONF_MAX or DK4_FS_CONF_SYS_MAX 366 and decrease the number down to DK4_FS_CONF_SHARE_LIB, 367 use the first file found. 368 - Start with pass number DK4_FS_CONF_MAX to allow both user 369 and system configuration files. 370 - Start with pass number DK4_FS_CONF_SYS_MAX to process system 371 configuration files only. 372 - To process multiple files, each file may overwrite settings 373 made by previous files: 374 - Start with pass number DK4_FS_CONF_SHARE_LIB (0) and increase 375 the pass number up to DK4_FS_CONF_SYS_MAX or DK4_FS_CONF_MAX. 376 - Stopping after DK4_FS_CONF_SYS_MAX will process system 377 configuration files only, stopping after DK4_FS_CONF_MAX 378 processes both system and user configuration files. 379 380 CRT on Windows: Optional. 381 @param dptr Buffer for result file name. 382 @param szdptr Size of buffer (number of dkChar). 383 @param shortname Short configuration file name. 384 @param dir_share The data directory. 385 @param dir_etc The system configuration directory. 386 @param dir_home Users home directory. 387 @param name_prog Application name. 388 @param name_group Application group name. 389 @param passno Number of current pass. 390 @param co3 Flag: Compatible mode to DK tools 3. 391 @param compressed Flag: Allow gzip and bzip2 compressed files 392 too, if the library was build with gzip 393 and/or bzip2 support. 394 @param erp Error report, may be NULL. 395 @return 1 on success, 0 on error. 396 397 Error codes: 398 - DK4_E_INVALID_ARGUMENTS<br> 399 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 400 number or one of the used strings (dir_share, dir_etc, dir_home, 401 name_prog, or name_group) is NULL, 402 - DK4_E_BUFFER_TOO_SMALL<br> 403 if the dptr buffer is too small, 404 - DK4_E_MATH_OVERFLOW<br> 405 if a mathematical overflow happened during a size calculation, 406 - DK4_E_NOT_FOUND<br> 407 if no file was found, 408 - DK4_E_NOT_SUPPORTED<br> 409 if wchar_t are used as dkChar on non-Windows systems. 410 */ 411 int 412 dk4fs_config_compat_one( 413 dkChar *dptr, 414 size_t szdptr, 415 const dkChar *shortname, 416 const dkChar *dir_share, 417 const dkChar *dir_etc, 418 const dkChar *dir_home, 419 const dkChar *name_prog, 420 const dkChar *name_group, 421 int passno, 422 int co3, 423 int compressed, 424 dk4_er_t *erp 425 ); 426 427 /** Check one path candidate for configuration file name 428 (construct name and check presence of file). 429 430 To search for a file matching your needs run this function 431 multiple times with differenct passno values. 432 - To search for one file best matching: 433 - Start with pass number DK4_FS_CONF_MAX or DK4_FS_CONF_SYS_MAX 434 and decrease the number down to DK4_FS_CONF_SHARE_LIB, 435 use the first file found. 436 - Start with pass number DK4_FS_CONF_MAX to allow both user 437 and system configuration files. 438 - Start with pass number DK4_FS_CONF_SYS_MAX to process system 439 configuration files only. 440 - To process multiple files, each file may overwrite settings 441 made by previous files: 442 - Start with pass number DK4_FS_CONF_SHARE_LIB (0) and increase 443 the pass number up to DK4_FS_CONF_SYS_MAX or DK4_FS_CONF_MAX. 444 - Stopping after DK4_FS_CONF_SYS_MAX will process system 445 configuration files only, stopping after DK4_FS_CONF_MAX 446 processes both system and user configuration files. 447 448 CRT on Windows: Optional. 449 @param dptr Buffer for result file name. 450 @param szdptr Size of buffer (number of dkChar). 451 @param shortname Short configuration file name. 452 @param dir_share The data directory. 453 @param dir_etc The system configuration directory. 454 @param dir_home Users home directory. 455 @param name_prog Application name. 456 @param name_group Application group name. 457 @param passno Number of current pass. 458 @param compressed Flag: Allow gzip and bzip2 compressed files 459 too, if the library was build with gzip 460 and/or bzip2 support. 461 @param erp Error report, may be NULL. 462 @return 1 on success, 0 on error. 463 464 Error codes: 465 - DK4_E_INVALID_ARGUMENTS<br> 466 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 467 number or one of the used strings (dir_share, dir_etc, dir_home, 468 name_prog, or name_group) is NULL, 469 - DK4_E_BUFFER_TOO_SMALL<br> 470 if the dptr buffer is too small, 471 - DK4_E_MATH_OVERFLOW<br> 472 if a mathematical overflow happened during a size calculation, 473 - DK4_E_NOT_FOUND<br> 474 if no file was found, 475 - DK4_E_NOT_SUPPORTED<br> 476 if wchar_t are used as dkChar on non-Windows systems. 477 */ 478 int 479 dk4fs_config_one( 480 dkChar *dptr, 481 size_t szdptr, 482 const dkChar *shortname, 483 const dkChar *dir_share, 484 const dkChar *dir_etc, 485 const dkChar *dir_home, 486 const dkChar *name_prog, 487 const dkChar *name_group, 488 int passno, 489 int compressed, 490 dk4_er_t *erp 491 ); 492 493 /** Attempt to construct one path name for a data file. 494 CRT on Windows: Optional. 495 @param dptr Buffer for result file name. 496 @param szdptr Size of buffer (number of dkChar). 497 @param shortname Short configuration file name. 498 @param dir_share The data directory. 499 @param language Users language. 500 @param region Users region. 501 @param dir_home Users home directory. 502 @param name_prog Application name. 503 @param name_group Application group name. 504 @param passno Number of current pass. 505 @param erp Error report, may be NULL. 506 @return 1 on success, 0 on error. 507 508 Error codes: 509 - DK4_E_INVALID_ARGUMENTS<br> 510 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 511 number or one of the used strings (dir_share, dir_home, language, 512 region, name_prog, or name_group) is NULL, 513 - DK4_E_BUFFER_TOO_SMALL<br> 514 if the dptr buffer is too small, 515 - DK4_E_MATH_OVERFLOW<br> 516 if a mathematical overflow happened during a size calculation. 517 */ 518 int 519 dk4fs_data_construct_one( 520 dkChar *dptr, 521 size_t szdptr, 522 const dkChar *shortname, 523 const dkChar *dir_share, 524 const dkChar *language, 525 const dkChar *region, 526 const dkChar *dir_home, 527 const dkChar *name_prog, 528 const dkChar *name_group, 529 int passno, 530 dk4_er_t *erp 531 ); 532 533 /** Check one path candidate for data file name 534 (construct file name and check presence). 535 536 To search for a file, use this function multiple times with different 537 passno values: 538 - Start with DK4_F_DATA_MAX, DK4_FS_DATA_CURRENT_DIR, 539 DK4_FS_DATA_HOME_APP or DK4_FS_DATA_MAX_SYS. 540 - Decrease the pass number down to DK4_FS_DATA_SHARE_LIB. 541 - Use the first file found. 542 543 CRT on Windows: Optional. 544 @param dptr Buffer for result file name. 545 @param szdptr Size of buffer (number of dkChar). 546 @param shortname Short configuration file name. 547 @param dir_share The data directory. 548 @param dir_home Users home directory. 549 @param name_prog Application name. 550 @param name_group Application group name. 551 @param language Users preferred language. 552 @param region Users region (country code). 553 @param passno Number of current pass. 554 @param compressed Flag: Allow compressed files too. 555 @param erp Error report, may be NULL. 556 @return 1 on success, 0 on error. 557 558 Error codes: 559 - DK4_E_INVALID_ARGUMENTS<br> 560 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 561 number or one of the used strings (dir_share, dir_home, language, 562 region, name_prog, or name_group) is NULL, 563 - DK4_E_BUFFER_TOO_SMALL<br> 564 if the dptr buffer is too small, 565 - DK4_E_MATH_OVERFLOW<br> 566 if a mathematical overflow happened during a size calculation, 567 - DK4_E_NOT_FOUND<br> 568 if no file was found, 569 - DK4_E_NOT_SUPPORTED<br> 570 if wchar_t are used as dkChar on non-Windows systems. 571 */ 572 int 573 dk4fs_data_one( 574 dkChar *dptr, 575 size_t szdptr, 576 const dkChar *shortname, 577 const dkChar *dir_share, 578 const dkChar *dir_home, 579 const dkChar *name_prog, 580 const dkChar *name_group, 581 const dkChar *language, 582 const dkChar *region, 583 int passno, 584 int compressed, 585 dk4_er_t *erp 586 ); 587 588 /** Attempt to construct one path name for a documentation or help file. 589 CRT on Windows: Optional. 590 @param dptr Buffer for result file name. 591 @param szdptr Size of buffer (number of dkChar). 592 @param shortname Short configuration file name. 593 @param dir_share The data directory. 594 @param language Users language. 595 @param region Users region. 596 @param name_prog Application name. 597 @param name_group Application group name. 598 @param passno Number of current pass. 599 @param erp Error report, may be NULL. 600 @return 1 on success, 0 on error. 601 602 Error codes: 603 - DK4_E_INVALID_ARGUMENTS<br> 604 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 605 number or one of the used strings (dir_share, dir_home, language, 606 region, name_prog, or name_group) is NULL, 607 - DK4_E_BUFFER_TOO_SMALL<br> 608 if the dptr buffer is too small, 609 - DK4_E_MATH_OVERFLOW<br> 610 if a mathematical overflow happened during a size calculation. 611 */ 612 int 613 dk4fs_doc_construct_one( 614 dkChar *dptr, 615 size_t szdptr, 616 const dkChar *shortname, 617 const dkChar *dir_share, 618 const dkChar *language, 619 const dkChar *region, 620 const dkChar *name_prog, 621 const dkChar *name_group, 622 int passno, 623 dk4_er_t *erp 624 ); 625 626 /** Check one path candidate for documentation or help file name 627 (construct file name and check presence). 628 629 To search for a file, use this function multiple times with different 630 passno values: 631 - Start with DK4_FS_DOC_GROUP_HELP_PROG_LANG_REG. 632 - Increase the pass number up to (including) DK4_FS_DOC_MAX. 633 - Use the first file found. 634 635 CRT on Windows: Optional. 636 @param dptr Buffer for result file name. 637 @param szdptr Size of buffer (number of dkChar). 638 @param shortname Short configuration file name. 639 @param dir_share The data directory. 640 @param name_prog Application name. 641 @param name_group Application group name. 642 @param language Users preferred language. 643 @param region Users region (country code). 644 @param passno Number of current pass. 645 @param erp Error report, may be NULL. 646 @return 1 on success, 0 on error. 647 648 The function searches for the file <i>shortname</i> in the 649 following directories, first file found is returned: 650 - /usr/share/<i>group</i>/help/<i>program</i>/<i>language</i>/<i>region</i> 651 - /usr/share/doc/<i>group</i>/help/<i>program</i>/<i>language</i>/<i>region</i> 652 - /usr/share/<i>group</i>/help/<i>program</i>/<i>language</i> 653 - /usr/share/doc/<i>group</i>/help/<i>program</i>/<i>language</i> 654 - /usr/share/<i>group</i>/help/<i>program</i>/en 655 - /usr/share/doc/<i>group</i>/help/<i>program</i>/en 656 - /usr/share/<i>group</i>/help/<i>program</i> 657 - /usr/share/doc/<i>group</i>/help/<i>program</i> 658 659 For a relocated installation replace /usr/share by ${datadir}. 660 661 Error codes: 662 - DK4_E_INVALID_ARGUMENTS<br> 663 if dptr or shortname is NULL or szdptr is 0 or passno is an invalid 664 number or one of the used strings (dir_share, dir_home, language, 665 region, name_prog, or name_group) is NULL, 666 - DK4_E_BUFFER_TOO_SMALL<br> 667 if the dptr buffer is too small, 668 - DK4_E_MATH_OVERFLOW<br> 669 if a mathematical overflow happened during a size calculation, 670 - DK4_E_NOT_FOUND<br> 671 if no file was found, 672 - DK4_E_NOT_SUPPORTED<br> 673 if wchar_t are used as dkChar on non-Windows systems. 674 */ 675 int 676 dk4fs_doc_one( 677 dkChar *dptr, 678 size_t szdptr, 679 const dkChar *shortname, 680 const dkChar *dir_share, 681 const dkChar *name_prog, 682 const dkChar *name_group, 683 const dkChar *language, 684 const dkChar *region, 685 int passno, 686 dk4_er_t *erp 687 ); 688 689 #ifdef __cplusplus 690 } 691 #endif 692 693 694 695 696 #endif 697