A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
system-path.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef SYSTEM_PATH_H
9#define SYSTEM_PATH_H
10
11#include <list>
12#include <string>
13
14/**
15 * @file
16 * @ingroup systempath
17 * ns3::SystemPath declarations.
18 */
19
20namespace ns3
21{
22
23/**
24 * @ingroup system
25 * @defgroup systempath Host Filesystem
26 * @brief Encapsulate OS-specific functions to manipulate file
27 * and directory paths.
28 *
29 * The functions provided here are used mostly to implement
30 * the ns-3 test framework.
31 */
32
33/**
34 * @ingroup systempath
35 * @brief Namespace for various file and directory path functions.
36 */
37namespace SystemPath
38{
39
40/**
41 * @ingroup systempath
42 * Get the file system path to the current executable.
43 *
44 * This path is only equivalent to the current working directory when
45 * the executable is executed in its parent directory.
46 *
47 * @return The directory in which the currently-executing binary is located
48 */
49std::string FindSelfDirectory();
50
51/**
52 * @ingroup systempath
53 * Join two file system path elements.
54 *
55 * @param [in] left A path element
56 * @param [in] right A path element
57 * @return A concatenation of the two input paths
58 */
59std::string Append(std::string left, std::string right);
60
61/**
62 * @ingroup systempath
63 * Split a file system path into directories according to
64 * the local path separator.
65 *
66 * This is the inverse of Join.
67 *
68 * @param [in] path A path
69 * @return A list of path elements that can be joined together again with
70 * the Join function.
71 * \sa ns3::SystemPath::Join
72 */
73std::list<std::string> Split(std::string path);
74
75/**
76 * Join a list of file system path directories into a single
77 * file system path.
78 *
79 * This is the inverse of Split.
80 *
81 * @ingroup systempath
82 * @param [in] begin Iterator to first element to join
83 * @param [in] end Iterator to one past the last element to join
84 * @return A path that is a concatenation of all the input elements.
85 */
86std::string Join(std::list<std::string>::const_iterator begin,
87 std::list<std::string>::const_iterator end);
88
89/**
90 * @ingroup systempath
91 * Get the list of files located in a file system directory.
92 *
93 * @param [in] path A path which identifies a directory
94 * @return A list of the filenames which are located in the input directory
95 */
96std::list<std::string> ReadFiles(std::string path);
97
98/**
99 * @ingroup systempath
100 * Get the name of a temporary directory.
101 *
102 * The returned path identifies a directory which does not exist yet.
103 * Call ns3::SystemPath::MakeDirectories to create it. Yes, there is a
104 * well-known security race in this API but we don't care in ns-3.
105 *
106 * The final path to the directory is going to look something like
107 *
108 * /tmp/ns3.14.30.29.32767
109 *
110 * The first part, "/tmp/" is the absolute path found by inspecting
111 * the environment variables `TMP`and `TEMP`, in order. If neither
112 * exists the hard-coded root path `/tmp/` is used.
113 *
114 * The directory name itself starts with the "ns3" identifier telling folks
115 * who is making all of the temp directories.
116 *
117 * The next three numbers give the hour, minute and second, separated by
118 * periods.
119 *
120 * The final number is randomly generated, to avoid name collisions.
121 *
122 * @return A path which identifies a temporary directory.
123 */
124std::string MakeTemporaryDirectoryName();
125
126/**
127 * @ingroup systempath
128 * Create all the directories leading to path.
129 *
130 * @param [in] path A path to a directory
131 */
132void MakeDirectories(std::string path);
133
134/**
135 * @ingroup systempath
136 * Check if a path exists.
137 * Path can be a file or directory.
138 * @param [in] path The path to check.
139 * @returns \c true if the \pname{path} exists.
140 */
141bool Exists(const std::string path);
142
143/**
144 * @ingroup systempath
145 * Replace incompatible characters in a path,
146 * to get a path compatible with different
147 * file systems.
148 * @param [in] path The path to check.
149 * @returns A compatible path.
150 */
151std::string CreateValidSystemPath(const std::string path);
152
153} // namespace SystemPath
154
155} // namespace ns3
156
157#endif /* SYSTEM_PATH_H */
std::list< std::string > ReadFiles(std::string path)
Get the list of files located in a file system directory.
bool Exists(const std::string path)
Check if a path exists.
std::list< std::string > Split(std::string path)
Split a file system path into directories according to the local path separator.
void MakeDirectories(std::string path)
Create all the directories leading to path.
std::string MakeTemporaryDirectoryName()
Get the name of a temporary directory.
std::string Append(std::string left, std::string right)
Join two file system path elements.
std::string Join(std::list< std::string >::const_iterator begin, std::list< std::string >::const_iterator end)
Join a list of file system path directories into a single file system path.
std::string CreateValidSystemPath(const std::string path)
Replace incompatible characters in a path, to get a path compatible with different file systems.
std::string FindSelfDirectory()
Get the file system path to the current executable.
Namespace for various file and directory path functions.
Every class exported by the ns3 library is enclosed in the ns3 namespace.