New suggestions result

[yaz-moved-to-github.git] / include / yaz / tpath.h

diff --git a/include/yaz/tpath.h b/include/yaz/tpath.h
index cda60cb..b135ce4 100644 (file)
--- a/include/yaz/tpath.h
+++ b/include/yaz/tpath.h
@@ -1,5 +1,5 @@
-/*
- * Copyright (c) 1995-2006, Index Data
+/* This file is part of the YAZ toolkit.
+ * Copyright (C) 1995-2011 Index Data.
  * All rights reserved.
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
@@ -24,7 +24,6 @@
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/* $Id: tpath.h,v 1.12 2006-10-09 21:02:41 adam Exp $ */
 
 /**
  * \file tpath.h
@@ -41,20 +40,33 @@ YAZ_BEGIN_CDECL
 
 /** \brief checks whether path is absolute
     \param path path to checked
-
-    Returns 1 if path is absolute, 0 if relative
+    \retval 1 path is absolute
+    \retval 0 path is relative
+*/
+YAZ_EXPORT int yaz_is_abspath(const char *path);
+
+/** \brief get next path component in filepath
+    \param path_p pointer to path (updated to "next" entry if any)
+    \param comp upon pointer to component (if component is found)
+    \retval 0 no component found (and no more componennts)
+    \retval >0 length of component (length of *comp)
+    
+    A filepath has components separted by colon. For example
+    /usr/lib/modules:c:/my:/:lib
+    which has these components
+    "/usr/lib/modules", "c:/my", "/", "lib"
 */
-YAZ_EXPORT int yaz_is_abspath (const char *path);
+YAZ_EXPORT size_t yaz_filepath_comp(const char **path_p, const char **comp);
+
 
 /** \brief resolve file on path 
     \param fname "short" filename (without path)
     \param path the path (dir1:dir2,..) - ala Unix
     \param base can be added to relative paths (NULL for no append)
-    \param fullpath the full path to filename (if succesful)
+    \param fullpath the full path to filename (if successful)
+    \returns fullpath or NULL if file could not be found
 
-    Returns 0/NULL if no fname could be found in path; 
-    pointer to fullpath if fname could be found.
-    We assume fullpath is 1024 bytes in length!
+    Be sure to allocate at least 1024 bytes for fullpath
 */
 YAZ_EXPORT char *yaz_filepath_resolve(const char *fname, const char *path,
                                       const char *base, char *fullpath);
@@ -65,9 +77,7 @@ YAZ_EXPORT char *yaz_filepath_resolve(const char *fname, const char *path,
     \param mode mode as in fopen(3)
     \param path the path (dir1:dir2,..) - ala Unix
     \param base can be added to relative paths (NULL for no append)
-
-    Returns 0/NULL if no fname could be found in path; 
-    FILE pointer if fname could be found.
+    \returns FILE pointer if fname could be found; NULL otherwise
 */
 YAZ_EXPORT FILE *yaz_fopen(const char *path, const char *fname,
                            const char *mode, const char *base);
@@ -76,9 +86,7 @@ YAZ_EXPORT FILE *yaz_fopen(const char *path, const char *fname,
     \param fname "short" filename (without path)
     \param mode mode as in fopen(3)
     \param path the path (dir1:dir2,..) - ala Unix
-
-    Returns 0/NULL if no fname could be found in path; 
-    FILE pointer if fname could be found.
+    \returns FILE pointer if fname could be found; NULL otherwise
 */
 YAZ_EXPORT FILE *yaz_path_fopen(const char *path, const char *fname,
                                 const char *mode);
@@ -86,7 +94,8 @@ YAZ_EXPORT FILE *yaz_path_fopen(const char *path, const char *fname,
 /** \brief closes file
     \param f FILE handle
 
-    Returns -1 on failure; 0 on success
+    \retval -1 on failure
+    \retval 0 on success
 */
 YAZ_EXPORT int yaz_fclose(FILE *f);
 
@@ -97,6 +106,7 @@ YAZ_END_CDECL
 /*
  * Local variables:
  * c-basic-offset: 4
+ * c-file-style: "Stroustrup"
  * indent-tabs-mode: nil
  * End:
  * vim: shiftwidth=4 tabstop=8 expandtab