source: project/chicken/trunk/manual/Unit posix @ 14554

Last change on this file since 14554 was 14554, checked in by felix winkelmann, 11 years ago

fixed bug #16 (setter for file-position accepts list, now)

File size: 41.2 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit posix
5
6This unit provides services as used on many UNIX-like systems.  Note that
7the following definitions are not all available on non-UNIX systems like
8Windows. See below for Windows specific notes.
9
10This unit uses the {{regex}}, {{scheduler}}, {{extras}} and {{utils}} units.
11
12All errors related to failing file-operations will signal a condition
13of kind {{(exn i/o file)}}.
14
15
16=== Constants
17
18==== File-control Commands
19
20===== fcntl/dupfd
21===== fcntl/getfd
22===== fcntl/setfd
23===== fcntl/getfl
24===== fcntl/setfl
25
26==== Standard I/O file-descriptors
27
28===== fileno/stdin
29===== fileno/stdout
30===== fileno/stderr
31
32==== Open flags
33
34===== open/rdonly
35===== open/wronly
36===== open/rdwr
37===== open/read
38===== open/write
39===== open/creat
40===== open/append
41===== open/excl
42===== open/noctty
43===== open/nonblock
44===== open/trunc
45===== open/sync
46===== open/fsync
47===== open/binary
48===== open/text
49
50==== Permission bits
51
52===== perm/irusr
53===== perm/iwusr
54===== perm/ixusr
55===== perm/irgrp
56===== perm/iwgrp
57===== perm/ixgrp
58===== perm/iroth
59===== perm/iwoth
60===== perm/ixoth
61===== perm/irwxu
62===== perm/irwxg
63===== perm/irwxo
64===== perm/isvtx
65===== perm/isuid
66===== perm/isgid
67
68
69=== Directories
70
71==== change-directory
72
73<procedure>(change-directory NAME)</procedure>
74
75Changes the current working directory to {{NAME}}.
76
77==== current-directory
78
79<procedure>(current-directory [DIR])</procedure>
80
81Returns the name of the current working directory. If the optional argument {{DIR}} is given,
82then {{(current-directory DIR)}} is equivalent to {{(change-directory DIR)}}.
83
84==== create-directory
85
86<procedure>(create-directory NAME #!optional PARENTS?)</procedure>
87
88Creates a directory with the pathname {{NAME}}.  If the {{PARENTS?}} argument
89is given and not false, any nonextant parent directories are also created.
90
91==== delete-directory
92
93<procedure>(delete-directory NAME)</procedure>
94
95Deletes the directory with the pathname {{NAME}}. The directory has
96to be empty.
97
98==== directory
99
100<procedure>(directory [PATHNAME [SHOW-DOTFILES?]])</procedure>
101
102Returns a list with all files that are contained in the directory with the name {{PATHNAME}}
103(which defaults to the value of {{(current-directory)}}).
104Files beginning with {{.}} are included only if {{SHOW-DOTFILES?}} is given and not {{#f}}.
105
106==== directory?
107
108<procedure>(directory? NAME)</procedure>
109
110Returns {{#t}} if there exists a file with the name {{NAME}}
111and if that file is a directory, or {{#f}} otherwise.
112
113==== glob
114
115<procedure>(glob PATTERN1 ...)</procedure>
116
117Returns a list of the pathnames of all existing files matching
118{{PATTERN1 ...}}, which should be strings containing the usual
119file-patterns (with {{*}} matching zero or more characters and
120{{?}} matching zero or one character).
121
122==== canonical-path
123
124<procedure>(canonical-path NAME)</procedure>
125
126Returns a canonical path for {{NAME}}, which should be a string
127containing a path-or-filename.  The string returned by
128{{canonical-path}} is OS dependent; it may be quoted and used in
129a shell on the calling machine. (Quoting is suggested as shell
130special characters, including space, are not escaped.)  However,
131all path separators and prefixes are handled in an OS independent
132fashion.  Any appearance of {{/}} below imply {{\\}} is also handled.
133
134The prefix for {{NAME}} determines what path to prepend.  If {{NAME}}
135begins with a {{"~/"}}, this prefix is stripped and the user's
136home directory is added.  If beginning with {{/}} or a DRIVE-LETTER:\\
137combination, no additional path is added.  Otherwise, the current
138directory and separator are added.  All relative path elements and
139duplicate separators are processed and removed.  If {{NAME}} ends with
140a {{/}} or is empty, the appropriate slash is appended to the tail.
141
142No directories or files are actually tested for existence; this
143procedure only canonicalises path syntax.
144
145==== set-root-directory!
146
147<procedure>(set-root-directory! STRING)</procedure>
148
149Sets the root directory for the current process to the path given in {{STRING}}
150(using the {{chroot}} function).
151If the current process has no root permissions, the operation will fail.
152
153
154=== Pipes
155
156==== call-with-input-pipe
157==== call-with-output-pipe
158
159<procedure>(call-with-input-pipe CMDLINE PROC [MODE])</procedure>
160<procedure>(call-with-output-pipe CMDLINE PROC [MODE])</procedure>
161
162Call {{PROC}} with a single argument: a input- or output port
163for a pipe connected to the subprocess named in {{CMDLINE}}. If
164{{PROC}} returns normally, the pipe is closed and any result values
165are returned.
166
167==== close-input-pipe
168==== close-output-pipe
169
170<procedure>(close-input-pipe PORT)</procedure>
171<procedure>(close-output-pipe PORT)</procedure>
172
173Closes the pipe given in {{PORT}} and waits until the connected
174subprocess finishes. The exit-status code of the invoked process
175is returned.
176
177==== create-pipe
178
179<procedure>(create-pipe)</procedure>
180
181The fundamental pipe-creation operator. Calls the C function
182{{pipe()}} and returns 2 values: the file-descriptors of the input-
183and output-ends of the pipe.
184
185==== open-input-pipe
186
187<procedure>(open-input-pipe CMDLINE [MODE])</procedure>
188
189Spawns a subprocess with the command-line string {{CMDLINE}} and
190returns a port, from which the output of the process can be read. If
191{{MODE}} is specified, it should be the keyword {{#:text}}
192(the default) or {{#:binary}}.
193
194==== open-output-pipe
195
196<procedure>(open-output-pipe CMDLINE [MODE])</procedure>
197
198Spawns a subprocess with the command-line string {{CMDLINE}} and
199returns a port. Anything written to that port is treated as the input
200for the process.  If {{MODE}} is specified, it should be the keyword
201{{#:text}} (the default) or {{#:binary}}.
202
203==== pipe/buf
204This variable contains the maximal number of bytes that can be written
205atomically into a pipe or FIFO.
206
207==== with-input-from-pipe
208==== with-output-to-pipe
209
210<procedure>(with-input-from-pipe CMDLINE THUNK [MODE])</procedure>
211<procedure>(with-output-to-pipe CMDLINE THUNK [MODE])</procedure>
212
213Temporarily set the value of
214{{current-input-port/current-output-port}} to a port for a
215pipe connected to the subprocess named in {{CMDLINE}} and call
216the procedure {{THUNK}} with no arguments. After {{THUNK}}
217returns normally the pipe is closed and the standard input-/output port
218is restored to its previous value and any result values are returned.
219
220<enscript highlight=scheme>
221(with-output-to-pipe
222  "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
223  (lambda ()
224    (print #<<EOF
225 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
226 /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
227 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
228 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
229 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
230 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
231 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
232 V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J
233 cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
234 EOF
235 ) ) )
236</enscript>
237
238
239=== Fifos
240
241==== create-fifo
242
243<procedure>(create-fifo FILENAME [MODE])</procedure>
244
245Creates a FIFO with the name {{FILENAME}} and the permission bits
246{{MODE}}, which defaults to
247
248<enscript highlight=scheme>
249 (+ perm/irwxu perm/irwxg perm/irwxo)
250</enscript>
251
252==== fifo?
253
254<procedure>(fifo? FILENAME)</procedure>
255
256Returns {{#t}} if the file with the name {{FILENAME}} names
257a FIFO.
258
259
260=== File descriptors and low-level I/O
261
262==== duplicate-fileno
263
264<procedure>(duplicate-fileno OLD [NEW])</procedure>
265
266If {{NEW}} is given, then the file-descriptor {{NEW}} is opened
267to access the file with the file-descriptor {{OLD}}. Otherwise a
268fresh file-descriptor accessing the same file as {{OLD}} is returned.
269
270==== file-close
271
272<procedure>(file-close FILENO)</procedure>
273
274Closes the input/output file with the file-descriptor {{FILENO}}.
275
276==== file-open
277
278<procedure>(file-open FILENAME FLAGS [MODE])</procedure>
279
280Opens the file specified with the string {{FILENAME}} and open-flags
281{{FLAGS}} using the C function {{open()}}. On success a
282file-descriptor for the opened file is returned.  {{FLAGS}}
283should be a bitmask containing one or more of the {{open/...}}
284values '''or'''ed together using {{bitwise-ior}} (or simply added
285together).  The optional {{MODE}} should be a bitmask composed of one
286or more permission values like {{perm/irusr}} and is only relevant
287when a new file is created. The default mode is
288{{perm/irwxu | perm/irgrp | perm/iroth}}.
289
290==== file-mkstemp
291
292<procedure>(file-mkstemp TEMPLATE-FILENAME)</procedure>
293
294Create a file based on the given {{TEMPLATE-FILENAME}}, in which
295the six last characters must be ''XXXXXX''.  These will be replaced
296with a string that makes the filename unique.  The file descriptor of
297the created file and the generated filename is returned.  See the
298{{mkstemp(3)}} manual page for details on how this function
299works.  The template string given is not modified.
300
301Example usage:
302
303<enscript highlight=scheme>
304 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
305  (let ((temp-port (open-output-file* fd)))
306    (format temp-port "This file is ~A.~%" temp-path)
307    (close-output-port temp-port)))
308</enscript>
309
310==== file-read
311
312<procedure>(file-read FILENO SIZE [BUFFER])</procedure>
313
314Reads {{SIZE}} bytes from the file with the file-descriptor
315{{FILENO}}.  If a string or bytevector is passed in the optional
316argument {{BUFFER}}, then this string will be destructively modified
317to contain the read data. This procedure returns a list with two values:
318the buffer containing the data and the number of bytes read.
319
320==== file-select
321
322<procedure>(file-select READFDLIST WRITEFDLIST [TIMEOUT])</procedure>
323
324Waits until any of the file-descriptors given in the lists
325{{READFDLIST}} and {{WRITEFDLIST}} is ready for input or
326output, respectively. If the optional argument {{TIMEOUT}} is
327given and not false, then it should specify the number of seconds after
328which the wait is to be aborted (the value may be a floating point
329number). This procedure returns two values:
330the lists of file-descriptors ready for input and output, respectively.
331{{READFDLIST}} and '''WRITEFDLIST''' may also by file-descriptors
332instead of lists.  In this case the returned values are booleans
333indicating whether input/output is ready by {{#t}} or {{#f}}
334otherwise.  You can also pass {{#f}} as {{READFDLIST}} or
335{{WRITEFDLIST}} argument, which is equivalent to {{()}}.
336
337==== file-write
338
339<procedure>(file-write FILENO BUFFER [SIZE])</procedure>
340
341Writes the contents of the string or bytevector {{BUFFER}} into
342the file with the file-descriptor {{FILENO}}. If the optional
343argument {{SIZE}} is given, then only the specified number of bytes
344are written.
345
346==== file-control
347
348<procedure>(file-control FILENO COMMAND [ARGUMENT])</procedure>
349
350Performs the fcntl operation {{COMMAND}} with the given
351{{FILENO}} and optional {{ARGUMENT}}. The return value is
352meaningful depending on the {{COMMAND}}.
353
354==== open-input-file*
355==== open-output-file*
356
357<procedure>(open-input-file* FILENO [OPENMODE])</procedure>
358<procedure>(open-output-file* FILENO [OPENMODE])</procedure>
359
360Opens file for the file-descriptor {{FILENO}} for input or output
361and returns a port.  {{FILENO}} should be a positive exact integer.
362{{OPENMODE}} specifies an additional mode for opening the file
363(currently only the keyword {{#:append}} is supported, which opens
364an output-file for appending).
365
366==== port->fileno
367
368<procedure>(port->fileno PORT)</procedure>
369
370If {{PORT}} is a file- or tcp-port, then a file-descriptor is returned for
371this port. Otherwise an error is signaled.
372
373
374=== Retrieving file attributes
375
376==== file-access-time
377==== file-change-time
378==== file-modification-time
379
380<procedure>(file-access-time FILE)</procedure>
381<procedure>(file-change-time FILE)</procedure>
382<procedure>(file-modification-time FILE)</procedure>
383
384Returns time (in seconds) of the last access, modification or change of {{FILE}}. {{FILE}}
385may be a filename or a file-descriptor. If the file does not exist,
386an error is signaled.
387
388==== file-stat
389
390<procedure>(file-stat FILE [LINK])</procedure>
391
392Returns a 13-element vector with the following contents: inode-number,
393mode (as with {{file-permissions}}), number of hard links, uid of
394owner (as with {{file-owner}}), gid of owner, size (as with
395{{file-size}}) and access-, change- and modification-time (as with
396{{file-access-time}}, {{file-change-time}} and
397{{file-modification-time}}, device id, device type (for special file
398inode, blocksize and blocks allocated.  On Windows systems the last 4
399values are undefined.  If the optional argument {{LINK}} is given and
400not {{#f}}, then the file-statistics vector will be resolved for
401symbolic links (otherwise symbolic links are not resolved).
402Note that for very large files, the {{file-size}} value may be an
403inexact integer.
404
405==== file-position
406
407<procedure>(file-position FILE)</procedure>
408<procedure>(set! (file-position FILE) POSITION)</procedure>
409
410{{file-position}} Returns the current file position of {{FILE}}, which should be a
411port or a file-descriptor.
412
413{{(set! (file-position FILE) POSITION)}} Sets the current read/write position of {{FILE}} to
414{{POSITION}}, which should be an exact integer or a list of two elements. {{FILE}}
415should be a port or a file-descriptor. If {{POSITION}} is a list, it should
416be of the form {{(POSITION WHENCE)}} where {{WHENCE}} specifies
417how the position is to interpreted and should be one of the values
418{{seek/set, seek/cur}} and {{seek/end}}. It defaults to
419{{seek/set}}.
420
421Exceptions: {{(exn bounds)}}, {{(exn i/o file)}}
422
423
424==== file-size
425
426<procedure>(file-size FILENAME)</procedure>
427
428Returns the size of the file designated by {{FILE}}.  {{FILE}}
429may be a filename or a file-descriptor.  If the file does not exist,
430an error is signaled. Note that for very large files, {{file-size}} may
431return an inexact integer.
432
433==== regular-file?
434
435<procedure>(regular-file? FILENAME)</procedure>
436
437Returns true, if {{FILENAME}} names a regular file (not a directory or symbolic link).
438
439==== file-owner
440
441<procedure>(file-owner FILE)</procedure>
442
443Returns the user-id of {{FILE}}.  {{FILE}} may be a filename
444or a file-descriptor.
445
446==== file-permissions
447
448<procedure>(file-permissions FILE)</procedure>
449
450Returns the permission bits for {{FILE}}. You can test this value
451by performing bitwise operations on the result and the {{perm/...}}
452values.  {{FILE}} may be a filename or a file-descriptor.
453
454==== file-read-access?
455==== file-write-access?
456==== file-execute-access?
457
458<procedure>(file-read-access? FILENAME)</procedure>
459<procedure>(file-write-access? FILENAME)</procedure>
460<procedure>(file-execute-access? FILENAME)</procedure>
461
462These procedures return {{#t}} if the current user has read,
463write or execute permissions on the file named {{FILENAME}}.
464
465
466==== stat-regular?
467==== stat-directory?
468==== stat-char-device?
469==== stat-block-device?
470==== stat-fifo?
471==== stat-symlink?
472==== stat-socket?
473
474<procedure>(stat-regular? FILENAME)</procedure>
475<procedure>(stat-directory? FILENAME)</procedure>
476<procedure>(stat-char-device? FILENAME)</procedure>
477<procedure>(stat-block-device? FILENAME)</procedure>
478<procedure>(stat-fifo? FILENAME)</procedure>
479<procedure>(stat-symlink? FILENAME)</procedure>
480<procedure>(stat-socket? FILENAME)</procedure>
481
482These procedures return {{#t}} if the {{FILENAME}} given is of the
483appropriate type.
484
485
486=== Changing file attributes
487
488==== file-truncate
489
490<procedure>(file-truncate FILE OFFSET)</procedure>
491
492Truncates the file {{FILE}} to the length {{OFFSET}},
493which should be an integer. If the file-size is smaller or equal to
494{{OFFSET}} then nothing is done.  {{FILE}} should be a filename
495or a file-descriptor.
496
497==== change-file-mode
498
499<procedure>(change-file-mode FILENAME MODE)</procedure>
500
501Changes the current file mode of the file named {{FILENAME}}
502to {{MODE}} using the {{chmod()}} system call.  The
503{{perm/...}} variables contain the various permission bits and can
504be combinded with the {{bitwise-ior}} procedure.
505
506==== change-file-owner
507
508<procedure>(change-file-owner FILENAME UID GID)</procedure>
509
510Changes the owner information of the file named {{FILENAME}} to
511the user- and group-ids {{UID}} and {{GID}} (which should be
512exact integers) using the {{chown()}} system call.
513
514
515=== Processes
516
517==== current-process-id
518
519<procedure>(current-process-id)</procedure>
520
521Returns the process ID of the current process.
522
523==== parent-process-id
524
525<procedure>(parent-process-id)</procedure>
526
527Returns the process ID of the parent of the current process.
528
529==== process-group-id
530
531<procedure>(process-group-id PID)</procedure>
532
533Returns the process group ID of the process specified by {{PID}}.
534
535==== process-execute
536
537<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]])</procedure>
538
539Creates a new child process and replaces the running process with it
540using the C library function {{execvp(3)}}. If the optional argument
541{{ARGUMENT-LIST}} is given, then it should contain a list of strings which
542are passed as arguments to the subprocess. If the optional argument
543{{ENVIRONMENT-LIST}} is supplied, then the library function {{execve(2)}}
544is used, and the environment passed in {{ENVIRONMENT-LIST}} (which should
545be of the form {{("<NAME>=<VALUE>" ...)}} is given
546to the invoked process. Note that {{execvp(3)}} respects the current setting
547of the {{PATH}} environment variable while {{execve(3)}} does not.
548
549==== process-fork
550
551<procedure>(process-fork [THUNK])</procedure>
552
553Creates a new child process with the UNIX system call
554{{fork()}}. Returns either the PID of the child process or 0. If
555{{THUNK}} is given, then the child process calls it as a procedure
556with no arguments and terminates.
557
558==== process-run
559
560<procedure>(process-run COMMANDLINE])</procedure>
561<procedure>(process-run COMMAND ARGUMENT-LIST)</procedure>
562
563Creates a new child process. The PID of the new process is returned.
564
565* The single parameter version passes the {{COMMANDLINE}} to the system shell, so usual
566argument expansion can take place.
567* The multiple parameter version directly invokes the {{COMMAND}} with the {{ARGUMENT-LIST}}.
568
569==== process-signal
570
571<procedure>(process-signal PID [SIGNAL])</procedure>
572
573Sends {{SIGNAL}} to the process with the id {{PID}} using the
574UNIX system call {{kill()}}. {{SIGNAL}} defaults to the value
575of the variable {{signal/term}}.
576
577==== process-wait
578
579<procedure>(process-wait [PID [NOHANG]])</procedure>
580
581Suspends the current process until the child process with
582the id {{PID}} has terminated using the UNIX system call
583{{waitpid()}}. If {{PID}} is not given, then this procedure
584waits for any child process. If {{NOHANG}} is given and not
585{{#f}} then the current process is not suspended.  This procedure
586returns three values:
587
588* {{PID}} or 0, if {{NOHANG}} is true and the child process has not terminated yet.
589* {{#t}} if the process exited normally or {{#f}} otherwise.
590* either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.
591
592==== process
593
594<procedure>(process COMMANDLINE)</procedure>
595<procedure>(process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])</procedure>
596
597Creates a subprocess and returns three values: an input port from
598which data written by the sub-process can be read, an output port from
599which any data written to will be received as input in the sub-process
600and the process-id of the started sub-process. Blocking reads and writes
601to or from the ports returned by {{process}} only block the current
602thread, not other threads executing concurrently.
603
604* The single parameter version passes the string {{COMMANDLINE}} to the host-system's shell that
605is invoked as a subprocess.
606* The multiple parameter version directly invokes the {{COMMAND}} as a subprocess. The {{ARGUMENT-LIST}}
607is directly passed, as is {{ENVIRONMENT-LIST}}.
608
609Not using the shell may be preferrable for security reasons.
610
611==== process*
612
613<procedure>(process* COMMANDLINE)</procedure>
614<procedure>(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])</procedure>
615
616Like {{process}} but returns 4 values: an input port from
617which data written by the sub-process can be read, an output port from
618which any data written to will be received as input in the sub-process,
619the process-id of the started sub-process, and an input port from
620which data written by the sub-process to {{stderr}} can be read.
621
622==== sleep
623
624<procedure>(sleep SECONDS)</procedure>
625
626Puts the process to sleep for {{SECONDS}}. Returns either 0 if
627the time has completely elapsed, or the number of remaining seconds,
628if a signal occurred.
629
630==== create-session
631
632<procedure>(create-session)</procedure>
633
634Creates a new session if the calling process is not a process group leader and returns
635the session ID.
636
637
638=== Hard and symbolic links
639
640==== symbolic-link?
641
642<procedure>(symbolic-link? FILENAME)</procedure>
643
644Returns true, if {{FILENAME}} names a symbolic link.
645
646==== create-symbolic-link
647
648<procedure>(create-symbolic-link OLDNAME NEWNAME)</procedure>
649
650Creates a symbolic link with the filename {{NEWNAME}} that points
651to the file named {{OLDNAME}}.
652
653==== read-symbolic-link
654
655<procedure>(read-symbolic-link FILENAME)</procedure>
656
657Returns the filename to which the symbolic link {{FILENAME}} points.
658
659==== file-link
660
661<procedure>(file-link OLDNAME NEWNAME)</procedure>
662
663Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).
664
665
666=== Retrieving user & group information
667
668==== current-user-id
669
670<procedure>(current-user-id)</procedure>
671 [setter] (set! (current-user-id) UID)
672
673Get or set the real user-id of the current process.
674
675==== current-effective-user-id
676
677<procedure>(current-effective-user-id)</procedure>
678 [setter] (set! (current-effective-user-id) UID)
679
680Get or set the effective user-id of the current process.
681
682==== user-information
683
684<procedure>(user-information USER [AS-VECTOR])</procedure>
685
686If {{USER}} specifes a valid username (as a string) or user ID, then the user
687database is consulted and a list of 7 values are returned: the user-name, the
688encrypted password, the user ID, the group ID, a user-specific string, the home
689directory and the default shell. When {{AS-VECTOR}} is {{#t}} a vector of 7
690elements is returned instead of a list. If no user with this name or id then
691{{#f}} is returned.
692
693==== current-group-id
694
695<procedure>(current-group-id)</procedure>
696 [setter] (set! (current-group-id) GID)
697
698Get or set the real group-id of the current process.
699
700==== current-effective-group-id
701
702<procedure>(current-effective-group-id)</procedure>
703 [setter] (set! (current-effective-group-id) GID)
704
705Get or set the effective group-id of the current process.
706ID can be found, then {{#f}} is returned.
707
708==== group-information
709
710<procedure>(group-information GROUP)</procedure>
711
712If {{GROUP}} specifies a valid group-name or group-id, then this
713procedure returns a list of four values: the group-name, the encrypted group password,
714the group ID and a list of the names of all group members. If no group with the
715given name or ID exists, then {{#f}} is returned.
716
717==== get-groups
718
719<procedure>(get-groups)</procedure>
720
721Returns a list with the supplementary group IDs of the current user.
722
723
724=== Changing user & group information
725
726==== set-groups!
727
728<procedure>(set-groups! GIDLIST)</procedure>
729
730Sets the supplementrary group IDs of the current user to the IDs given in the list {{GIDLIST}}.
731
732Only the superuser may invoke this procedure.
733
734==== initialize-groups
735
736<procedure>(initialize-groups USERNAME BASEGID)</procedure>
737
738Sets the supplementrary group IDs of the current user to the IDs from the user with name {{USERNAME}}
739(a string), including {{BASEGID}}.
740
741Only the superuser may invoke this procedure.
742
743==== set-process-group-id!
744
745<procedure>(set-process-group-id! PID PGID)</procedure>
746 [setter] (set! (process-group-id PID) PGID)
747
748Sets the process group ID of the process specifed by {{PID}} to {{PGID}}.
749
750
751=== Record locking
752
753==== file-lock
754
755<procedure>(file-lock PORT [START [LEN]])</procedure>
756
757Locks the file associated with {{PORT}} for reading or
758writing (according to whether {{PORT}} is an input- or
759output-port). {{START}} specifies the starting position in the
760file to be locked and defaults to 0. {{LEN}} specifies the length
761of the portion to be locked and defaults to {{#t}}, which means
762the complete file. {{file-lock}} returns a ''lock''-object.
763
764==== file-lock/blocking
765
766<procedure>(file-lock/blocking PORT [START [LEN]])</procedure>
767
768Similar to {{file-lock}}, but if a lock is held on the file,
769the current process blocks (including all threads) until the lock is released.
770
771==== file-test-lock
772
773<procedure>(file-test-lock PORT [START [LEN]])</procedure>
774
775Tests whether the file associated with {{PORT}} is locked for reading
776or writing (according to whether {{PORT}} is an input- or output-port)
777and returns either {{#f}} or the process-id of the locking process.
778
779==== file-unlock
780
781<procedure>(file-unlock LOCK)</procedure>
782
783Unlocks the previously locked portion of a file given in {{LOCK}}.
784
785
786=== Signal handling
787
788==== set-alarm!
789
790<procedure>(set-alarm! SECONDS)</procedure>
791
792Sets an internal timer to raise the {{signal/alrm}}
793after {{SECONDS}} are elapsed.  You can use the
794{{set-signal-handler!}} procedure to write a handler for this signal.
795
796==== set-signal-handler!
797
798<procedure>(set-signal-handler! SIGNUM PROC)</procedure>
799
800Establishes the procedure of one argument {{PROC}} as the handler
801for the signal with the code {{SIGNUM}}. {{PROC}} is called
802with the signal number as its sole argument. If the argument {{PROC}} is {{#f}}
803then any signal handler will be removed, and the corresponding signal set to {{SIG_IGN}}.
804
805Note that is is unspecified in which thread of execution the signal handler will be invoked.
806
807==== signal-handler
808
809<procedure>(signal-handler SIGNUM)</procedure>
810
811Returns the signal handler for the code {{SIGNUM}} or {{#f}}.
812
813==== set-signal-mask!
814
815<procedure>(set-signal-mask! SIGLIST)</procedure>
816
817Sets the signal mask of the current process to block all signals given
818in the list {{SIGLIST}}.  Signals masked in that way will not be
819delivered to the current process.
820
821==== signal-mask
822
823<procedure>(signal-mask)</procedure>
824
825Returns the signal mask of the current process.
826
827==== signal-masked?
828
829<procedure>(signal-masked? SIGNUM)</procedure>
830
831Returns whether the signal for the code {{SIGNUM}} is currently masked.
832
833==== signal-mask!
834
835<procedure>(signal-mask! SIGNUM)</procedure>
836
837Masks (blocks) the signal for the code {{SIGNUM}}.
838
839==== signal-unmask!
840
841<procedure>(signal-unmask! SIGNUM)</procedure>
842
843Unmasks (unblocks) the signal for the code {{SIGNUM}}.
844
845==== signal/term
846==== signal/kill
847==== signal/int
848==== signal/hup
849==== signal/fpe
850==== signal/ill
851==== signal/segv
852==== signal/abrt
853==== signal/trap
854==== signal/quit
855==== signal/alrm
856==== signal/vtalrm
857==== signal/prof
858==== signal/io
859==== signal/urg
860==== signal/chld
861==== signal/cont
862==== signal/stop
863==== signal/tstp
864==== signal/pipe
865==== signal/xcpu
866==== signal/xfsz
867==== signal/usr1
868==== signal/usr2
869==== signal/winch
870
871These variables contain signal codes for use with {{process-signal}},  {{set-signal-handler!}},  {{signal-handler}},  {{signal-masked?}},  {{signal-mask!}},  or {{signal-unmask!}}.
872
873
874=== Environment access
875
876==== current-environment
877
878 [procedure] (get-environment-variables)
879
880Returns a association list of the environment variables and their
881current values (see also [[http://srfi.schemers.org/srfi-98/|SRFI-98]]).
882
883==== setenv
884
885<procedure>(setenv VARIABLE VALUE)</procedure>
886
887Sets the environment variable named {{VARIABLE}} to
888{{VALUE}}. Both arguments should be strings. If the variable is
889not defined in the environment, a new definition is created.
890
891==== unsetenv
892
893<procedure>(unsetenv VARIABLE)</procedure>
894
895Removes the definition of the environment variable {{VARIABLE}} from
896the environment of the current process. If the variable is not defined,
897nothing happens.
898
899
900=== Memory mapped I/O
901
902==== memory-mapped-file?
903
904 [pocedure] (memory-mapped-file? X)
905
906Returns {{#t}}, if {{X}} is an object representing a memory
907mapped file, or {{#f}} otherwise.
908
909==== map-file-to-memory
910
911<procedure>(map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])</procedure>
912
913Maps a section of a file to memory using the C function
914{{mmap()}}.  {{ADDRESS}} should be a foreign pointer object
915or {{#f}}; {{LEN}} specifies the size of the section to
916be mapped; {{PROTECTION}} should be one or more of the flags
917{{prot/read, prot/write, prot/exec}} or {{prot/none}}
918'''bitwise-ior'''ed together; {{FLAG}} should be one or more of
919the flags {{map/fixed, map/shared, map/private, map/anonymous}} or
920{{map/file}}; {{FILENO}} should be the file-descriptor of the
921mapped file. The optional argument {{OFFSET}} gives the offset of
922the section of the file to be mapped and defaults to 0. This procedure
923returns an object representing the mapped file section.  The procedure
924{{move-memory!}} can be used to access the mapped memory.
925
926==== memory-mapped-file-pointer
927
928<procedure>(memory-mapped-file-pointer MMAP)</procedure>
929
930Returns a machine pointer to the start of the memory region to which
931the file is mapped.
932
933==== unmap-file-from-memory
934
935<procedure>(unmap-file-from-memory MMAP [LEN])</procedure>
936
937Unmaps the section of a file mapped to memory using the C function
938{{munmap()}}.  {{MMAP}} should be a mapped file as returned
939by the procedure {{map-file-to-memory}}.  The optional argument
940{{LEN}} specifies the length of the section to be unmapped and
941defaults to the complete length given when the file was mapped.
942
943
944=== Date and time routines
945
946==== seconds->local-time
947
948<procedure>(seconds->local-time SECONDS)</procedure>
949
950Breaks down the time value represented in {{SECONDS}} into a 10
951element vector of the form {{#(seconds minutes hours mday month
952year wday yday dstflag timezone)}}, in the following format:
953
954; seconds (0) : the number of seconds after the minute (0 - 59)
955; minutes (1) : the number of minutes after the hour (0 - 59)
956; hours (2) : the number of hours past midnight (0 - 23)
957; mday (3) : the day of the month (1 - 31)
958; month (4) : the number of months since january (0 - 11)
959; year (5) : the number of years since 1900
960; wday (6) : the number of days since Sunday (0 - 6)
961; yday (7) : the number of days since January 1 (0 - 365)
962; dstflag (8) : a flag that is true if Daylight Saving Time is in effect at the time described.
963; timezone (9) : the difference between UTC and the latest local standard time, in seconds west of UTC.
964
965==== local-time->seconds
966
967<procedure>(local-time->seconds VECTOR)</procedure>
968
969Converts the ten-element vector {{VECTOR}} representing the time value relative to
970the current timezone into
971the number of seconds since the first of January, 1970 UTC.
972
973==== local-timezone-abbreviation
974
975<procedure>(local-timezone-abbreviation)</procedure>
976
977Returns the abbreviation for the local timezone as a string.
978
979==== seconds->string
980
981<procedure>(seconds->string SECONDS)</procedure>
982
983Converts the local time represented in {{SECONDS}} into a string
984of the form {{"Tue May 21 13:46:22 1991"}}.
985
986==== seconds->utc-time
987
988<procedure>(seconds->utc-time SECONDS)</procedure>
989
990Similar to {{seconds->local-time}}, but interpretes {{SECONDS}}
991as UTC time.
992
993==== utc-time->seconds
994
995<procedure>(utc-time->seconds VECTOR)</procedure>
996
997Converts the ten-element vector {{VECTOR}} representing the UTC time value into
998the number of seconds since the first of January, 1970 UTC.
999
1000==== time->string
1001
1002<procedure>(time->string VECTOR)</procedure>
1003
1004Converts the broken down time represented in the 10 element vector
1005{{VECTOR}} into a string of the form represented by the {{FORMAT}}
1006string. The default time form produces something like {{"Tue May 21 13:46:22 1991"}}.
1007
1008The {{FORMAT}} string follows the rules for the C library procedure {{strftime}}. The default {{FORMAT}} string is "%a %b %e %H:%M:%S %Z %Y".
1009
1010==== string->time
1011
1012 [procedure] (string->time TIME [FORMAT])
1013
1014Converts a string of the form represented by the {{FORMAT}} string
1015into the broken down time represented in a 10 element vector. The
1016default time form understands something like {{"Tue May 21 13:46:22 1991"}}.
1017
1018The {{FORMAT}} string follows the rules for the C library procedure {{strptime}}. The default {{FORMAT}} string is "%a %b %e %H:%M:%S %Z %Y".
1019
1020
1021=== Raw exit
1022
1023==== _exit
1024
1025<procedure>(_exit [CODE])</procedure>
1026
1027Exits the current process without flushing any buffered output (using
1028the C function {{_exit}}).  Note that the {{exit-handler}}
1029is not called when this procedure is invoked. The optional return-code
1030{{CODE}} defaults to {{0}}.
1031
1032
1033=== ERRNO values
1034
1035==== errno/perm
1036==== errno/noent
1037==== errno/srch
1038==== errno/intr
1039==== errno/io
1040==== errno/noexec
1041==== errno/badf
1042==== errno/child
1043==== errno/nomem
1044==== errno/acces
1045==== errno/fault
1046==== errno/busy
1047==== errno/notdir
1048==== errno/isdir
1049==== errno/inval
1050==== errno/mfile
1051==== errno/nospc
1052==== errno/spipe
1053==== errno/pipe
1054==== errno/again
1055==== errno/rofs
1056==== errno/exist
1057==== errno/wouldblock
1058These variables contain error codes as returned by {{errno}}.
1059
1060
1061=== Finding files
1062
1063==== find-files
1064
1065<procedure>(find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])</procedure>
1066
1067Recursively traverses the contents of {{DIRECTORY}} (which should
1068be a string) and invokes the procedure {{ACTION}} for all files
1069in which the procedure {{PREDICATE}} is true.  {{PREDICATE}}
1070may me a procedure of one argument or a regular-expression string.
1071{{ACTION}} should be a procedure of two arguments: the currently
1072encountered file and the result of the previous invocation of
1073{{ACTION}}, or, if this is the first invocation, the value
1074of {{IDENTITY}}. {{ACTION}} defaults to {{cons}},
1075{{IDENTITY}} defaults to {{()}}.  {{LIMIT}} should be a
1076procedure of one argument that is called for each nested directory
1077and which should return true, if that directory is to be traversed
1078recursively. {{LIMIT}} may also be an exact integer that
1079gives the maximum recursion depth. For example, a depth of {{0}} means that only files in the top-level, specified directory are to be traversed. In this case, all nested directories are ignored.  {{LIMIT}} may also be {{#f}} (the default),
1080which is equivalent to {{(constantly #t)}}.
1081
1082Note that {{ACTION}} is called with the full pathname of each file,
1083including the directory prefix.
1084
1085
1086=== Getting the hostname and system information
1087
1088==== get-host-name
1089
1090<procedure>(get-host-name)</procedure>
1091
1092Returns the hostname of the machine that this process is running on.
1093
1094==== system-information
1095
1096<procedure>(system-information)</procedure>
1097
1098Invokes the UNIX system call {{uname()}} and returns a list of 5 values:
1099system-name, node-name, OS release, OS version and machine.
1100
1101=== Setting the file buffering mode
1102
1103==== set-buffering-mode!
1104
1105<procedure>(set-buffering-mode! PORT MODE [BUFSIZE])</procedure>
1106
1107Sets the buffering-mode for the file associated with {{PORT}} to
1108{{MODE}}, which should be one of the keywords {{#:full}},
1109{{#:line}} or {{#:none}}. If {{BUFSIZE}} is specified it
1110determines the size of the buffer to be used (if any).
1111
1112
1113=== Terminal ports
1114
1115==== terminal-name
1116
1117<procedure>(terminal-name PORT)</procedure>
1118
1119Returns the name of the terminal that is connected to {{PORT}}.
1120
1121==== terminal-port?
1122
1123<procedure>(terminal-port? PORT)</procedure>
1124
1125Returns {{#t}} if {{PORT}} is connected to a terminal and
1126{{#f}} otherwise.
1127
1128
1129==== terminal-size
1130
1131 [procedure] (terminal-size)
1132
1133Returns two values, the number of columns and rows of the
1134current terminal window or {{0}}, {{0}} if the terminal
1135size can not be obtained. On Windows, this procedure
1136always returns {{0}, {{0}}.
1137
1138
1139=== How Scheme procedures relate to UNIX C functions
1140
1141; {{change-directory}} : {{chdir}}
1142; {{change-file-mode}} : {{chmod}}
1143; {{change-file-owner}} : {{chown}}
1144; {{create-directory}} : {{mkdir}}
1145; {{create-fifo}} : {{mkfifo}}
1146; {{create-pipe}} : {{pipe}}
1147; {{create-session}} : {{setsid}}
1148; {{create-symbolic-link}} : {{link}}
1149; {{current-directory}} : {{curdir}}
1150; {{current-effective-groupd-id}} : {{getegid}}
1151; {{current-effective-user-id}} : {{geteuid}}
1152; {{current-group-id}} : {{getgid}}
1153; {{current-parent-id}} : {{getppid}}
1154; {{current-process-id}} : {{getpid}}
1155; {{current-user-id}} : {{getuid}}
1156; {{delete-directory}} : {{rmdir}}
1157; {{duplicate-fileno}} : {{dup/dup2}}
1158; {{_exit}} : {{_exit}}
1159; {{file-close}} : {{close}}
1160; {{file-access-time}} : {{stat}}
1161; {{file-change-time}} : {{stat}}
1162; {{file-modification-time}} : {{stat}}
1163; {{file-execute-access?}} : {{access}}
1164; {{file-open}} : {{open}}
1165; {{file-lock}} : {{fcntl}}
1166; {{file-position}} : {{ftell/lseek}}
1167; {{file-read}} : {{read}}
1168; {{file-read-access?}} : {{access}}
1169; {{file-select}} : {{select}}
1170; {{file-control}} : {{fcntl}}
1171; {{file-stat}} : {{stat}}
1172; {{file-test-lock}} : {{fcntl}}
1173; {{file-truncate}} : {{truncate/ftruncate}}
1174; {{file-unlock}} : {{fcntl}}
1175; {{file-write}} : {{write}}
1176; {{file-write-access?}} : {{access}}
1177; {{get-groups}} : {{getgroups}}
1178; {{get-host-name}} : {{gethostname}}
1179; {{initialize-groups}} : {{initgroups}}
1180; {{local-time->seconds}} : {{mktime}}
1181; {{local-timezone-abbreviation}} : {{localtime}}
1182; {{map-file-to-memory}} : {{mmap}}
1183; {{open-input-file*}} : {{fdopen}}
1184; {{open-output-file*}} : {{fdopen}}
1185; {{open-input-pipe}} : {{popen}}
1186; {{open-output-pipe}} : {{popen}}
1187; {{port->fileno}} : {{fileno}}
1188; {{process-execute}} : {{execvp}}
1189; {{process-fork}} : {{fork}}
1190; {{process-group-id}} : {{getpgid}}
1191; {{process-signal}} : {{kill}}
1192; {{process-wait}} : {{waitpid}}
1193; {{close-input-pipe}} : {{pclose}}
1194; {{close-output-pipe}} : {{pclose}}
1195; {{read-symbolic-link}} : {{readlink}}
1196; {{seconds->local-time}} : {{localtime}}
1197; {{seconds->string}} : {{ctime}}
1198; {{seconds->utc-time}} : {{gmtime}}
1199; {{set-alarm!}} : {{alarm}}
1200; {{set-buffering-mode!}} : {{setvbuf}}
1201; {{set-file-position!}} : {{fseek/seek}}
1202; {{set-groups!}} : {{setgroups}}
1203; {{set-signal-mask!}} : {{sigprocmask}}
1204; {{set-group-id!}} : {{setgid}}
1205; {{set-process-group-id!}} : {{setpgid}}
1206; {{set-user-id!}} : {{setuid}}
1207; {{set-root-directory!}} : {{chroot}}
1208; {{setenv}} : {{setenv/putenv}}
1209; {{sleep}} : {{sleep}}
1210; {{system-information}} : {{uname}}
1211; {{terminal-name}} : {{ttyname}}
1212; {{terminal-port?}} : {{isatty}}
1213; {{time->string}} : {{asctime}}
1214; {{unsetenv}} : {{putenv}}
1215; {{unmap-file-from-memory}} : {{munmap}}
1216; {{user-information}} : {{getpwnam/getpwuid}}
1217; {{utc-time->seconds}} : {{timegm}}
1218
1219
1220=== Windows specific notes
1221
1222Use of UTF8 encoded strings is for pathnames is not supported. Windows uses a
122316-bit UNICODE encoding with special system calls for wide-character support.
1224Only single-byte string encoding can be used.
1225
1226==== Procedure Changes
1227
1228Exceptions to the above procedure definitions.
1229
1230<procedure>(create-pipe [MODE])</procedure>
1231
1232The optional parameter {{MODE}}, default {{open/binary | open/noinherit}}. This can be {{open/binary}} or
1233{{open/text}}, optionally or'ed with {{open/noinherit}}.
1234
1235<procedure>(process-wait [PID [NOHANG]])</procedure>
1236
1237{{process-wait}} always returns {{#t}} for a terminated process and only the exit
1238status is available. (Windows does not provide signals as an interprocess
1239communication method.)
1240
1241<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])</procedure>
1242<procedure>(process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])</procedure>
1243<procedure>(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])</procedure>
1244
1245The optional parameter {{EXACT-FLAG}}, default {{#f}}. When {{#f}} any argument string with
1246embedded whitespace will be wrapped in quotes. When {{#t}} no such wrapping occurs.
1247
1248==== Unsupported Definitions
1249
1250The following definitions are not supported for native Windows builds (compiled with the
1251Microsoft tools or with MinGW):
1252
1253 open/noctty  open/nonblock  open/fsync  open/sync
1254 perm/isvtx  perm/isuid  perm/isgid
1255 file-select file-control
1256 signal/... (except signal/term, signal/int, signal/fpe, signal/ill, signal/segv, signal/abrt, signal/break)
1257 set-signal-mask!  signal-mask  signal-masked?  signal-mask!  signal-unmask!
1258 user-information  group-information  get-groups  set-groups!  initialize-groups
1259 errno/wouldblock
1260 change-file-owner
1261 current-user-id  current-group-id  current-effective-user-id  current-effective-groupd-id
1262 set-user-id!  set-group-id!
1263 create-session
1264 process-group-id  set-process-group-id!
1265 create-symbolic-link  read-symbolic-link
1266 file-truncate
1267 file-lock  file-lock/blocking  file-unlock  file-test-lock
1268 create-fifo  fifo?
1269 prot/...
1270 map/...
1271 map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
1272 set-alarm!
1273 terminal-port?  terminal-name
1274 process-fork  process-signal
1275 parent-process-id
1276 set-root-directory!
1277 utc-time->seconds
1278
1279==== Additional Definitions
1280
1281Only available for Windows
1282
1283* open/noinherit
1284
1285This variable is a mode value for {{create-pipe}}. Useful when spawning a child process.
1286
1287* spawn/overlay
1288* spawn/wait
1289* spawn/nowait
1290* spawn/nowaito
1291* spawn/detach
1292
1293These variables contains special flags that specify the exact semantics of {{process-spawn}}:
1294{{spawn/overlay}} replaces the current process with the new one.
1295{{spawn/wait}} suspends execution of the current process until the spawned process returns.
1296{{spawn/nowait}} does the opposite ({{spawn/nowaito}} is identical, according to the Microsoft
1297documentation) and runs the process asynchronously.
1298{{spawn/detach}} runs the new process in the background, without being attached to a console.
1299
1300==== process-spawn
1301
1302<procedure>(process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])</procedure>
1303
1304Creates and runs a new process with the given {{COMMAND}} filename and the optional
1305{{ARGUMENT-LIST}} and {{ENVIRONMENT-LIST}}. {{MODE}} specifies how exactly the process
1306should be executed and must be one or more of the {{spawn/...}} flags defined above.
1307
1308The {{EXACT-FLAG}}, default {{#f}}, controls quote-wrapping of argument strings. When {{#t}}
1309quote-wrapping is not performed.
1310
1311Returns:
1312* the exit status when synchronous
1313* the PID when asynchronous
1314* -1 when failure
1315
1316---
1317Previous: [[Unit srfi-69]]
1318
1319Next: [[Unit utils]]
Note: See TracBrowser for help on using the repository browser.