source: project/chicken/branches/prerelease/manual/Unit posix @ 15101

Last change on this file since 15101 was 15101, checked in by felix winkelmann, 10 years ago

merged trunk changes from 14491:15100 into prerelease branch

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