/src/libfsntfs/libfsntfs/libfsntfs_path_hint.c

Source
/*
 * Path hint functions
 *
 * Copyright (C) 2010-2026, Joachim Metz <joachim.metz@gmail.com>
 *
 * Refer to AUTHORS for acknowledgements.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

#include <common.h>
#include <memory.h>
#include <types.h>

#include "libfsntfs_libcdata.h"
#include "libfsntfs_libcerror.h"
#include "libfsntfs_libuna.h"
#include "libfsntfs_path_hint.h"

/* Creates a path hint
 * Make sure the value path_hint is referencing, is set to NULL
 * Returns 1 if successful or -1 on error
 */
int libfsntfs_path_hint_initialize(
     libfsntfs_path_hint_t **path_hint,
     libcerror_error_t **error )
{
  static char *function = "libfsntfs_path_hint_initialize";

  if( path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid path hint.",
     function );

    return( -1 );
  }
  if( *path_hint != NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_RUNTIME,
     LIBCERROR_RUNTIME_ERROR_VALUE_ALREADY_SET,
     "%s: invalid path hint value already set.",
     function );

    return( -1 );
  }
  *path_hint = memory_allocate_structure(
                libfsntfs_path_hint_t );

  if( *path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_MEMORY,
     LIBCERROR_MEMORY_ERROR_INSUFFICIENT,
     "%s: unable to create path hint.",
     function );

    goto on_error;
  }
  if( memory_set(
       *path_hint,
       0,
       sizeof( libfsntfs_path_hint_t ) ) == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_MEMORY,
     LIBCERROR_MEMORY_ERROR_SET_FAILED,
     "%s: unable to clear path hint.",
     function );

    goto on_error;
  }
  return( 1 );

on_error:
  if( *path_hint != NULL )
  {
    memory_free(
     *path_hint );

    *path_hint = NULL;
  }
  return( -1 );
}

/* Frees a path hint
 * Returns 1 if successful or -1 on error
 */
int libfsntfs_path_hint_free(
     libfsntfs_path_hint_t **path_hint,
     libcerror_error_t **error )
{
  static char *function = "libfsntfs_path_hint_free";

  if( path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid path hint.",
     function );

    return( -1 );
  }
  if( *path_hint != NULL )
  {
    if( ( *path_hint )->path != NULL )
    {
      memory_free(
       ( *path_hint )->path );
    }
    memory_free(
     *path_hint );

    *path_hint = NULL;
  }
  return( 1 );
}

/* Compares 2 path hints by file reference
 * Returns LIBCDATA_COMPARE_LESS, LIBCDATA_COMPARE_EQUAL, LIBCDATA_COMPARE_GREATER if successful or -1 on error
 */
int libfsntfs_path_hint_compare_by_file_reference(
     libfsntfs_path_hint_t *first_path_hint,
     libfsntfs_path_hint_t *second_path_hint,
     libcerror_error_t **error )
{
  static char *function           = "libfsntfs_path_hint_compare_by_file_reference";
  uint64_t first_mft_entry_index  = 0;
  uint64_t second_mft_entry_index = 0;
  uint16_t first_sequence_number  = 0;
  uint16_t second_sequence_number = 0;

  if( first_path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid first path hint.",
     function );

    return( -1 );
  }
  if( second_path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid second path hint.",
     function );

    return( -1 );
  }
  first_mft_entry_index  = first_path_hint->file_reference & 0xffffffffffffUL;
  second_mft_entry_index = second_path_hint->file_reference & 0xffffffffffffUL;

  if( first_mft_entry_index < second_mft_entry_index )
  {
    return( LIBCDATA_COMPARE_LESS );
  }
  else if( first_mft_entry_index > second_mft_entry_index )
  {
    return( LIBCDATA_COMPARE_GREATER );
  }
  first_sequence_number  = (uint16_t) ( first_path_hint->file_reference >> 48 );
  second_sequence_number = (uint16_t) ( second_path_hint->file_reference >> 48 );

  if( first_sequence_number < second_sequence_number )
  {
    return( LIBCDATA_COMPARE_LESS );
  }
  else if( first_sequence_number > second_sequence_number )
  {
    return( LIBCDATA_COMPARE_GREATER );
  }
  return( LIBCDATA_COMPARE_EQUAL );
}

