annotate common/portpath.h @ 1304:82fab0c689bf 0.9.3

Fix doxygen syntax error. Change inout to in,out
author Andre Heinecke <andre.heinecke@intevation.de>
date Mon, 29 Sep 2014 16:42:06 +0200
parents fd7d04bb37cb
children
rev   line source
404
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 176
diff changeset
1 /* Copyright (C) 2014 by Bundesamt für Sicherheit in der Informationstechnik
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 176
diff changeset
2 * Software engineering by Intevation GmbH
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 176
diff changeset
3 *
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 176
diff changeset
4 * This file is Free Software under the GNU GPL (v>=2)
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 176
diff changeset
5 * and comes with ABSOLUTELY NO WARRANTY!
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 176
diff changeset
6 * See LICENSE.txt for details.
17e1c8f37d72 Add License
Andre Heinecke <aheinecke@intevation.de>
parents: 176
diff changeset
7 */
146
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
8 #ifndef PORTPATH_H
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
9 #define PORTPATH_H
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
10
168
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
11 #include <stdbool.h>
1157
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
12 #include <stdio.h>
168
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
13
146
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
14 /**
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
15 * @file portpath.h
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
16 * @brief Platform independent functions for file and path handling.
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
17 * @details portpath contains functions to handle file and path names
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
18 * in a platform independent way. The code unsing this functions
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
19 * should be protable between GNU/Linux and Windows32 systems.
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
20 */
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
21
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
22 /**
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
23 * @brief portable version of dirname
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
24 * @details return the directory component of the given path.
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
25 * The argument path may be altered by the function.
1304
82fab0c689bf Fix doxygen syntax error. Change inout to in,out
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1157
diff changeset
26 * @param[in,out] path the pathname
146
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
27 * @returns a pointer to the string containing the directory component
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
28 */
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
29 char *port_dirname(char *path);
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
30
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
31 /**
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
32 * @brief portable version of realpath
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
33 * @details return the expanded absolute pathname for the given path.
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
34 * The buffer for the resolved path is allocated by this function and
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
35 * should be freed by the caller.
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
36 * @param[in] path the original pathname
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
37 * @returns a pointer to the resolved path or NULL on error
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
38 */
975
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
39 char *port_realpath(const char *path);
146
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
40
168
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
41 /**
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
42 * @brief test if a file exists
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
43 * @details uses a platform specific stat call to test if the given
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
44 * file exists.
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
45 * @param[in] path the path to the file
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
46 * @returns true if the file exists and false otherwise
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
47 */
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
48 bool port_fileexits(char *path);
f100861dad8f Added simple portable function to test if an file exists.
Sascha Wilde <wilde@intevation.de>
parents: 167
diff changeset
49
176
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
50 /**
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
51 * @brief test if a file is a directory
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
52 * @details uses a platform specific stat call to test if the given
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
53 * file is an directory.
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
54 * @param[in] path the path to the file
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
55 * @returns true if the file is an directory and false otherwise
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
56 */
984
faf58e9f518b Add recursive mkdir and mkdir for windows
Andre Heinecke <andre.heinecke@intevation.de>
parents: 975
diff changeset
57 bool port_isdir(const char *path);
176
70d627e9e801 New portability function to test if a file is an directory.
Sascha Wilde <wilde@intevation.de>
parents: 168
diff changeset
58
975
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
59 /**
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
60 * @brief create a directory
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
61 * @details uses a platform specific mkdir / access rights setup
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
62 * to create a directory that is world readable and
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
63 * writable by the current user / group
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
64 * @param[in] path the path to the directory
1070
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
65 * @param[in] propagate_acl weather or not objects should inherit
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
66 * the ACL of this directory. Only has an effect on Windows.
975
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
67 * @returns true if the directory was created
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
68 */
1070
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
69 bool port_mkdir(const char *path, bool propagate_acl);
975
b3695a3399de (issue86) Install into default directories on Linux
Andre Heinecke <andre.heinecke@intevation.de>
parents: 404
diff changeset
70
984
faf58e9f518b Add recursive mkdir and mkdir for windows
Andre Heinecke <andre.heinecke@intevation.de>
parents: 975
diff changeset
71 /**
faf58e9f518b Add recursive mkdir and mkdir for windows
Andre Heinecke <andre.heinecke@intevation.de>
parents: 975
diff changeset
72 * @brief create a directory and its parent directores
1070
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
73 *
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
74 * On Windows the last directory will propagate it's ACL
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
75 * to objects and subdirectories. The parent directories
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
76 * will not.
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
77 *
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
78 * @param[in] propagate_acl weather or not the
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
79 * last created directory should propagate it's acl.
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
80 * Only has an effect on Windows.
984
faf58e9f518b Add recursive mkdir and mkdir for windows
Andre Heinecke <andre.heinecke@intevation.de>
parents: 975
diff changeset
81 * @param[in] path the path to the directory
faf58e9f518b Add recursive mkdir and mkdir for windows
Andre Heinecke <andre.heinecke@intevation.de>
parents: 975
diff changeset
82 * @returns true if the directory was created
faf58e9f518b Add recursive mkdir and mkdir for windows
Andre Heinecke <andre.heinecke@intevation.de>
parents: 975
diff changeset
83 */
1070
f110a3f6e387 (issue114) Fine tune ACL propagation
Andre Heinecke <andre.heinecke@intevation.de>
parents: 984
diff changeset
84 bool port_mkdir_p(const char *path, bool propagate_acl);
984
faf58e9f518b Add recursive mkdir and mkdir for windows
Andre Heinecke <andre.heinecke@intevation.de>
parents: 975
diff changeset
85
1157
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
86 /**
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
87 * @brief Open a file in read binary mode
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
88 *
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
89 * @param[in] path UTF-8 (or local 8 bit encoding)
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
90 * encoded filename
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
91 * @param[in] exclusive weather or not to open the file with
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
92 * a denywr lock. Ignored under linux.
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
93 * @returns the same as fopen.
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
94 */
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
95 FILE* port_fopen_rb(const char *path, bool exclusive);
fd7d04bb37cb (issue36) Add encoding aware port_fopen function and use it
Andre Heinecke <andre.heinecke@intevation.de>
parents: 1070
diff changeset
96
146
306e4db11761 Added portable path name handling functions.
Sascha Wilde <wilde@intevation.de>
parents:
diff changeset
97 #endif

http://wald.intevation.org/projects/trustbridge/