1 #ifndef VIENNA_RNA_PACKAGE_FILE_UTILS_H
2 #define VIENNA_RNA_PACKAGE_FILE_UTILS_H
3 
4 /**
5  *  @file     ViennaRNA/io/utils.h
6  *  @ingroup  utils, file_utils
7  *  @brief    Several utilities for file handling
8  */
9 
10 #include <stdio.h>
11 
12 /**
13  *  @addtogroup file_utils
14  *  @{
15  *  @brief      Functions to parse, write, and convert various file formats and to deal with file system related issues
16  */
17 
18 /**
19  *  @brief Inefficient `cp'
20  */
21 void vrna_file_copy(FILE  *from,
22                     FILE  *to);
23 
24 
25 /**
26  *  @brief Read a line of arbitrary length from a stream
27  *
28  *  Returns a pointer to the resulting string. The necessary memory is
29  *  allocated and should be released using @e free() when the string is
30  *  no longer needed.
31  *
32  *  @param  fp  A file pointer to the stream where the function should read from
33  *  @return     A pointer to the resulting string
34  */
35 char *vrna_read_line(FILE *fp);
36 
37 
38 /**
39  *  @brief  Recursivly create a directory tree
40  */
41 int vrna_mkdir_p(const char *path);
42 
43 
44 /**
45  *  @brief  Extract the filename from a file path
46  */
47 char *vrna_basename(const char *path);
48 
49 
50 /**
51  *  @brief  Extract the directory part of a file path
52  */
53 char *vrna_dirname(const char *path);
54 
55 
56 /**
57  *  @brief  Sanitize a file name
58  *
59  *  Returns a new file name where all invalid characters are
60  *  substituted by a replacement character. If no replacement
61  *  character is supplied, invalid characters are simply removed
62  *  from the filename. File names may also never exceed a length
63  *  of 255 characters. Longer file names will undergo a 'smart'
64  *  truncation process, where the filenames` suffix, i.e. everything
65  *  after the last dot '.', is attempted to be kept intact. Hence,
66  *  only the filename part before the suffix is reduced in such a
67  *  way that the total filename complies to the length restriction
68  *  of 255 characters. If no suffix is present or the suffix itself
69  *  already exceeds the maximum length, the filename is simply
70  *  truncated from the back of the string.
71  *
72  *  For now we consider the following characters invalid:
73  *  - backslash '\'
74  *  - slash '/'
75  *  - question mark '?'
76  *  - percent sign '%'
77  *  - asterisk '*'
78  *  - colon ':'
79  *  - pipe symbol '|'
80  *  - double quote '"'
81  *  - triangular brackets '<' and '>'
82  *
83  *  Furthermore, the (resulting) file name must not be a reserved
84  *  file name, such as:
85  *  - '.'
86  *  - '..'
87  *
88  *  @note This function allocates a new block of memory for the
89  *        sanitized string. It also may return (a) NULL if the input
90  *        is pointing to NULL, or (b) an empty string if the input
91  *        only consists of invalid characters which are simply removed!
92  *
93  *  @param  name        The input file name
94  *  @param  replacement The replacement character, or NULL
95  *  @return             The sanitized file name, or NULL
96  */
97 char *vrna_filename_sanitize(const char *name,
98                              const char *replacement);
99 
100 
101 /**
102  *  @brief  Check if a file already exists in the file system
103  *
104  *  @param  filename  The name of (path to) the file to check for existence
105  *  @return           0 if it doesn't exists, 1 otherwise
106  */
107 int
108 vrna_file_exists(const char *filename);
109 
110 
111 /**
112  *  @}
113  */
114 
115 #endif
116