/* Retrieves the size of the UTF-8 encoded path
 * The returned size includes the end of string character
 * Returns 1 if successful or -1 on error
 */
int libfsntfs_path_hint_get_utf8_path_size(
     libfsntfs_path_hint_t *path_hint,
     size_t *utf8_string_size,
     libcerror_error_t **error )
{
  static char *function = "libfsntfs_path_hint_get_utf8_path_size";

  if( path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid file path values.",
     function );

    return( -1 );
  }
  if( libuna_utf8_string_size_from_utf8_stream(
       path_hint->path,
       path_hint->path_size,
       utf8_string_size,
       error ) != 1 )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_RUNTIME,
     LIBCERROR_RUNTIME_ERROR_GET_FAILED,
     "%s: unable to retrieve UTF-8 string size.",
     function );

    return( -1 );
  }
  return( 1 );
}

/* Retrieves the UTF-8 encoded path
 * The size should include the end of string character
 * Returns 1 if successful or -1 on error
 */
int libfsntfs_path_hint_get_utf8_path(
     libfsntfs_path_hint_t *path_hint,
     uint8_t *utf8_string,
     size_t utf8_string_size,
     libcerror_error_t **error )
{
  static char *function = "libfsntfs_path_hint_get_utf8_path";

  if( path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid file path values.",
     function );

    return( -1 );
  }
  if( libuna_utf8_string_copy_from_utf8_stream(
       utf8_string,
       utf8_string_size,
       path_hint->path,
       path_hint->path_size,
       error ) != 1 )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_RUNTIME,
     LIBCERROR_RUNTIME_ERROR_GET_FAILED,
     "%s: unable to retrieve UTF-8 string.",
     function );

    return( -1 );
  }
  return( 1 );
}

/* Retrieves the size of the UTF-16 encoded path
 * The returned size includes the end of string character
 * Returns 1 if successful or -1 on error
 */
int libfsntfs_path_hint_get_utf16_path_size(
     libfsntfs_path_hint_t *path_hint,
     size_t *utf16_string_size,
     libcerror_error_t **error )
{
  static char *function = "libfsntfs_path_hint_get_utf16_path_size";

  if( path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid file path values.",
     function );

    return( -1 );
  }
  if( libuna_utf16_string_size_from_utf8_stream(
       path_hint->path,
       path_hint->path_size,
       utf16_string_size,
       error ) != 1 )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_RUNTIME,
     LIBCERROR_RUNTIME_ERROR_GET_FAILED,
     "%s: unable to retrieve UTF-16 string size.",
     function );

    return( -1 );
  }
  return( 1 );
}

/* Retrieves the UTF-16 encoded path
 * The size should include the end of string character
 * Returns 1 if successful or -1 on error
 */
int libfsntfs_path_hint_get_utf16_path(
     libfsntfs_path_hint_t *path_hint,
     uint16_t *utf16_string,
     size_t utf16_string_size,
     libcerror_error_t **error )
{
  static char *function = "libfsntfs_path_hint_get_utf16_path";

  if( path_hint == NULL )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
     LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
     "%s: invalid file path values.",
     function );

    return( -1 );
  }
  if( libuna_utf16_string_copy_from_utf8_stream(
       utf16_string,
       utf16_string_size,
       path_hint->path,
       path_hint->path_size,
       error ) != 1 )
  {
    libcerror_error_set(
     error,
     LIBCERROR_ERROR_DOMAIN_RUNTIME,
     LIBCERROR_RUNTIME_ERROR_GET_FAILED,
     "%s: unable to retrieve UTF-16 string.",
     function );

    return( -1 );
  }
  return( 1 );
}


Coverage Report

Created: 2026-02-19 06:51

