Changeset 35277 in project


Ignore:
Timestamp:
03/11/18 12:28:38 (6 months ago)
Author:
sjamaan
Message:

man/5: Move some procedures from Module (chicken file) to Module (chicken file posix)

Location:
wiki/man/5
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • wiki/man/5/Module (chicken file posix)

    r34291 r35277  
    110110but it simply won't have an effect.
    111111
    112 === File descriptors and low-level I/O
    113 
    114 ==== duplicate-fileno
    115 
    116 <procedure>(duplicate-fileno OLD [NEW])</procedure>
    117 
    118 If {{NEW}} is given, then the file-descriptor {{NEW}} is opened
    119 to access the file with the file-descriptor {{OLD}}. Otherwise a
    120 fresh file-descriptor accessing the same file as {{OLD}} is returned.
    121 
    122 ==== file-close
    123 
    124 <procedure>(file-close FILENO)</procedure>
    125 
    126 Closes the input/output file with the file-descriptor {{FILENO}}.
    127 
    128 ==== file-open
    129 
    130 <procedure>(file-open FILENAME FLAGS [MODE])</procedure>
    131 
    132 Opens the file specified with the string {{FILENAME}} and open-flags
    133 {{FLAGS}} using the C function {{open(2)}}. On success a
    134 file-descriptor for the opened file is returned.
    135 
    136 {{FLAGS}} is a bitmask of {{open/...}}
    137 values '''or'''ed together using {{bitwise-ior}} (or simply added
    138 together).  You must provide exactly one of the access flags {{open/rdonly}}, {{open/wronly}}, or {{open/rdwr}}.  Additionally, you may provide zero or more creation flags ({{open/creat}}, {{open/excl}}, {{open/trunc}}, and {{open/noctty}}) and status flags (the remaining {{open/...}} values).  For example, to open a possibly new output file for appending:
    139 
    140  (file-open "/tmp/hen.txt" (+ open/wronly open/append open/creat))
    141 
    142 The optional {{MODE}} should be a bitmask composed of one
    143 or more permission values like {{perm/irusr}} and is only relevant
    144 when a new file is created. The default mode is
    145 {{perm/irwxu | perm/irgrp | perm/iroth}}.
    146 
    147 ==== file-mkstemp
    148 
    149 <procedure>(file-mkstemp TEMPLATE-FILENAME)</procedure>
    150 
    151 Create a file based on the given {{TEMPLATE-FILENAME}}, in which
    152 the six last characters must be ''XXXXXX''.  These will be replaced
    153 with a string that makes the filename unique.  The file descriptor of
    154 the created file and the generated filename is returned.  See the
    155 {{mkstemp(3)}} manual page for details on how this function
    156 works.  The template string given is not modified.
    157 
    158 Example usage:
     112
     113=== Information about files
     114
     115==== directory?
     116
     117<procedure>(directory? FILE)</procedure>
     118
     119Returns {{#t}} if {{FILE}} designates a directory. Otherwise, it returns {{#f}}.
     120{{FILE}} may be a pathname, a file-descriptor or a port object.
     121
     122
     123==== file-type
     124
     125<procedure>(file-type FILE [LINK [ERROR]])</procedure>
     126
     127Returns the file-type for {{FILE}}, which should be a filename, a file-descriptor
     128or a port object. If {{LINK}} is given and true, symbolic-links are
     129not followed:
     130
     131  regular-file
     132  directory
     133  fifo
     134  socket
     135  symbolic-link
     136  character-device
     137  block-device
     138
     139Note that not all types are supported on every platform.
     140If {{ERROR}} is given and false, then {{file-type}} returns {{#f}} if the file does not exist;
     141otherwise, it signals an error.
     142
     143==== character-device?
     144==== block-device?
     145==== socket?
     146
     147<procedure>(character-device? FILE)</procedure><br>
     148<procedure>(block-device? FILE)</procedure><br>
     149<procedure>(socket? FILE)</procedure>
     150
     151These procedures return {{#t}} if {{FILE}} given is of the
     152appropriate type. {{FILE}} may be a filename, a file-descriptor or a port object.
     153Note that these operations follow symbolic links. If the file does
     154not exist, {{#f}} is returned.
     155
     156==== file-read-access?
     157==== file-write-access?
     158==== file-execute-access?
     159
     160<procedure>(file-read-access? FILENAME)</procedure><br>
     161<procedure>(file-write-access? FILENAME)</procedure><br>
     162<procedure>(file-execute-access? FILENAME)</procedure>
     163
     164These procedures return {{#t}} if the current user has read,
     165write or execute permissions on the file named {{FILENAME}}.
     166
     167==== regular-file?
     168
     169<procedure>(regular-file? FILE)</procedure>
     170
     171Returns true, if {{FILE}} names a regular file (not a directory, socket, etc.)  This operation follows symbolic links; use either {{symbolic-link?}} or {{file-type}} if you need to test for symlinks. {{FILE}} may refer to a filename, file descriptor or ports object.
     172
     173
     174=== Fifos
     175
     176==== create-fifo
     177
     178<procedure>(create-fifo FILENAME [MODE])</procedure>
     179
     180Creates a FIFO with the name {{FILENAME}} and the permission bits
     181{{MODE}}, which defaults to
    159182
    160183<enscript highlight=scheme>
    161  (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
    162   (let ((temp-port (open-output-file* fd)))
    163     (format temp-port "This file is ~A.~%" temp-path)
    164     (close-output-port temp-port)))
     184 (+ perm/irwxu perm/irwxg perm/irwxo)
    165185</enscript>
    166186
    167 ==== file-read
    168 
    169 <procedure>(file-read FILENO SIZE [BUFFER])</procedure>
    170 
    171 Reads {{SIZE}} bytes from the file with the file-descriptor
    172 {{FILENO}}.  If a string or bytevector is passed in the optional
    173 argument {{BUFFER}}, then this string will be destructively modified
    174 to contain the read data. This procedure returns a list with two values:
    175 the buffer containing the data and the number of bytes read.
    176 
    177 ==== file-select
    178 
    179 <procedure>(file-select READFDLIST WRITEFDLIST [TIMEOUT])</procedure>
    180 
    181 Waits until any of the file-descriptors given in the lists
    182 {{READFDLIST}} and {{WRITEFDLIST}} is ready for input or
    183 output, respectively. If the optional argument {{TIMEOUT}} is
    184 given and not false, then it should specify the number of seconds after
    185 which the wait is to be aborted (the value may be a floating point
    186 number). This procedure returns two values:
    187 the lists of file-descriptors ready for input and output, respectively.
    188 {{READFDLIST}} and '''WRITEFDLIST''' may also by file-descriptors
    189 instead of lists.  In this case the returned values are booleans
    190 indicating whether input/output is ready by {{#t}} or {{#f}}
    191 otherwise.  You can also pass {{#f}} as {{READFDLIST}} or
    192 {{WRITEFDLIST}} argument, which is equivalent to {{()}}.
    193 
    194 '''NOTE''': On native Windows builds (all except cygwin), this
    195 procedure is unimplemented and will raise an error.
    196 
    197 ==== file-write
    198 
    199 <procedure>(file-write FILENO BUFFER [SIZE])</procedure>
    200 
    201 Writes the contents of the string or bytevector {{BUFFER}} into
    202 the file with the file-descriptor {{FILENO}}. If the optional
    203 argument {{SIZE}} is given, then only the specified number of bytes
    204 are written.
    205 
    206 ==== file-control
    207 
    208 <procedure>(file-control FILENO COMMAND [ARGUMENT])</procedure>
    209 
    210 Performs the fcntl operation {{COMMAND}} with the given
    211 {{FILENO}} and optional {{ARGUMENT}}. The return value is
    212 meaningful depending on the {{COMMAND}}.
    213 
    214 '''NOTE''': On native Windows builds (all except cygwin), this
    215 procedure is unimplemented and will raise an error.
    216 
    217 ==== open-input-file*
    218 ==== open-output-file*
    219 
    220 <procedure>(open-input-file* FILENO [OPENMODE])</procedure><br>
    221 <procedure>(open-output-file* FILENO [OPENMODE])</procedure>
    222 
    223 Opens file for the file-descriptor {{FILENO}} for input or output
    224 and returns a port.  {{FILENO}} should be a positive exact integer.
    225 {{OPENMODE}} specifies an additional mode for opening the file
    226 (currently only the keyword {{#:append}} is supported, which opens
    227 an output-file for appending).
    228 
    229 ==== port->fileno
    230 
    231 <procedure>(port->fileno PORT)</procedure>
    232 
    233 If {{PORT}} is a file- or tcp-port, then a file-descriptor is returned for
    234 this port. Otherwise an error is signaled.
     187'''NOTE''': On native Windows builds (all except cygwin), this
     188procedure is unimplemented and will raise an error.
     189
     190==== fifo?
     191
     192<procedure>(fifo? FILE)</procedure>
     193
     194Returns {{#t}} if {{FILE}} names a FIFO. {{FILE}} may be a filename,
     195a port or a file-descriptor.
     196
     197'''NOTE''': On native Windows builds (all except cygwin), this
     198procedure is unimplemented and will raise an error.
    235199
    236200
     
    463427
    464428
    465 === Hard links
     429=== Hard and symbolic links
    466430
    467431==== file-link
     
    470434
    471435Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).
     436
     437
     438==== symbolic-link?
     439
     440<procedure>(symbolic-link? FILE)</procedure>
     441
     442Returns true, if {{FILE}} names a symbolic link. If no such file exists, {{#f}}
     443is returned.  This operation does not follow symbolic links itself.
     444{{FILE}} could be a filename, file descriptor or port object.
     445
     446==== create-symbolic-link
     447
     448<procedure>(create-symbolic-link OLDNAME NEWNAME)</procedure>
     449
     450Creates a symbolic link with the filename {{NEWNAME}} that points
     451to the file named {{OLDNAME}}.
     452
     453'''NOTE''': On native Windows builds (all except cygwin), this
     454procedure is unimplemented and will raise an error.
     455
     456==== read-symbolic-link
     457
     458<procedure>(read-symbolic-link FILENAME [CANONICALIZE])</procedure>
     459
     460Returns the filename to which the symbolic link {{FILENAME}} points.
     461If {{CANONICALIZE}} is given and true, then symbolic links are
     462resolved repeatedly until the result is not a link.
     463
     464'''NOTE''': On native Windows builds (all except cygwin), this
     465procedure is unimplemented and will raise an error.
     466
     467
     468=== File descriptors and low-level I/O
     469
     470==== duplicate-fileno
     471
     472<procedure>(duplicate-fileno OLD [NEW])</procedure>
     473
     474If {{NEW}} is given, then the file-descriptor {{NEW}} is opened
     475to access the file with the file-descriptor {{OLD}}. Otherwise a
     476fresh file-descriptor accessing the same file as {{OLD}} is returned.
     477
     478==== file-close
     479
     480<procedure>(file-close FILENO)</procedure>
     481
     482Closes the input/output file with the file-descriptor {{FILENO}}.
     483
     484==== file-open
     485
     486<procedure>(file-open FILENAME FLAGS [MODE])</procedure>
     487
     488Opens the file specified with the string {{FILENAME}} and open-flags
     489{{FLAGS}} using the C function {{open(2)}}. On success a
     490file-descriptor for the opened file is returned.
     491
     492{{FLAGS}} is a bitmask of {{open/...}}
     493values '''or'''ed together using {{bitwise-ior}} (or simply added
     494together).  You must provide exactly one of the access flags {{open/rdonly}}, {{open/wronly}}, or {{open/rdwr}}.  Additionally, you may provide zero or more creation flags ({{open/creat}}, {{open/excl}}, {{open/trunc}}, and {{open/noctty}}) and status flags (the remaining {{open/...}} values).  For example, to open a possibly new output file for appending:
     495
     496 (file-open "/tmp/hen.txt" (+ open/wronly open/append open/creat))
     497
     498The optional {{MODE}} should be a bitmask composed of one
     499or more permission values like {{perm/irusr}} and is only relevant
     500when a new file is created. The default mode is
     501{{perm/irwxu | perm/irgrp | perm/iroth}}.
     502
     503==== file-mkstemp
     504
     505<procedure>(file-mkstemp TEMPLATE-FILENAME)</procedure>
     506
     507Create a file based on the given {{TEMPLATE-FILENAME}}, in which
     508the six last characters must be ''XXXXXX''.  These will be replaced
     509with a string that makes the filename unique.  The file descriptor of
     510the created file and the generated filename is returned.  See the
     511{{mkstemp(3)}} manual page for details on how this function
     512works.  The template string given is not modified.
     513
     514Example usage:
     515
     516<enscript highlight=scheme>
     517 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
     518  (let ((temp-port (open-output-file* fd)))
     519    (format temp-port "This file is ~A.~%" temp-path)
     520    (close-output-port temp-port)))
     521</enscript>
     522
     523==== file-read
     524
     525<procedure>(file-read FILENO SIZE [BUFFER])</procedure>
     526
     527Reads {{SIZE}} bytes from the file with the file-descriptor
     528{{FILENO}}.  If a string or bytevector is passed in the optional
     529argument {{BUFFER}}, then this string will be destructively modified
     530to contain the read data. This procedure returns a list with two values:
     531the buffer containing the data and the number of bytes read.
     532
     533==== file-select
     534
     535<procedure>(file-select READFDLIST WRITEFDLIST [TIMEOUT])</procedure>
     536
     537Waits until any of the file-descriptors given in the lists
     538{{READFDLIST}} and {{WRITEFDLIST}} is ready for input or
     539output, respectively. If the optional argument {{TIMEOUT}} is
     540given and not false, then it should specify the number of seconds after
     541which the wait is to be aborted (the value may be a floating point
     542number). This procedure returns two values:
     543the lists of file-descriptors ready for input and output, respectively.
     544{{READFDLIST}} and '''WRITEFDLIST''' may also by file-descriptors
     545instead of lists.  In this case the returned values are booleans
     546indicating whether input/output is ready by {{#t}} or {{#f}}
     547otherwise.  You can also pass {{#f}} as {{READFDLIST}} or
     548{{WRITEFDLIST}} argument, which is equivalent to {{()}}.
     549
     550'''NOTE''': On native Windows builds (all except cygwin), this
     551procedure is unimplemented and will raise an error.
     552
     553==== file-write
     554
     555<procedure>(file-write FILENO BUFFER [SIZE])</procedure>
     556
     557Writes the contents of the string or bytevector {{BUFFER}} into
     558the file with the file-descriptor {{FILENO}}. If the optional
     559argument {{SIZE}} is given, then only the specified number of bytes
     560are written.
     561
     562==== file-control
     563
     564<procedure>(file-control FILENO COMMAND [ARGUMENT])</procedure>
     565
     566Performs the fcntl operation {{COMMAND}} with the given
     567{{FILENO}} and optional {{ARGUMENT}}. The return value is
     568meaningful depending on the {{COMMAND}}.
     569
     570'''NOTE''': On native Windows builds (all except cygwin), this
     571procedure is unimplemented and will raise an error.
     572
     573==== open-input-file*
     574==== open-output-file*
     575
     576<procedure>(open-input-file* FILENO [OPENMODE])</procedure><br>
     577<procedure>(open-output-file* FILENO [OPENMODE])</procedure>
     578
     579Opens file for the file-descriptor {{FILENO}} for input or output
     580and returns a port.  {{FILENO}} should be a positive exact integer.
     581{{OPENMODE}} specifies an additional mode for opening the file
     582(currently only the keyword {{#:append}} is supported, which opens
     583an output-file for appending).
     584
     585==== port->fileno
     586
     587<procedure>(port->fileno PORT)</procedure>
     588
     589If {{PORT}} is a file- or tcp-port, then a file-descriptor is returned for
     590this port. Otherwise an error is signaled.
    472591
    473592
  • wiki/man/5/Module (chicken file)

    r34271 r35277  
    2424that already exists).
    2525
    26 ==== file-copy
     26==== copy-file
    2727
    28 <procedure>(file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
     28<procedure>(copy-file ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
    2929
    30 Copies {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}}, 
    31 {{BLOCKSIZE}} bytes at a time.  {{BLOCKSIZE}} defaults to 1024, and must be
    32 a positive integer.  Returns the number of bytes copied on success, or errors
    33 on failure.  {{CLOBBER}} determines the behaviour of {{file-copy}} when
    34 {{NEWFILE}} is already extant.  When set to {{#f}} (default), an error is
    35 signalled.  When set to any other value, {{NEWFILE}} is overwritten.
    36 {{file-copy}} will work across filesystems and devices and is not
    37 platform-dependent.
     30Copies {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}},
     31{{BLOCKSIZE}} bytes at a time.  {{BLOCKSIZE}} defaults to 1024, and
     32must be a positive integer.  Returns the number of bytes copied on
     33success, or errors on failure.  {{CLOBBER}} determines the behaviour
     34of {{file-copy}} when {{NEWFILE}} is already extant.  When set to
     35{{#f}} (default), an error is signaled.  When set to any other value,
     36{{NEWFILE}} is overwritten.  {{file-copy}} will work across
     37filesystems and devices and is not platform-dependent.
    3838
    39 ==== file-move
     39==== move-file
    4040
    41 <procedure>(file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
     41<procedure>(move-file ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)</procedure>
    4242
    43 Moves {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}}, with
    44 the same semantics as {{file-copy}}, above.  {{file-move}} is safe across
    45 filesystems and devices (unlike {{rename-file}}).  It is possible for an
    46 error to be signalled despite partial success if {{NEWFILE}} could be created
    47 and fully written but removing {{ORIGFILE}} fails.
     43Moves {{ORIGFILE}} (a string denoting some filename) to {{NEWFILE}},
     44with the same semantics as {{copy-file}}, above.  {{move-file}} is
     45safe across filesystems and devices (unlike {{rename-file}}).  It is
     46possible for an error to be signaled despite partial success if
     47{{NEWFILE}} could be created and fully written but removing
     48{{ORIGFILE}} fails.
    4849
     50If {{CLOBBER}} is given and not {{#f}}, {{NEWFILE}} will be replaced
     51when it already exists, otherwise an error is signaled.
     52
     53The {{BLOCKSIZE}} argument indicates the block size to use when
     54copying the file a block at a time.  It must be a positive integer,
     55and it defaults to 1024.
    4956
    5057==== delete-file
     
    96103==== rename-file
    97104
    98 <procedure>(rename-file OLD NEW)</procedure>
     105<procedure>(rename-file OLD NEW #!optional CLOBBER)</procedure>
    99106
    100107Renames the file or directory with the pathname {{OLD}} to
    101108{{NEW}}. If the operation does not succeed, an error is signaled.
     109
     110If {{CLOBBER}} is given and not {{#f}}, {{NEW}} will be replaced when
     111it already exists, otherwise an error is signaled.
    102112
    103113
     
    124134environment variable {{TMPDIR, TEMP}} or {{TMP}} is set, then the
    125135temporary directory is created at that location.
    126 
    127 
    128 === Information about files
    129 
    130 ==== directory?
    131 
    132 <procedure>(directory? FILE)</procedure>
    133 
    134 Returns {{#t}} if {{FILE}} designates a directory. Otherwise, it returns {{#f}}.
    135 {{FILE}} may be a pathname, a file-descriptor or a port object.
    136 
    137 
    138 ==== file-type
    139 
    140 <procedure>(file-type FILE [LINK [ERROR]])</procedure>
    141 
    142 Returns the file-type for {{FILE}}, which should be a filename, a file-descriptor
    143 or a port object. If {{LINK}} is given and true, symbolic-links are
    144 not followed:
    145 
    146   regular-file
    147   directory
    148   fifo
    149   socket
    150   symbolic-link
    151   character-device
    152   block-device
    153 
    154 Note that not all types are supported on every platform.
    155 If {{ERROR}} is given and false, then {{file-type}} returns {{#f}} if the file does not exist;
    156 otherwise, it signals an error.
    157 
    158 ==== character-device?
    159 ==== block-device?
    160 ==== socket?
    161 
    162 <procedure>(character-device? FILE)</procedure><br>
    163 <procedure>(block-device? FILE)</procedure><br>
    164 <procedure>(socket? FILE)</procedure>
    165 
    166 These procedures return {{#t}} if {{FILE}} given is of the
    167 appropriate type. {{FILE}} may be a filename, a file-descriptor or a port object.
    168 Note that these operations follow symbolic links. If the file does
    169 not exist, {{#f}} is returned.
    170 
    171 ==== file-read-access?
    172 ==== file-write-access?
    173 ==== file-execute-access?
    174 
    175 <procedure>(file-read-access? FILENAME)</procedure><br>
    176 <procedure>(file-write-access? FILENAME)</procedure><br>
    177 <procedure>(file-execute-access? FILENAME)</procedure>
    178 
    179 These procedures return {{#t}} if the current user has read,
    180 write or execute permissions on the file named {{FILENAME}}.
    181 
    182 ==== regular-file?
    183 
    184 <procedure>(regular-file? FILE)</procedure>
    185 
    186 Returns true, if {{FILE}} names a regular file (not a directory, socket, etc.)  This operation follows symbolic links; use either {{symbolic-link?}} or {{file-type}} if you need to test for symlinks. {{FILE}} may refer to a filename, file descriptor or ports object.
    187136
    188137
     
    237186{{?}} matching zero or one character).
    238187
    239 
    240 === Fifos
    241 
    242 ==== create-fifo
    243 
    244 <procedure>(create-fifo FILENAME [MODE])</procedure>
    245 
    246 Creates a FIFO with the name {{FILENAME}} and the permission bits
    247 {{MODE}}, which defaults to
    248 
    249 <enscript highlight=scheme>
    250  (+ perm/irwxu perm/irwxg perm/irwxo)
    251 </enscript>
    252 
    253 '''NOTE''': On native Windows builds (all except cygwin), this
    254 procedure is unimplemented and will raise an error.
    255 
    256 ==== fifo?
    257 
    258 <procedure>(fifo? FILE)</procedure>
    259 
    260 Returns {{#t}} if {{FILE}} names a FIFO. {{FILE}} may be a filename,
    261 a port or a file-descriptor.
    262 
    263 '''NOTE''': On native Windows builds (all except cygwin), this
    264 procedure is unimplemented and will raise an error.
    265 
    266 
    267 === Symbolic links
    268 
    269 ==== symbolic-link?
    270 
    271 <procedure>(symbolic-link? FILE)</procedure>
    272 
    273 Returns true, if {{FILE}} names a symbolic link. If no such file exists, {{#f}}
    274 is returned.  This operation does not follow symbolic links itself.
    275 {{FILE}} could be a filename, file descriptor or port object.
    276 
    277 ==== create-symbolic-link
    278 
    279 <procedure>(create-symbolic-link OLDNAME NEWNAME)</procedure>
    280 
    281 Creates a symbolic link with the filename {{NEWNAME}} that points
    282 to the file named {{OLDNAME}}.
    283 
    284 '''NOTE''': On native Windows builds (all except cygwin), this
    285 procedure is unimplemented and will raise an error.
    286 
    287 ==== read-symbolic-link
    288 
    289 <procedure>(read-symbolic-link FILENAME [CANONICALIZE])</procedure>
    290 
    291 Returns the filename to which the symbolic link {{FILENAME}} points.
    292 If {{CANONICALIZE}} is given and true, then symbolic links are
    293 resolved repeatedly until the result is not a link.
    294 
    295 '''NOTE''': On native Windows builds (all except cygwin), this
    296 procedure is unimplemented and will raise an error.
    297 
    298188---
    299189Previous: [[Module (chicken eval)]]
Note: See TracChangeset for help on using the changeset viewer.