Mercurial > irccd

comparison man/irccd-api-file.3 @ 932:0e11221c9bcc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
man: split irccd-api into individual ones
author David Demelier <markand@malikania.fr>
date Tue, 05 Jan 2021 22:25:47 +0100
parents
children 2a6d753f79f6
comparison
equal deleted inserted replaced
931:c78ad0799e68 932:0e11221c9bcc
1 .\"
2 .\" Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
3 .\"
4 .\" Permission to use, copy, modify, and/or distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd @IRCCD_MAN_DATE@
17 .Dt IRCCD-API-FILE 3
18 .Os
19 .\" NAME
20 .Sh NAME
21 .Nm Irccd.File
22 .Nd file I/O API
23 .\" SYNOPSIS
24 .Sh SYNOPSIS
25 .Vt Irccd.File.SeekCur
26 .Vt Irccd.File.SeekEnd
27 .Vt Irccd.File.SeekSet
28 .Fn Irccd.File.basename "path"
29 .Fn Irccd.File.dirname "path"
30 .Fn Irccd.File.exists "path"
31 .Fn Irccd.File.remove "path"
32 .Fn Irccd.File.stat "path"
33 .Fn Irccd.File "path, mode"
34 .Fn Irccd.File.prototype.basename
35 .Fn Irccd.File.prototype.close
36 .Fn Irccd.File.prototype.dirname
37 .Fn Irccd.File.prototype.lines
38 .Fn Irccd.File.prototype.read "amount = undefined"
39 .Fn Irccd.File.prototype.readline
40 .Fn Irccd.File.prototype.remove
41 .Fn Irccd.File.prototype.seek "type, amount"
42 .Fn Irccd.File.prototype.stat
43 .Fn Irccd.File.prototype.tell
44 .Fn Irccd.File.prototype.write "data"
45 .\" DESCRIPTION
46 .Sh DESCRIPTION
47 This module provides routines for opening and writing files on the disk.
48 .Pp
49 For convenience, some functions are available as static functions and some as
50 object methods.
51 .\" CONSTANTS
52 .Sh CONSTANTS
53 The following constants properties are defined:
54 .Pp
55 .Bl -tag
56 .It Va Irccd.File.SeekCur No (int)
57 Seek from the current file position.
58 .It Va Irccd.File.SeekEnd No (int)
59 Seek from end of the file.
60 .It Va Irccd.File.SeekSet No (int)
61 Seek from beginning of the file.
62 .El
63 .\" METHODS
64 .Sh METHODS
65 .\" Irccd.File.basename
66 The
67 .Fn Irccd.File.basename
68 method returns the file basename from
69 .Fa path
70 as specified in
71 .Xr basename 3
72 POSIX function.
73 .Pp
74 .\" Irccd.File.dirname
75 The
76 .Fn Irccd.File.dirname
77 method returns the file directory name from
78 .Fa path
79 as specified in
80 .Xr dirname 3
81 POSIX function.
82 .Pp
83 .\" Irccd.File.exists
84 The
85 .Fn Irccd.File.exists
86 method checks if the file specified by
87 .Fa path
88 exists and returns true to indicate success. Warning: using this function is
89 usually discouraged as it may introduce a possible race condition.
90 .Pp
91 .\" Irccd.File.remove
92 The
93 .Fn Irccd.File.remove
94 method removes the file at the given
95 .Fa path .
96 .Pp
97 .\" Irccd.File.stat
98 The optional
99 .Fn Irccd.File.stat
100 method returns information from the file at the specified
101 .Fa path .
102 The returned object has the following properties. Not all properties are
103 available and you must check its presence before using it.
104 .Pp
105 .Bl -tag -width 20n -compact -offset Ds
106 .It Va atime No (int)
107 The last access time.
108 .It Va blksize No (int)
109 The block size.
110 .It Va blocks No (int)
111 The number of blocks.
112 .It Va ctime No (int)
113 The creation time.
114 .It Va dev No (int)
115 The device.
116 .It Va gid No (int)
117 The group numeric id.
118 .It Va ino No (int)
119 The inode.
120 .It Va mode No (int)
121 The mode.
122 .It Va mtime No (int)
123 The modification time.
124 .It Va nlink No (int)
125 The number of hard links.
126 .It Va rdev No (int)
127 No description available.
128 .It Va size No (int)
129 The file size.
130 .It Va uid No (int)
131 The user numeric id.
132 .El
133 .Pp
134 .\" Irccd.File
135 The
136 .Fn Irccd.File
137 function constructor opens a file specified by
138 .Fa path
139 with the specified
140 .Fa mode
141 similar to
142 .Xr fopen 3
143 C standard function.
144 .Pp
145 .\" Irccd.File.prototype.basename
146 The
147 .Fn Irccd.File.prototype.basename
148 method is the synonym of
149 .Fn Irccd.File.basename
150 method but the path is taken from the file object.
151 .Pp
152 .\" Irccd.File.prototype.close
153 The
154 .Fn Irccd.File.prototype.close
155 method closes the file. It is usually not required as already closed in the
156 destructor.
157 .Pp
158 .\" Irccd.File.prototype.dirname
159 The
160 .Fn Irccd.File.prototype.dirname
161 method is the synonym of
162 .Fn Irccd.File.dirname
163 method but the path is taken from the file object.
164 .Pp
165 .\" Irccd.File.prototype.lines
166 The
167 .Fn Irccd.File.prototype.lines
168 method reads all lines and return an array.
169 .Pp
170 .\" Irccd.File.prototype.read
171 The
172 .Fn Irccd.File.prototype.read
173 method reads the specified
174 .Fa amount
175 of characters or the whole file if undefined.
176 .Pp
177 .\" Irccd.File.prototype.readline
178 The
179 .Fn Irccd.File.prototype.readline
180 method reads the next line available and returns it. If EOF was reached,
181 returns undefined. Warning: this method is slow and its usage is discouraged on
182 large files. Consider using
183 .Fn Irccd.File.prototype.lines
184 function if you want to read a file line per line.
185 .Pp
186 .\" Irccd.File.prototype.remove
187 The
188 .Fn Irccd.File.prototype.remove
189 method is the synonym of
190 .Fn Irccd.File.remove
191 method but the path is taken from the file object.
192 .Pp
193 .\" Irccd.File.prototype.seek
194 The
195 .Fn Irccd.File.prototype.seek
196 method sets the position in the file to the position
197 .Fa amount .
198 The type argument must be one of
199 .Vt Irccd.File.SeekCur , Irccd.File.SeekEnd
200 or
201 .Vt Irccd.File.SeekSet .
202 .Pp
203 .\" Irccd.File.prototype.stat
204 The optional
205 .Fn Irccd.File.prototype.stat
206 method is the synonym of
207 .Fn Irccd.File.stat
208 method but the path is taken from the file object.
209 .Pp
210 .\" Irccd.File.prototype.tell
211 The
212 .Fn Irccd.File.prototype.tell
213 methods returns the current position in the file.
214 .Pp
215 .\" Irccd.File.prototype.write
216 The
217 .Fn Irccd.File.prototype.write
218 method writes the string
219 .Fa data
220 to the file.
221 .Pp
222 .\" EXCEPTIONS
223 .Sh EXCEPTIONS
224 .Bl -tag -width 20n
225 .It Bq Er Irccd.SystemError
226 On I/O errors.
227 .It Bq Er Error
228 On other errors.
229 .El
230 .\" SEE ALSO
231 .Sh SEE ALSO
232 .Xr irccd-api 3