Line	Count	Source
1		/*
2		* Path hint functions
3		*
4		* Copyright (C) 2010-2026, Joachim Metz <joachim.metz@gmail.com>
5		*
6		* Refer to AUTHORS for acknowledgements.
7		*
8		* This program is free software: you can redistribute it and/or modify
9		* it under the terms of the GNU Lesser General Public License as published by
10		* the Free Software Foundation, either version 3 of the License, or
11		* (at your option) any later version.
12		*
13		* This program is distributed in the hope that it will be useful,
14		* but WITHOUT ANY WARRANTY; without even the implied warranty of
15		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16		* GNU General Public License for more details.
17		*
18		* You should have received a copy of the GNU Lesser General Public License
19		* along with this program. If not, see <https://www.gnu.org/licenses/>.
20		*/
21
22		#include <common.h>
23		#include <memory.h>
24		#include <types.h>
25
26		#include "libfsntfs_libcdata.h"
27		#include "libfsntfs_libcerror.h"
28		#include "libfsntfs_libuna.h"
29		#include "libfsntfs_path_hint.h"
30
31		/* Creates a path hint
32		* Make sure the value path_hint is referencing, is set to NULL
33		* Returns 1 if successful or -1 on error
34		*/
35		int libfsntfs_path_hint_initialize(
36		libfsntfs_path_hint_t **path_hint,
37		libcerror_error_t **error )
38	0	{
39	0	static char *function = "libfsntfs_path_hint_initialize";
40
41	0	if( path_hint == NULL )
42	0	{
43	0	libcerror_error_set(
44	0	error,
45	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
46	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
47	0	"%s: invalid path hint.",
48	0	function );
49
50	0	return( -1 );
51	0	}
52	0	if( *path_hint != NULL )
53	0	{
54	0	libcerror_error_set(
55	0	error,
56	0	LIBCERROR_ERROR_DOMAIN_RUNTIME,
57	0	LIBCERROR_RUNTIME_ERROR_VALUE_ALREADY_SET,
58	0	"%s: invalid path hint value already set.",
59	0	function );
60
61	0	return( -1 );
62	0	}
63	0	*path_hint = memory_allocate_structure(
64	0	libfsntfs_path_hint_t );
65
66	0	if( *path_hint == NULL )
67	0	{
68	0	libcerror_error_set(
69	0	error,
70	0	LIBCERROR_ERROR_DOMAIN_MEMORY,
71	0	LIBCERROR_MEMORY_ERROR_INSUFFICIENT,
72	0	"%s: unable to create path hint.",
73	0	function );
74
75	0	goto on_error;
76	0	}
77	0	if( memory_set(
78	0	*path_hint,
79	0	0,
80	0	sizeof( libfsntfs_path_hint_t ) ) == NULL )
81	0	{
82	0	libcerror_error_set(
83	0	error,
84	0	LIBCERROR_ERROR_DOMAIN_MEMORY,
85	0	LIBCERROR_MEMORY_ERROR_SET_FAILED,
86	0	"%s: unable to clear path hint.",
87	0	function );
88
89	0	goto on_error;
90	0	}
91	0	return( 1 );
92
93	0	on_error:
94	0	if( *path_hint != NULL )
95	0	{
96	0	memory_free(
97	0	*path_hint );
98
99	0	*path_hint = NULL;
100	0	}
101	0	return( -1 );
102	0	}
103
104		/* Frees a path hint
105		* Returns 1 if successful or -1 on error
106		*/
107		int libfsntfs_path_hint_free(
108		libfsntfs_path_hint_t **path_hint,
109		libcerror_error_t **error )
110	0	{
111	0	static char *function = "libfsntfs_path_hint_free";
112
113	0	if( path_hint == NULL )
114	0	{
115	0	libcerror_error_set(
116	0	error,
117	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
118	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
119	0	"%s: invalid path hint.",
120	0	function );
121
122	0	return( -1 );
123	0	}
124	0	if( *path_hint != NULL )
125	0	{
126	0	if( ( *path_hint )->path != NULL )
127	0	{
128	0	memory_free(
129	0	( *path_hint )->path );
130	0	}
131	0	memory_free(
132	0	*path_hint );
133
134	0	*path_hint = NULL;
135	0	}
136	0	return( 1 );
137	0	}
138
139		/* Compares 2 path hints by file reference
140		* Returns LIBCDATA_COMPARE_LESS, LIBCDATA_COMPARE_EQUAL, LIBCDATA_COMPARE_GREATER if successful or -1 on error
141		*/
142		int libfsntfs_path_hint_compare_by_file_reference(
143		libfsntfs_path_hint_t *first_path_hint,
144		libfsntfs_path_hint_t *second_path_hint,
145		libcerror_error_t **error )
146	0	{
147	0	static char *function = "libfsntfs_path_hint_compare_by_file_reference";
148	0	uint64_t first_mft_entry_index = 0;
149	0	uint64_t second_mft_entry_index = 0;
150	0	uint16_t first_sequence_number = 0;
151	0	uint16_t second_sequence_number = 0;
152
153	0	if( first_path_hint == NULL )
154	0	{
155	0	libcerror_error_set(
156	0	error,
157	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
158	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
159	0	"%s: invalid first path hint.",
160	0	function );
161
162	0	return( -1 );
163	0	}
164	0	if( second_path_hint == NULL )
165	0	{
166	0	libcerror_error_set(
167	0	error,
168	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
169	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
170	0	"%s: invalid second path hint.",
171	0	function );
172
173	0	return( -1 );
174	0	}
175	0	first_mft_entry_index = first_path_hint->file_reference & 0xffffffffffffUL;
176	0	second_mft_entry_index = second_path_hint->file_reference & 0xffffffffffffUL;
177
178	0	if( first_mft_entry_index < second_mft_entry_index )
179	0	{
180	0	return( LIBCDATA_COMPARE_LESS );
181	0	}
182	0	else if( first_mft_entry_index > second_mft_entry_index )
183	0	{
184	0	return( LIBCDATA_COMPARE_GREATER );
185	0	}
186	0	first_sequence_number = (uint16_t) ( first_path_hint->file_reference >> 48 );
187	0	second_sequence_number = (uint16_t) ( second_path_hint->file_reference >> 48 );
188
189	0	if( first_sequence_number < second_sequence_number )
190	0	{
191	0	return( LIBCDATA_COMPARE_LESS );
192	0	}
193	0	else if( first_sequence_number > second_sequence_number )
194	0	{
195	0	return( LIBCDATA_COMPARE_GREATER );
196	0	}
197	0	return( LIBCDATA_COMPARE_EQUAL );
198	0	}
199
200		/* Retrieves the size of the UTF-8 encoded path
201		* The returned size includes the end of string character
202		* Returns 1 if successful or -1 on error
203		*/
204		int libfsntfs_path_hint_get_utf8_path_size(
205		libfsntfs_path_hint_t *path_hint,
206		size_t *utf8_string_size,
207		libcerror_error_t **error )
208	0	{
209	0	static char *function = "libfsntfs_path_hint_get_utf8_path_size";
210
211	0	if( path_hint == NULL )
212	0	{
213	0	libcerror_error_set(
214	0	error,
215	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
216	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
217	0	"%s: invalid file path values.",
218	0	function );
219
220	0	return( -1 );
221	0	}
222	0	if( libuna_utf8_string_size_from_utf8_stream(
223	0	path_hint->path,
224	0	path_hint->path_size,
225	0	utf8_string_size,
226	0	error ) != 1 )
227	0	{
228	0	libcerror_error_set(
229	0	error,
230	0	LIBCERROR_ERROR_DOMAIN_RUNTIME,
231	0	LIBCERROR_RUNTIME_ERROR_GET_FAILED,
232	0	"%s: unable to retrieve UTF-8 string size.",
233	0	function );
234
235	0	return( -1 );
236	0	}
237	0	return( 1 );
238	0	}
239
240		/* Retrieves the UTF-8 encoded path
241		* The size should include the end of string character
242		* Returns 1 if successful or -1 on error
243		*/
244		int libfsntfs_path_hint_get_utf8_path(
245		libfsntfs_path_hint_t *path_hint,
246		uint8_t *utf8_string,
247		size_t utf8_string_size,
248		libcerror_error_t **error )
249	0	{
250	0	static char *function = "libfsntfs_path_hint_get_utf8_path";
251
252	0	if( path_hint == NULL )
253	0	{
254	0	libcerror_error_set(
255	0	error,
256	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
257	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
258	0	"%s: invalid file path values.",
259	0	function );
260
261	0	return( -1 );
262	0	}
263	0	if( libuna_utf8_string_copy_from_utf8_stream(
264	0	utf8_string,
265	0	utf8_string_size,
266	0	path_hint->path,
267	0	path_hint->path_size,
268	0	error ) != 1 )
269	0	{
270	0	libcerror_error_set(
271	0	error,
272	0	LIBCERROR_ERROR_DOMAIN_RUNTIME,
273	0	LIBCERROR_RUNTIME_ERROR_GET_FAILED,
274	0	"%s: unable to retrieve UTF-8 string.",
275	0	function );
276
277	0	return( -1 );
278	0	}
279	0	return( 1 );
280	0	}
281
282		/* Retrieves the size of the UTF-16 encoded path
283		* The returned size includes the end of string character
284		* Returns 1 if successful or -1 on error
285		*/
286		int libfsntfs_path_hint_get_utf16_path_size(
287		libfsntfs_path_hint_t *path_hint,
288		size_t *utf16_string_size,
289		libcerror_error_t **error )
290	0	{
291	0	static char *function = "libfsntfs_path_hint_get_utf16_path_size";
292
293	0	if( path_hint == NULL )
294	0	{
295	0	libcerror_error_set(
296	0	error,
297	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
298	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
299	0	"%s: invalid file path values.",
300	0	function );
301
302	0	return( -1 );
303	0	}
304	0	if( libuna_utf16_string_size_from_utf8_stream(
305	0	path_hint->path,
306	0	path_hint->path_size,
307	0	utf16_string_size,
308	0	error ) != 1 )
309	0	{
310	0	libcerror_error_set(
311	0	error,
312	0	LIBCERROR_ERROR_DOMAIN_RUNTIME,
313	0	LIBCERROR_RUNTIME_ERROR_GET_FAILED,
314	0	"%s: unable to retrieve UTF-16 string size.",
315	0	function );
316
317	0	return( -1 );
318	0	}
319	0	return( 1 );
320	0	}
321
322		/* Retrieves the UTF-16 encoded path
323		* The size should include the end of string character
324		* Returns 1 if successful or -1 on error
325		*/
326		int libfsntfs_path_hint_get_utf16_path(
327		libfsntfs_path_hint_t *path_hint,
328		uint16_t *utf16_string,
329		size_t utf16_string_size,
330		libcerror_error_t **error )
331	0	{
332	0	static char *function = "libfsntfs_path_hint_get_utf16_path";
333
334	0	if( path_hint == NULL )
335	0	{
336	0	libcerror_error_set(
337	0	error,
338	0	LIBCERROR_ERROR_DOMAIN_ARGUMENTS,
339	0	LIBCERROR_ARGUMENT_ERROR_INVALID_VALUE,
340	0	"%s: invalid file path values.",
341	0	function );
342
343	0	return( -1 );
344	0	}
345	0	if( libuna_utf16_string_copy_from_utf8_stream(
346	0	utf16_string,
347	0	utf16_string_size,
348	0	path_hint->path,
349	0	path_hint->path_size,
350	0	error ) != 1 )
351	0	{
352	0	libcerror_error_set(
353	0	error,
354	0	LIBCERROR_ERROR_DOMAIN_RUNTIME,
355	0	LIBCERROR_RUNTIME_ERROR_GET_FAILED,
356	0	"%s: unable to retrieve UTF-16 string.",
357	0	function );
358
359	0	return( -1 );
360	0	}
361	0	return( 1 );
362	0	}
363